Merge pull request #10817 from bablokb/userconfig

support user-configuration files

Author: dhalbert

.gitignore

@@ -55,6 +55,9 @@ __pycache__/
 ######################
 GNUmakefile
 user.props
+user_pre_mpconfigport.mk
+user_post_mpconfigport.mk
+user_post_circuitpy_defns.mk
 
 # Sphinx output
 ###############

BUILDING.md

@@ -64,6 +64,52 @@ If you aren't sure what boards exist, have a peek in the boards subdirectory of
 If you have a fast computer with many cores, consider adding `-j` to your build flags, such as `-j17` on
 a 6-core 12-thread machine.
 
+## Configuration
+
+Ports and boards are preconfigured, thus make knows how to build a specific
+board. Power users can change the configuration of a specific board or port,
+either by passing compile-time options to make, or by creating appropriate
+make include files.
+
+The configuration system is hierarchical. A higher level will typically only
+set an option that a lower level hasn't configured:
+
+* board configuration: `mpconfigport.mk`
+* pre-port user configuration: `user_pre_mpconfigport.mk`
+* port configuration: `mpconfigport.mk`
+* post-port user configuration: `user_post_mpconfigport.mk`
+* global configuration: `py/circuitpython_mpconfig.mk`
+
+The board configuration is within the board-directory, e.g.
+`ports/raspberrypi/boards/raspberry_pi_pico/`, the port configuration is
+in the port-directory, e.g. `ports/raspberrypi/`.
+
+Editing these configuration files is the way to go if you want to change
+the default behavior and ultimately create a pull-request. Otherwise,
+changes should go into one of the user configuration files.
+
+User specific configurations are optional and should be maintained out of
+tree. Passing `-I directory` tells make where to search for the additional
+configuration files. E.g. to speed up boots by removing the wait-time for
+the save-mode button press, you would:
+
+* create a directory: `mkdir -p ~/my_cp_config`
+* create the config file: `echo 'CIRCUITPY_SKIP_SAFE_MODE_WAIT=0' > ~/my_cp_config/user_pre_mpconfigport.mk`
+* run make with: `make -I ~/my_cp_config BOARD=raspberry_pi_pico`
+
+Besides the `user*mpconfigport.mk` files, there is another optional file
+named `user_post_circuitpy_defns.mk`. This file is included at the end
+and can be used to tweak compiler-definitions that are not covered by
+one of the compile time options `CIRCUITPY_*`.
+
+Example: to create a build for the Pico2-W with an integrated saves-partition,
+you would create a `user_post_circuitpy_defns.mk` with the following content:
+
+    $(info ===> processing user_post_circuitpy_defns.mk)
+    ifeq (${BOARD},raspberry_pi_pico2_w)
+    CFLAGS += -DCIRCUITPY_SAVES_PARTITION_SIZE=1048576
+    endif
+
 ## Testing
 
 If you are working on changes to the core language, you might find it useful to run the test suite.

py/circuitpy_mkenv.mk

@@ -43,6 +43,10 @@ ifneq ($(VALID_BOARD),)
 include boards/$(BOARD)/mpconfigboard.mk
 endif
 
+# user-specific settings that mpconfigport does not override
+# (i.e. mpconfigport.mk uses "foo ?= bar")
+-include user_pre_mpconfigport.mk
+
 # Port-specific
 include mpconfigport.mk
 
@@ -52,6 +56,10 @@ ifneq ($(VALID_BOARD),)
 include $(TOP)/py/circuitpy_mpconfig.mk
 endif
 
+# user-specific overrides of hard-coded settings
+# (i.e. xxx.mk uses "foo = bar")
+-include user_post_mpconfigport.mk
+
 # qstr definitions (must come before including py.mk)
 QSTR_DEFS = qstrdefsport.h
 
@@ -62,3 +70,6 @@ include $(TOP)/supervisor/supervisor.mk
 
 # Include make rules and variables common across CircuitPython builds.
 include $(TOP)/py/circuitpy_defns.mk
+
+# user specific
+-include user_post_circuitpy_defns.mk