Add userspace config.h handling to build script (#2640)

* Add userspace 'config.h' file

* Add more robust docs

* Remove config.h code from drashna userspace

* Spelling error

* Include links to Config Options page

* Remove config.h documentation from userspace doc, as it's no longer needed
master
Drashna Jaelre 2018-03-31 21:02:40 -07:00 committed by Jack Humbert
parent cc323df9ba
commit 162a67cbc5
4 changed files with 27 additions and 34 deletions

View File

@ -204,6 +204,10 @@ endif
# User space stuff # User space stuff
USER_PATH := users/$(KEYMAP) USER_PATH := users/$(KEYMAP)
-include $(USER_PATH)/rules.mk -include $(USER_PATH)/rules.mk
ifneq ("$(wildcard users/$(KEYMAP)/config.h)","")
CONFIG_H += users/$(KEYMAP)/config.h
endif
# Object files directory # Object files directory
# To put object files in current directory, use a dot (.), do NOT make # To put object files in current directory, use a dot (.), do NOT make

View File

@ -3,10 +3,11 @@
If you use more than one keyboard with a similar keymap, you might see the benefit in being able to share code between them. Create your own folder in `users/` named the same as your keymap (ideally your github username, `<name>`) with the following structure: If you use more than one keyboard with a similar keymap, you might see the benefit in being able to share code between them. Create your own folder in `users/` named the same as your keymap (ideally your github username, `<name>`) with the following structure:
* `/users/<name>/` (added to the path automatically) * `/users/<name>/` (added to the path automatically)
* `readme.md` * `readme.md` (optional, recommended)
* `rules.mk` (included automatically) * `rules.mk` (included automatically)
* `<name>.h` (optional) * `<name>.h` (optional)
* `<name>.c` (optional) * `<name>.c` (optional)
* `config.h` (optional)
`<name>.c` will need to be added to the SRC in `rules.mk` like this: `<name>.c` will need to be added to the SRC in `rules.mk` like this:
@ -24,10 +25,31 @@ For example,
Will include the `/users/jack/` folder in the path, along with `/users/jack/rules.mk`. Will include the `/users/jack/` folder in the path, along with `/users/jack/rules.mk`.
Additionally, `config.h` here will be processed like the same file in your keymap folder. This is handled separately from the `<name>.h` file.
The reason for this, is that `<name>.h` won't be added in time to add settings (such as `#define TAPPING_TERM 100`), and including the `<name.h>` file in any `config.h` files will result in compile issues.
So you should use the `config.h` for QMK settings, and the `<name>.h` file for user or keymap specific settings.
## Readme ## Readme
Please include authorship (your name, github username, email), and optionally [a license that's GPL compatible](https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses). Please include authorship (your name, github username, email), and optionally [a license that's GPL compatible](https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses).
## `Config.h`
If you do add a `config,h` file, you want to make sure that it only gets processed once. So you may want to start off with something like this:
```c
#ifndef USERSPACE_CONFIG_H
#define USERSPACE_CONFIG_H
// Put normal config.h settings here:
#endif // !USERSPACE_CONFIG_H
```
You can use any option hre that you could use in your keymap's `config.h` file. You can find a list of vales [here](config_options.md).
## Example ## Example
For a brief example, checkout `/users/_example/` , or for a more detailed examples check out [`template.h`](https://github.com/qmk/qmk_firmware/blob/master/users/drashna/template.h) and [`template.c`](https://github.com/qmk/qmk_firmware/blob/master/users/drashna/template.c) in `/users/drashna/` . For a brief example, checkout `/users/_example/` , or for a more detailed examples check out [`template.h`](https://github.com/qmk/qmk_firmware/blob/master/users/drashna/template.h) and [`template.c`](https://github.com/qmk/qmk_firmware/blob/master/users/drashna/template.c) in `/users/drashna/` .

View File

@ -3,33 +3,6 @@ Overview
This is my personal userspace file. Most of my code exists here, as it's heavily shared. This is my personal userspace file. Most of my code exists here, as it's heavily shared.
Userspace Config.h
------------------
By default, the userspace feature doesn't include a `config.h` file the way that that keyboards, revisions, keymaps and layouts handle them. This means that if you want global configurations via userspace, it's very difficult to implement.
The reason for using seperate files here is that the `drashna.h` file doesn't get called in such a way that will actually define QMK settings. Additionally, attempting to add it to the `config.h` files has issues. Namely, the `drashna.h` file requires the `quantum.h` file... but including this to the `config.h` attemps to redefines a bunch of settings and breaks the firmare. Removing the `quantum.h` include means that a number of data structures no longer get added, and the `SAFE_RANGE` value is no longer defined, as well. So we need both a `config.h` for global config, and we need a seperate h file for local settings.
However, the `rules.mk` file is included when building the firmware. So we can hijack that process to "manually" add a `config.h`. To do so, you would need to add the following to the `rules.mk` in your userspace:
```c
ifneq ("$(wildcard users/$(KEYMAP)/config.h)","")
CONFIG_H += users/$(KEYMAP)/config.h
endif
```
You can replace `$(KEYMAP)` with your name, but it's not necessary. This checks for the existence of `/users/<name>/config.h`, and if it exists, includes it like every other `config.h` file, allowing you to make global `config.h` settings.
As for the `config.h` file, you want to make sure that it has an "ifdef" in it to make sure it's only used once. So you want something like this:
```c
#ifndef USERSPACE_CONFIG_H
#define USERSPACE_CONFIG_H
// put stuff here
#endif
```
Custom userspace handlers Custom userspace handlers
------------------------- -------------------------

View File

@ -2,10 +2,4 @@
SRC += drashna.c SRC += drashna.c
EXTRAFLAGS += -flto EXTRAFLAGS += -flto
ifneq ("$(wildcard users/$(KEYMAP)/config.h)","")
CONFIG_H += users/$(KEYMAP)/config.h
endif
ifeq ($(strip $(NO_SECRETS)), yes)
OPT_DEFS += -DNO_SECRETS
endif