Implements subprojects and updates projects for this

[jackhumbert]

Subprojects

Subproject folders are located at /keyboards/<keyboard>/<subproject>, and they can be compiled in a couple different ways:

• /keyboards/<keyboard>/ $ make sub=<subproject> (preferred)
• / $ make keyboard=<keyboard>/<subproject>
• /keyboards/<keyboard>/<subproject>/ $ make

Keyboard files

Some modifications to the keyboard files are available:

/keyboards/<keyboard>/Makefile

SUBPROJECT_DEFAULT = <subproject>

can be added to specify a subproject by default. This is not required, but your config.h files should compensation for this.

/keyboards/<keyboard>/config.h

#ifdef SUBPROJECT_<subproject>
    #include "<subproject>/config.h"
#endif

This is required if your keymaps or subprojects have config.hs in them.

/keyboards/<keyboard>/<keyboard>.h

#ifdef SUBPROJECT_<subproject>
    #include "<subproject>.h"
#endif

can be added as a conditional to include the relevant subproject files when necessary.

Subproject files

The basic template for constructing subprojects looks like this:

/keyboards/<keyboard>/<subproject>/config.h

#ifndef <subproject>_CONFIG_H
#define  <subproject>_CONFIG_H

#include "../config.h"

...

#endif

You can use #undef <variable> to override directives here.

/keyboards/<keyboard>/<subproject>/Makefile

...

ifndef QUANTUM_DIR
    include ../../../Makefile
endif

/keyboards/<keyboard>/<subproject>/<subproject>.h

#ifndef <subproject>_H
#define <subproject>_H

#include "../<keyboard>.h"

...

#endif

/keyboards/<keyboard>/<subproject>/<subproject>.c

#include "<subproject>.h"

...

The planck and the clueboard use these by default for revisions.

Travis build script

This script automatically pushes to the qmk.fm repo, and updates all information there. All .hex files are located in that repo, and are generated from these tests.

[fredizzimo]

I'm currently converting the Ergodox to use sub-projects, following the above instructions. Almost all keymaps already compiles for both the Infinity and the EZ, so this far everything is going well.

I think it would be good to add the following to the documentation(once it's properly documented) though
both

#ifdef SUBPROJECT_<subproject>
    #include "<subproject>/config.h"
#endif

and

#ifdef SUBPROJECT_<subproject>
    #include "<subproject>.h"
#endif

Should be at the bottom of the respective keyboard.h or config.h file, as we want to have the following order of parsing. If they are added to the top, then the order will be wrong.

1. Keyboard
2. Subproject
3. Keymap

And the include paths should be set as

1. Keymap
2. Subproject
3. Keyboard

A couple of examples, let's say a keymap has a config file

1. The include search path will find the keymap config.h file
2. It includes the keyboard config.h file
3. The keyboard config.h file is parsed
4. It includes the subproject config.h file
5. The include guard stops the keyboard config.h file from getting included again
6. The subproject config file is parsed
7. The parser gets to the end of the subproject config file and also the keyboard config file
8. The keymap config file is finally parsed.

If there's no keymap config file the following will happen

1. The include search path finds the subproject config file
2. It includes the keyboard config file
3. The keyboard config file is parsed
4. The include guards stops the subproject config file from being included again
5. The parser continues with the rest of the subproject config file