README.md
1## Linker Script Generator
2
3Contains code that implements linker script generation, `ldgen`. For more information about the feature,
4see `docs/en/api-guides/linker-script-generation.rst`.
5
6### Source Files
7
8The following are the source files in the directory:
9
10- `ldgen.py` - Python executable that gets called during build.
11- `entity.py` - contains classes related to entities (library, object, symbol or combination of the above) with mappable input sections.
12- `fragments.py` - contains classes for parsing the different types of fragments in linker fragment files.
13- `generation.py` - contains bulk of the logic used to process fragments into output commands.
14- `sdkconfig.py` - used for evaluating conditionals in fragment files.
15- `linker_script.py` - augments the input linker script template with output commands from generation process to produce the output linker script.
16- `output_commands.py` - contains classes that represent the output commands in the output linker script.
17- `ldgen_common.py` - contains miscellaneous utilities/definitions that can be used in the files mentioned above.
18
19### Tests
20
21Unit tests are in the `test` directory. These tests are run as part of CI in the job `test_ldgen_on_host`.
22
23There is also a test app for `ldgen` in `tools/test_apps/build_system/ldgen_test`.
24
25### Build System
26
27Linker script generation is a part of the build process. The build scripts `tools/cmake/ldgen.cmake`
28and `make/ldgen.mk` contain the build-system-side implementation for CMake and Make, respectively.
29
30### Basic Flow
31
32The build system invokes `ldgen.py`, passing some information from the build.
33
34The linker fragment files are parsed by `fragments.py`, evaluating conditional expressions
35with `sdkconfig.py`.
36
37From the parsed fragments, `generation.py` generates output commands defined in `output_commands.py`,
38with some help from `entity.py`.
39
40`linker_script.py` writes the output linker script, replacing markers with output commands generated.
41
42More details about the implementation are in the respective source files.
