@@ -64,6 +64,52 @@ If you aren't sure what boards exist, have a peek in the boards subdirectory of
6464If you have a fast computer with many cores, consider adding ` -j ` to your build flags, such as ` -j17 ` on
6565a 6-core 12-thread machine.
6666
67+ ## Configuration
68+
69+ Ports and boards are preconfigured, thus make knows how to build a specific
70+ board. Power users can change the configuration of a specific board or port,
71+ either by passing compile-time options to make, or by creating appropriate
72+ make include files.
73+
74+ The configuration system is hierarchical. A higher level will typically only
75+ set an option that a lower level hasn't configured:
76+
77+ * board configuration: ` mpconfigport.mk `
78+ * pre-port user configuration: ` user_pre_mpconfigport.mk `
79+ * port configuration: ` mpconfigport.mk `
80+ * post-port user configuration: ` user_post_mpconfigport.mk `
81+ * global configuration: ` py/circuitpython_mpconfig.mk `
82+
83+ The board configuration is within the board-directory, e.g.
84+ ` ports/raspberrypi/boards/raspberry_pi_pico/ ` , the port configuration is
85+ in the port-directory, e.g. ` ports/raspberrypi/ ` .
86+
87+ Editing these configuration files is the way to go if you want to change
88+ the default behavior and ultimately create a pull-request. Otherwise,
89+ changes should go into one of the user configuration files.
90+
91+ User specific configurations are optional and should be maintained out of
92+ tree. Passing ` -I directory ` tells make where to search for the additional
93+ configuration files. E.g. to speed up boots by removing the wait-time for
94+ the save-mode button press, you would:
95+
96+ * create a directory: ` mkdir -p ~/my_cp_config `
97+ * create the config file: ` echo 'CIRCUITPY_SKIP_SAFE_MODE_WAIT=0' > ~/my_cp_config/user_pre_mpconfigport.mk `
98+ * run make with: ` make -I ~/my_cp_config BOARD=raspberry_pi_pico `
99+
100+ Besides the ` user*mpconfigport.mk ` files, there is another optional file
101+ named ` user_post_circuitpy_defns.mk ` . This file is included at the end
102+ and can be used to tweak compiler-definitions that are not covered by
103+ one of the compile time options ` CIRCUITPY_* ` .
104+
105+ Example: to create a build for the Pico2-W with an integrated saves-partition,
106+ you would create a ` user_post_circuitpy_defns.mk ` with the following content:
107+
108+ $(info ===> processing user_post_circuitpy_defns.mk)
109+ ifeq (${BOARD},raspberry_pi_pico2_w)
110+ CFLAGS += -DCIRCUITPY_SAVES_PARTITION_SIZE=1048576
111+ endif
112+
67113## Testing
68114
69115If you are working on changes to the core language, you might find it useful to run the test suite.
0 commit comments