mirror of
https://github.com/micropython/micropython.git
synced 2025-07-21 21:11:12 +02:00
bf2005de9e
This commit lets mpy_ld.py resolve symbols not only from the object files involved in the linking process, or from compiler-supplied static libraries, but also from a list of symbols referenced by an absolute address (usually provided by the system's ROM). This is needed for ESP8266 targets as some C stdlib functions are provided by the MCU's own ROM code to reduce the final code footprint, and therefore those functions' implementation was removed from the compiler's support libraries. This means that unless `LINK_RUNTIME` is set (which lets tooling look at more libraries to resolve symbols) the build process will fail as tooling is unaware of the ROM symbols' existence. With this change, fixed-address symbols can be exposed to the symbol resolution step when performing natmod linking. If there are symbols coming in from a fixed-address symbols list and internal code or external libraries, the fixed-address symbol address will take precedence in all cases. Although this is - in theory - also working for the whole range of ESP32 MCUs, testing is currently limited to Xtensa processors and the example natmods' makefiles only make use of this commit's changes for the ESP8266 target. Natmod builds can set the MPY_EXTERN_SYM_FILE variable pointing to a linkerscript file containing a series of symbols (weak or strong) at a fixed address; these symbols will then be used by the MicroPython linker when packaging the natmod. If a different natmod build method is used (eg. custom CMake scripts), `tools/mpy_ld.py` can now accept a command line parameter called `--externs` (or its short variant `-e`) that contains the path of a linkerscript file with the fixed-address symbols to use when performing the linking process. The linkerscript file parser can handle a very limited subset of binutils's linkerscript syntax, namely just block comments, strong symbols, and weak symbols. Each symbol must be in its own line for the parser to succeed, empty lines or comment blocks are skipped. For an example of what this parser was meant to handle, you can look at `ports/esp8266/boards/eagle.rom.addr.v6.ld` and follow its format. The natmod developer documentation is also updated to reflect the new command line argument accepted by `mpy_ld.py` and the use cases for the changes introduced by this commit. Signed-off-by: Alessandro Gatti <a.gatti@frob.it>
MicroPython Documentation
The MicroPython documentation can be found at: http://docs.micropython.org/en/latest/
The documentation you see there is generated from the files in the docs tree: https://github.com/micropython/micropython/tree/master/docs
Building the documentation locally
If you're making changes to the documentation, you may want to build the documentation locally so that you can preview your changes.
Install Sphinx, and optionally (for the RTD-styling), sphinx_rtd_theme, preferably in a virtualenv:
pip install sphinx
pip install sphinx_rtd_theme
In micropython/docs, build the docs:
make html
You'll find the index page at micropython/docs/build/html/index.html.
Having readthedocs.org build the documentation
If you would like to have docs for forks/branches hosted on GitHub, GitLab or BitBucket an alternative to building the docs locally is to sign up for a free https://readthedocs.org account. The rough steps to follow are:
- sign-up for an account, unless you already have one
- in your account settings: add GitHub as a connected service (assuming you have forked this repo on github)
- in your account projects: import your forked/cloned micropython repository into readthedocs
- in the project's versions: add the branches you are developing on or for which you'd like readthedocs to auto-generate docs whenever you push a change
PDF manual generation
This can be achieved with:
make latexpdf
but requires a rather complete install of LaTeX with various extensions. On Debian/Ubuntu, try (1GB+ download):
apt install texlive-latex-recommended texlive-latex-extra texlive-xetex texlive-fonts-extra cm-super xindy