Skip to content

Commit fe036e9

Browse files
JohnAmadisJohnAmadis
authored
Merge pull request #71 from choco-technologies/copilot/add-cmake-options-documentation
Add CMake options reference documentation
2 parents 04e5a50 + e6f54c6 commit fe036e9

2 files changed

Lines changed: 145 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,8 @@ cmake --build build
5757

5858
All parameters are optional. If not specified, the build will proceed with default settings.
5959

60+
For a full list of all available CMake options (including DMOD library and VFS configuration), see [docs/cmake-options.md](docs/cmake-options.md).
61+
6062
## CMake Targets
6163

6264
The following targets work in both hardware mode (with OpenOCD) and Renode simulation mode. The workflow is identical regardless of the mode.

‎docs/cmake-options.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# CMake Options
2+
3+
This document describes all CMake options available when building dmod-boot.
4+
5+
## Main Build Options
6+
7+
These options are defined in the top-level `CMakeLists.txt` and control the overall build configuration.
8+
9+
| Option | Type | Default | Description |
10+
|--------|------|---------|-------------|
11+
| `TARGET` | STRING | `STM32F746xG` | Target microcontroller. Supported values: `STM32F746xG`, `STM32F407G`. Ignored when `BOARD` is set. |
12+
| `BOARD` | STRING | *(empty)* | Board name (optional). When set, `TARGET` is derived from `configs/board/<BOARD>/board.cmake`. Example: `stm32f746g-disco`. |
13+
| `STARTUP_DMP_FILE` | FILEPATH | *(empty)* | Path to an optional `.dmp` startup package file to embed in ROM. Loaded using `Dmod_AddPackageBuffer` at boot. |
14+
| `USER_DATA_FILE` | FILEPATH | *(empty)* | Path to an optional user data file to embed in ROM. Its address and size are accessible via `USER_DATA_ADDR` and `USER_DATA_SIZE` environment variables. |
15+
| `DMBOOT_CONFIG_DIR` | PATH | `<build>/configs` | Path to a directory that will be converted to a dmffs filesystem image and mounted at `/configs/` at boot time. |
16+
| `DMBOOT_MAIN_MODULE` | STRING | `dmell` | Name of the main module to start after boot. |
17+
| `DMBOOT_EXTRA_FLASH_DMD_FILES` | STRING | *(empty)* | Semicolon-separated list of additional `flash.dmd` files to include. Each file adds more flash modules to download at build time. |
18+
| `DMBOOT_EXTRA_SDCARD_DMD_FILES` | STRING | *(empty)* | Semicolon-separated list of additional `sdcard.dmd` files to include. Each file adds more sdcard modules to download at build time. |
19+
| `DMBOOT_MANIFEST_URL` | STRING | *(empty)* | Manifest path/URL to use with `dmf-get -m` flag for all module downloads. |
20+
| `DMBOOT_EMULATION` | BOOL | `OFF` | Enable Renode emulation mode instead of hardware mode (OpenOCD). |
21+
22+
## VFS Options
23+
24+
These options are defined in `configs/dmvfs-cfg.cmake` and configure the virtual filesystem.
25+
26+
| Option | Type | Default | Description |
27+
|--------|------|---------|-------------|
28+
| `DMBOOT_MAX_MOUNT_POINTS` | STRING | `100` | Maximum number of VFS mount points. |
29+
| `DMBOOT_MAX_OPEN_FILES` | STRING | `1000` | Maximum number of simultaneously open files. |
30+
31+
## DMOD Library Options
32+
33+
These options are defined in `configs/dmod-cfg.cmake` and configure the DMOD library.
34+
35+
### Standard Library Integration
36+
37+
| Option | Type | Default | Description |
38+
|--------|------|---------|-------------|
39+
| `DMOD_USE_STDLIB` | BOOL | `OFF` | Enable use of the C standard library. |
40+
| `DMOD_USE_GETENV` | BOOL | `OFF` | Enable use of the `getenv` function. |
41+
| `DMOD_USE_STDIO` | BOOL | `OFF` | Enable use of the `stdio` library. |
42+
| `DMOD_USE_ASSERT` | BOOL | `OFF` | Enable use of the `assert` function. |
43+
| `DMOD_USE_PTHREAD` | BOOL | `OFF` | Enable use of the `pthread` library. |
44+
| `DMOD_USE_MMAN` | BOOL | `OFF` | Enable use of memory management functions (`mman.h`). |
45+
| `DMOD_USE_ALIGNED_ALLOC` | BOOL | `OFF` | Enable use of aligned allocation. |
46+
| `DMOD_USE_ALIGNED_MALLOC_MOCK` | BOOL | `OFF` | Enable aligned malloc mock when aligned allocation is not available. |
47+
| `DMOD_USE_REALLOC` | BOOL | `OFF` | Enable use of the `realloc` function. |
48+
| `DMOD_USE_ENVIRON` | BOOL | `OFF` | Enable use of the `environ` variable. |
49+
| `DMOD_USE_TERMIOS` | BOOL | `OFF` | Enable use of the `termios` library. |
50+
| `DMOD_USE_TIME_H` | BOOL | `OFF` | Enable use of the `time.h` library. |
51+
| `DMOD_USE_FASTLZ` | BOOL | `ON` | Enable use of the FastLZ compression library. |
52+
| `DMOD_USE_EXCEPTIONS` | BOOL | `OFF` | Enable use of C++ exceptions. |
53+
54+
### Built-in Implementations
55+
56+
| Option | Type | Default | Description |
57+
|--------|------|---------|-------------|
58+
| `DMOD_IMPLEMENT_PRINTF` | BOOL | `ON` | Implement `printf` inside DMOD (avoids linking the full stdio library). |
59+
| `DMOD_IMPLEMENT_SCANF` | BOOL | `OFF` | Implement `scanf` inside DMOD. |
60+
| `DMOD_BUILTIN_COMPRESSION_API` | BOOL | `ON` | Enable the built-in compression API. Can use a lot of flash memory; decompression-only is usually sufficient. |
61+
62+
### Module System Configuration
63+
64+
| Option | Type | Default | Description |
65+
|--------|------|---------|-------------|
66+
| `DMOD_MAX_MODULES` | STRING | `100` | Maximum number of modules that can be registered. |
67+
| `DMOD_MAX_REQUIRED_MODULES` | STRING | `15` | Maximum number of required modules per module. |
68+
| `DMOD_MODE` | STRING | `DMOD_SYSTEM` | Operating mode of the DMOD system. |
69+
| `DMOD_EXTERNAL_REGISTRATION` | BOOL | `ON` | Enable external registration of modules (required by `dmvfs` and `dmlist` libraries). |
70+
71+
### System Version
72+
73+
| Option | Type | Default | Description |
74+
|--------|------|---------|-------------|
75+
| `DMOD_SYSTEM_VERSION_MAJOR` | STRING | `0` | Major version of your system. |
76+
| `DMOD_SYSTEM_VERSION_MINOR` | STRING | `1` | Minor version of your system. |
77+
78+
### File System Paths
79+
80+
| Option | Type | Default | Description |
81+
|--------|------|---------|-------------|
82+
| `DMOD_DMFC_DIR` | STRING | `/flash/dmfc` | Directory for DMFC (compiled module) files on the target filesystem. |
83+
| `DMOD_DMF_DIR` | STRING | `/flash/dmf` | Directory for DMF (module) files on the target filesystem. |
84+
| `DMOD_REPO_DIR` | STRING | `<DMOD_DMF_DIR>` | Path to the default module repository on the target filesystem. |
85+
| `DMOD_REPO_PATHS` | STRING | `<DMOD_DMF_DIR>:<DMOD_DMFC_DIR>` | Colon-separated list of all module repository paths on the target filesystem. |
86+
87+
### Sub-library Build Options
88+
89+
| Option | Type | Default | Description |
90+
|--------|------|---------|-------------|
91+
| `DMOD_BUILD_TESTS` | BOOL | `OFF` | Enable building of DMOD library tests. |
92+
| `DMOD_BUILD_EXAMPLES` | BOOL | `OFF` | Enable building of DMOD library examples. |
93+
| `DMOD_BUILD_TOOLS` | BOOL | `OFF` | Enable building of DMOD tools (e.g. `todmp`). |
94+
| `DMOD_BUILD_TEMPLATES` | BOOL | `OFF` | Enable building of DMOD module templates. |
95+
96+
## Usage Examples
97+
98+
### Minimal build with default settings
99+
100+
```bash
101+
cmake -S . -B build
102+
cmake --build build
103+
```
104+
105+
### Build for a specific target
106+
107+
```bash
108+
cmake -DTARGET=STM32F407G -S . -B build
109+
cmake --build build
110+
```
111+
112+
### Build using a board preset
113+
114+
```bash
115+
cmake -DBOARD=stm32f746g-disco -S . -B build
116+
cmake --build build
117+
```
118+
119+
### Build for Renode emulation
120+
121+
```bash
122+
cmake -DDMBOOT_EMULATION=ON -S . -B build
123+
cmake --build build
124+
```
125+
126+
### Build with embedded startup package and custom config directory
127+
128+
```bash
129+
cmake -DSTARTUP_DMP_FILE=/path/to/startup.dmp \
130+
-DDMBOOT_CONFIG_DIR=/path/to/configs \
131+
-S . -B build
132+
cmake --build build
133+
```
134+
135+
### Adjust module system limits
136+
137+
```bash
138+
cmake -DDMOD_MAX_MODULES=200 \
139+
-DDMBOOT_MAX_MOUNT_POINTS=50 \
140+
-DDMBOOT_MAX_OPEN_FILES=200 \
141+
-S . -B build
142+
cmake --build build
143+
```

0 commit comments

Comments
 (0)