mirror of
https://github.com/qmk/qmk_firmware.git
synced 2026-09-28 15:50:46 +08:00
Create a system to map between info.json and config.h/rules.mk (#11548)
* generate rules.mk from a json mapping * generate rules.mk from a json mapping * support for config.h from json maps * improve the mapping system * document the mapping system * move data/maps to data/mappings * fix flake8 errors * fixup LED_MATRIX_DRIVER * remove product and description from the vision_division keymap level * reduce the complexity of generate-rules-mk * add tests for the generate commands * fix qmk doctor when submodules are not clean
This commit is contained in:
Zach White
@@ -27,7 +27,8 @@ def _check_modules(requirements):
|
||||
line = line.split('#')[0]
|
||||
|
||||
module = dict()
|
||||
module['name'] = module['import'] = line.split('=')[0] if '=' in line else line
|
||||
module['name'] = line.split('=')[0] if '=' in line else line
|
||||
module['import'] = module['name'].replace('-', '_')
|
||||
|
||||
# Not every module is importable by its own name.
|
||||
if module['name'] == "pep8-naming":
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
# This file maps keys between `config.h` and `info.json`. It is used by QMK
|
||||
# to correctly and consistently map back and forth between the two systems.
|
||||
{
|
||||
# Format:
|
||||
# <config.h key>: {"info_key": <info.json key>, ["value_type": <value_type>], ["to_json": <true/false>], ["to_c": <true/false>]}
|
||||
# value_type: one of "array", "array.int", "int", "hex", "list", "mapping"
|
||||
# to_json: Default `true`. Set to `false` to exclude this mapping from info.json
|
||||
# to_c: Default `true`. Set to `false` to exclude this mapping from config.h
|
||||
# warn_duplicate: Default `true`. Set to `false` to turn off warning when a value exists in both places
|
||||
"DEBOUNCE": {"info_key": "debounce", "value_type": "int"}
|
||||
"DEVICE_VER": {"info_key": "usb.device_ver", "value_type": "hex"},
|
||||
"DESCRIPTION": {"info_key": "keyboard_folder", "to_json": false},
|
||||
"DIODE_DIRECTION": {"info_key": "diode_direction"},
|
||||
"LAYOUTS": {"info_key": "layout_aliases", "value_type": "mapping"},
|
||||
"LED_CAPS_LOCK_PIN": {"info_key": "indicators.caps_lock"},
|
||||
"LED_NUM_LOCK_PIN": {"info_key": "indicators.num_lock"},
|
||||
"LED_SCROLL_LOCK_PIN": {"info_key": "indicators.scroll_lock"},
|
||||
"MANUFACTURER": {"info_key": "manufacturer"},
|
||||
"RGB_DI_PIN": {"info_key": "rgblight.pin"},
|
||||
"RGBLED_NUM": {"info_key": "rgblight.led_count", "value_type": "int"},
|
||||
"RGBLED_SPLIT": {"info_key": "rgblight.split_count", "value_type": "array.int"},
|
||||
"RGBLIGHT_ANIMATIONS": {"info_key": "rgblight.animations.all", "value_type": "bool"},
|
||||
"RGBLIGHT_EFFECT_ALTERNATING": {"info_key": "rgblight.animations.alternating", "value_type": "bool"},
|
||||
"RGBLIGHT_EFFECT_BREATHING": {"info_key": "rgblight.animations.breathing", "value_type": "bool"},
|
||||
"RGBLIGHT_EFFECT_CHRISTMAS": {"info_key": "rgblight.animations.christmas", "value_type": "bool"},
|
||||
"RGBLIGHT_EFFECT_KNIGHT": {"info_key": "rgblight.animations.knight", "value_type": "bool"},
|
||||
"RGBLIGHT_EFFECT_RAINBOW_MOOD": {"info_key": "rgblight.animations.rainbow_mood", "value_type": "bool"},
|
||||
"RGBLIGHT_EFFECT_RAINBOW_SWIRL": {"info_key": "rgblight.animations.rainbow_swirl", "value_type": "bool"},
|
||||
"RGBLIGHT_EFFECT_RGB_TEST": {"info_key": "rgblight.animations.rgb_test", "value_type": "bool"},
|
||||
"RGBLIGHT_EFFECT_SNAKE": {"info_key": "rgblight.animations.snake", "value_type": "bool"},
|
||||
"RGBLIGHT_EFFECT_STATIC_GRADIENT": {"info_key": "rgblight.animations.static_gradient", "value_type": "bool"},
|
||||
"RGBLIGHT_EFFECT_TWINKLE": {"info_key": "rgblight.animations.twinkle"},
|
||||
"RGBLIGHT_LIMIT_VAL": {"info_key": "rgblight.max_brightness", "value_type": "int"},
|
||||
"RGBLIGHT_HUE_STEP": {"info_key": "rgblight.hue_steps", "value_type": "int"},
|
||||
"RGBLIGHT_SAT_STEP": {"info_key": "rgblight.saturation_steps", "value_type": "int"},
|
||||
"RGBLIGHT_VAL_STEP": {"info_key": "rgblight.brightness_steps", "value_type": "int"},
|
||||
"RGBLIGHT_SLEEP": {"info_key": "rgblight.sleep", "value_type": "bool"},
|
||||
"RGBLIGHT_SPLIT": {"info_key": "rgblight.split", "value_type": "bool"},
|
||||
"PRODUCT": {"info_key": "keyboard_folder", "to_json": false},
|
||||
"PRODUCT_ID": {"info_key": "usb.pid", "value_type": "hex"},
|
||||
"VENDOR_ID": {"info_key": "usb.vid", "value_type": "hex"}
|
||||
}
|
||||
@@ -0,0 +1,15 @@
|
||||
# This file maps keys between `rules.mk` and `info.json`. It is used by QMK
|
||||
# to correctly and consistently map back and forth between the two systems.
|
||||
{
|
||||
# Format:
|
||||
# <rules.mk key>: {"info_key": <info.json key>, ["value_type": <value_type>], ["to_json": <true/false>], ["to_c": <true/false>]}
|
||||
# value_type: one of "array", "array.int", "int", "list", "hex", "mapping"
|
||||
# to_json: Default `true`. Set to `false` to exclude this mapping from info.json
|
||||
# to_c: Default `true`. Set to `false` to exclude this mapping from rules.mk
|
||||
# warn_duplicate: Default `true`. Set to `false` to turn off warning when a value exists in both places
|
||||
"BOARD": {"info_key": "board"},
|
||||
"BOOTLOADER": {"info_key": "bootloader", "warn_duplicate": false},
|
||||
"LAYOUTS": {"info_key": "community_layouts", "value_type": "list"},
|
||||
"LED_MATRIX_DRIVER": {"info_key": "led_matrix.driver"},
|
||||
"MCU": {"info_key": "processor", "warn_duplicate": false},
|
||||
}
|
||||
@@ -12,17 +12,18 @@ Now we have support for generating `rules.mk` and `config.h` values from `info.j
|
||||
|
||||
## Overview
|
||||
|
||||
On the C side of things nothing really changes. When you need to create a new rule or define you follow the same process:
|
||||
On the C side of things nothing changes. When you need to create a new rule or define you follow the same process:
|
||||
|
||||
1. Add it to `docs/config_options.md`
|
||||
1. Set a default in the appropriate core file
|
||||
1. Add your `ifdef` and/or `#ifdef` statements as needed
|
||||
1. Add your ifdef statements as needed
|
||||
|
||||
You will then need to add support for your new configuration to `info.json`. The basic process is:
|
||||
|
||||
1. Add it to the schema in `data/schemas/keyboards.jsonschema`
|
||||
1. Add code to extract it from `config.h`/`rules.mk` to `lib/python/qmk/info.py`
|
||||
1. Add code to generate it to one of:
|
||||
1. Add a mapping in `data/maps`
|
||||
1. (optional and discoraged) Add code to extract/generate it to:
|
||||
* `lib/python/qmk/info.py`
|
||||
* `lib/python/qmk/cli/generate/config_h.py`
|
||||
* `lib/python/qmk/cli/generate/rules_mk.py`
|
||||
|
||||
@@ -32,12 +33,43 @@ This section describes adding support for a `config.h`/`rules.mk` value to info.
|
||||
|
||||
### Add it to the schema
|
||||
|
||||
QMK maintains schema files in `data/schemas`. The values that go into keyboard-specific `info.json` files are kept in `keyboard.jsonschema`. Any value you want to make available to end users to edit must go in here.
|
||||
QMK maintains [jsonschema](https://json-schema.org/) files in `data/schemas`. The values that go into keyboard-specific `info.json` files are kept in `keyboard.jsonschema`. Any value you want to make available to end users to edit must go in here.
|
||||
|
||||
In some cases you can simply add a new top-level key. Some examples to follow are `keyboard_name`, `maintainer`, `processor`, and `url`. This is appropriate when your option is self-contained and not directly related to other options. In other cases you should group like options together in an `object`. This is particularly true when adding support for a feature. Some examples to follow for this are `indicators`, `matrix_pins`, and `rgblight`. If you are not sure how to integrate your new option(s) [open an issue](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=) or [join #cli on Discord](https://discord.gg/heQPAgy) and start a conversation there.
|
||||
In some cases you can simply add a new top-level key. Some examples to follow are `keyboard_name`, `maintainer`, `processor`, and `url`. This is appropriate when your option is self-contained and not directly related to other options.
|
||||
|
||||
In other cases you should group like options together in an `object`. This is particularly true when adding support for a feature. Some examples to follow for this are `indicators`, `matrix_pins`, and `rgblight`. If you are not sure how to integrate your new option(s) [open an issue](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=) or [join #cli on Discord](https://discord.gg/heQPAgy) and start a conversation there.
|
||||
|
||||
### Add a mapping
|
||||
|
||||
In most cases you can add a simple mapping. These are maintained as JSON files in `data/mappings/info_config.json` and `data/mappings/info_rules.json`, and control mapping for `config.h` and `rules.mk`, respectively. Each mapping is keyed by the `config.h` or `rules.mk` variable, and the value is a hash with the following keys:
|
||||
|
||||
* `info_key`: (required) The location within `info.json` for this value. See below.
|
||||
* `value_type`: (optional) Default `str`. The format for this variable's value. See below.
|
||||
* `to_json`: (optional) Default `true`. Set to `false` to exclude this mapping from info.json
|
||||
* `to_c`: (optional) Default `true`. Set to `false` to exclude this mapping from config.h
|
||||
* `warn_duplicate`: (optional) Default `true`. Set to `false` to turn off warning when a value exists in both places
|
||||
|
||||
#### Info Key
|
||||
|
||||
We use JSON dot notation to address variables within info.json. For example, to access `info_json["rgblight"]["split_count"]` I would specify `rgblight.split_count`. This allows you to address deeply nested keys with a simple string.
|
||||
|
||||
Under the hood we use [Dotty Dict](https://dotty-dict.readthedocs.io/en/latest/), you can refer to that documentation for how these strings are converted to object access.
|
||||
|
||||
#### Value Types
|
||||
|
||||
By default we treat all values as simple strings. If your value is more complex you can use one of these types to intelligently parse the data:
|
||||
|
||||
* `array`: A comma separated array of strings
|
||||
* `array.int`: A comma separated array of integers
|
||||
* `int`: An integer
|
||||
* `hex`: A number formatted as hex
|
||||
* `list`: A space separate array of strings
|
||||
* `mapping`: A hash of key/value pairs
|
||||
|
||||
### Add code to extract it
|
||||
|
||||
Most use cases can be solved by the mapping files described above. If yours can't you can instead write code to extract your config values.
|
||||
|
||||
Whenever QMK generates a complete `info.json` it extracts information from `config.h` and `rules.mk`. You will need to add code for your new config value to `lib/python/qmk/info.py`. Typically this means adding a new `_extract_<feature>()` function and then calling your function in either `_extract_config_h()` or `_extract_rules_mk()`.
|
||||
|
||||
If you are not sure how to edit this file or are not comfortable with Python [open an issue](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=) or [join #cli on Discord](https://discord.gg/heQPAgy) and someone can help you with this part.
|
||||
|
||||
@@ -0,0 +1,10 @@
|
||||
{
|
||||
"maintainer": "qmk",
|
||||
"layouts": {
|
||||
"LAYOUT_custom": {
|
||||
"layout": [
|
||||
{ "label": "KC_Q", "matrix": [0, 0], "w": 1, "x": 0, "y": 0 }
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -8,7 +8,6 @@
|
||||
#define VENDOR_ID 0xFEED
|
||||
#define DEVICE_VER 0x0001
|
||||
#define MANUFACTURER IBNobody
|
||||
#define PRODUCT Vision Division
|
||||
|
||||
#define MATRIX_ROWS 6
|
||||
#define MATRIX_ROW_PINS { C2, C3, F4, F5, F6, F7 }
|
||||
|
||||
@@ -107,9 +107,9 @@ def doctor(cli):
|
||||
submodules.update()
|
||||
sub_ok = check_submodules()
|
||||
|
||||
if CheckStatus.ERROR in sub_ok:
|
||||
if sub_ok == CheckStatus.ERROR:
|
||||
status = CheckStatus.ERROR
|
||||
elif CheckStatus.WARNING in sub_ok and status == CheckStatus.OK:
|
||||
elif sub_ok == CheckStatus.WARNING and status == CheckStatus.OK:
|
||||
status = CheckStatus.WARNING
|
||||
|
||||
# Report a summary of our findings to the user
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,16 +1,37 @@
|
||||
"""Used by the make system to generate a rules.mk
|
||||
"""
|
||||
from pathlib import Path
|
||||
|
||||
from dotty_dict import dotty
|
||||
from milc import cli
|
||||
|
||||
from qmk.decorators import automagic_keyboard, automagic_keymap
|
||||
from qmk.info import info_json
|
||||
from qmk.info import _json_load, info_json
|
||||
from qmk.path import is_keyboard, normpath
|
||||
|
||||
info_to_rules = {
|
||||
'board': 'BOARD',
|
||||
'bootloader': 'BOOTLOADER',
|
||||
'processor': 'MCU',
|
||||
}
|
||||
|
||||
def process_mapping_rule(kb_info_json, rules_key, info_dict):
|
||||
"""Return the rules.mk line(s) for a mapping rule.
|
||||
"""
|
||||
if not info_dict.get('to_c', True):
|
||||
return None
|
||||
|
||||
info_key = info_dict['info_key']
|
||||
key_type = info_dict.get('value_type', 'str')
|
||||
|
||||
try:
|
||||
rules_value = kb_info_json[info_key]
|
||||
except KeyError:
|
||||
return None
|
||||
|
||||
if key_type == 'array':
|
||||
return f'{rules_key} ?= {" ".join(rules_value)}'
|
||||
elif key_type == 'bool':
|
||||
return f'{rules_key} ?= {"on" if rules_value else "off"}'
|
||||
elif key_type == 'mapping':
|
||||
return '\n'.join([f'{key} ?= {value}' for key, value in rules_value.items()])
|
||||
|
||||
return f'{rules_key} ?= {rules_value}'
|
||||
|
||||
|
||||
@cli.argument('-o', '--output', arg_only=True, type=normpath, help='File to write to')
|
||||
@@ -22,7 +43,6 @@ info_to_rules = {
|
||||
def generate_rules_mk(cli):
|
||||
"""Generates a rules.mk file from info.json.
|
||||
"""
|
||||
# Determine our keyboard(s)
|
||||
if not cli.config.generate_rules_mk.keyboard:
|
||||
cli.log.error('Missing paramater: --keyboard')
|
||||
cli.subcommands['info'].print_help()
|
||||
@@ -32,16 +52,18 @@ def generate_rules_mk(cli):
|
||||
cli.log.error('Invalid keyboard: "%s"', cli.config.generate_rules_mk.keyboard)
|
||||
return False
|
||||
|
||||
# Build the info.json file
|
||||
kb_info_json = info_json(cli.config.generate_rules_mk.keyboard)
|
||||
kb_info_json = dotty(info_json(cli.config.generate_rules_mk.keyboard))
|
||||
info_rules_map = _json_load(Path('data/mappings/info_rules.json'))
|
||||
rules_mk_lines = ['# This file was generated by `qmk generate-rules-mk`. Do not edit or copy.', '']
|
||||
|
||||
# Bring in settings
|
||||
for info_key, rule_key in info_to_rules.items():
|
||||
if info_key in kb_info_json:
|
||||
rules_mk_lines.append(f'{rule_key} ?= {kb_info_json[info_key]}')
|
||||
# Iterate through the info_rules map to generate basic rules
|
||||
for rules_key, info_dict in info_rules_map.items():
|
||||
new_entry = process_mapping_rule(kb_info_json, rules_key, info_dict)
|
||||
|
||||
# Find features that should be enabled
|
||||
if new_entry:
|
||||
rules_mk_lines.append(new_entry)
|
||||
|
||||
# Iterate through features to enable/disable them
|
||||
if 'features' in kb_info_json:
|
||||
for feature, enabled in kb_info_json['features'].items():
|
||||
if feature == 'bootmagic_lite' and enabled:
|
||||
@@ -51,15 +73,6 @@ def generate_rules_mk(cli):
|
||||
enabled = 'yes' if enabled else 'no'
|
||||
rules_mk_lines.append(f'{feature}_ENABLE ?= {enabled}')
|
||||
|
||||
# Set the LED driver
|
||||
if 'led_matrix' in kb_info_json and 'driver' in kb_info_json['led_matrix']:
|
||||
driver = kb_info_json['led_matrix']['driver']
|
||||
rules_mk_lines.append(f'LED_MATRIX_DRIVER ?= {driver}')
|
||||
|
||||
# Add community layouts
|
||||
if 'community_layouts' in kb_info_json:
|
||||
rules_mk_lines.append(f'LAYOUTS ?= {" ".join(kb_info_json["community_layouts"])}')
|
||||
|
||||
# Show the results
|
||||
rules_mk = '\n'.join(rules_mk_lines) + '\n'
|
||||
|
||||
@@ -72,7 +85,7 @@ def generate_rules_mk(cli):
|
||||
if cli.args.quiet:
|
||||
print(cli.args.output)
|
||||
else:
|
||||
cli.log.info('Wrote info_config.h to %s.', cli.args.output)
|
||||
cli.log.info('Wrote rules.mk to %s.', cli.args.output)
|
||||
|
||||
else:
|
||||
print(rules_mk)
|
||||
|
||||
@@ -27,7 +27,7 @@ ROW_LETTERS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnop'
|
||||
LED_INDICATORS = {
|
||||
'caps_lock': 'LED_CAPS_LOCK_PIN',
|
||||
'num_lock': 'LED_NUM_LOCK_PIN',
|
||||
'scrol_lock': 'LED_SCROLL_LOCK_PIN',
|
||||
'scroll_lock': 'LED_SCROLL_LOCK_PIN',
|
||||
}
|
||||
|
||||
# Constants that should match their counterparts in make
|
||||
|
||||
+104
-243
File diff suppressed because it is too large
Load Diff
@@ -230,3 +230,32 @@ def test_generate_rgb_breathe_table():
|
||||
check_returncode(result)
|
||||
assert 'Breathing center: 1.2' in result.stdout
|
||||
assert 'Breathing max: 127' in result.stdout
|
||||
|
||||
|
||||
def test_generate_config_h():
|
||||
result = check_subcommand('generate-config-h', '-kb', 'handwired/pytest/basic')
|
||||
check_returncode(result)
|
||||
assert '# define DEVICE_VER 0x0001' in result.stdout
|
||||
assert '# define DESCRIPTION handwired/pytest/basic' in result.stdout
|
||||
assert '# define DIODE_DIRECTION COL2ROW' in result.stdout
|
||||
assert '# define MANUFACTURER none' in result.stdout
|
||||
assert '# define PRODUCT handwired/pytest/basic' in result.stdout
|
||||
assert '# define PRODUCT_ID 0x6465' in result.stdout
|
||||
assert '# define VENDOR_ID 0xFEED' in result.stdout
|
||||
assert '# define MATRIX_COLS 1' in result.stdout
|
||||
assert '# define MATRIX_COL_PINS { F4 }' in result.stdout
|
||||
assert '# define MATRIX_ROWS 1' in result.stdout
|
||||
assert '# define MATRIX_ROW_PINS { F5 }' in result.stdout
|
||||
|
||||
|
||||
def test_generate_rules_mk():
|
||||
result = check_subcommand('generate-rules-mk', '-kb', 'handwired/pytest/basic')
|
||||
check_returncode(result)
|
||||
assert 'BOOTLOADER ?= atmel-dfu' in result.stdout
|
||||
assert 'MCU ?= atmega32u4' in result.stdout
|
||||
|
||||
|
||||
def test_generate_layouts():
|
||||
result = check_subcommand('generate-layouts', '-kb', 'handwired/pytest/basic')
|
||||
check_returncode(result)
|
||||
assert '#define LAYOUT_custom(k0A) {' in result.stdout
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
appdirs
|
||||
argcomplete
|
||||
colorama
|
||||
dotty-dict
|
||||
hjson
|
||||
jsonschema
|
||||
milc
|
||||
|
||||
Reference in New Issue
Block a user