a6bc1ccbe5
This commit extends the MPY file format in a backwards-compatible way to store an encoded form of architecture-specific flags that have been specified in the "mpy-cross" command line, or that have been explicitly set as part of a native emitter configuration. The file format changes are as follows: * The features byte, previously containing the target native architecture and the minor file format version, now claims bit 6 as a flag indicating the presence of an encoded architecture flags integer * If architecture flags need to be stored, they are placed right after the MPY file header. This means that properly-written MPY parsers, if encountering a MPY file containing encoded architecture flags, should raise an error since no architecture identifiers have been defined that make use of bits 6 and 7 in the referenced header byte. This should give enough guarantees of backwards compatibility when this feature is used (improper parsers were subjected to breakage anyway). The encoded architecture flags could have been placed at the end, but: * Having them right after the header makes the architecture compatibility checks occur before having read the whole file in memory (which still happens on certain platforms as the reader may be backed by a memory buffer), and prevents eventual memory allocations that do not take place if the module is rejected early * Properly-written MPY file parsers should have checked the upper two bits of the flags byte to be actually zero according to the format specification available right before this change, so no assumptions should have been made on the exact order of the chunks for an unexpected format. The meaning of the architecture flags value is backend-specific, with the only common characteristic of being a variable-encoded unsigned integer for the time being. The changes made to the file format effectively limit the number of possible target architectures to 16, of which 13 are already claimed. There aren't that many new architectures planned to be supported for the lifetime of the current MPY file format, so this change still leaves space for architecture updates if needed. 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 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.
Documentation autobuild
For a more convenient development experience, you can use sphinx-autobuild
to automatically rebuild and serve the documentation when you make changes:
pip install sphinx-autobuild
Then run from the micropython/docs directory:
sphinx-autobuild . build/html
This will start a local web server (typically at http://127.0.0.1:8000)
and automatically rebuild the documentation whenever you save changes to the source files.
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