unix: Expand the build steps in the README.
- Present the default build dependencies in one place at the top, and make a separate section about building standalone. - Add steps for the "minimal" variant as well. - Document that building standalone requires autoconf and libtool. - Allow MICROPY_STANDALONE to be set as an environment variable. Fixes issue #11313. This work was funded through GitHub Sponsors. Signed-off-by: Angus Gratton <angus@redyak.com.au>
This commit is contained in:
Angus Gratton
Damien George
parent
455415b1e1
commit
d04974d8d0
|
|
@ -1,17 +1,59 @@
|
|||
The Unix version
|
||||
----------------
|
||||
MicroPython Unix port
|
||||
=====================
|
||||
|
||||
The "unix" port requires a standard Unix-like environment with gcc and GNU
|
||||
make. This includes Linux, BSD, macOS, and Windows Subsystem for Linux. The
|
||||
x86 and x64 architectures are supported (i.e. x86 32- and 64-bit), as well as
|
||||
ARM and MIPS. Making a full-featured port to another architecture requires
|
||||
The "unix" port runs in standard Unix-like environments including Linux, BSD,
|
||||
macOS, and Windows Subsystem for Linux.
|
||||
|
||||
The x86 and x64 architectures are supported (i.e. x86 32- and 64-bit), as well
|
||||
as ARM and MIPS. Extending the unix port to another architecture requires
|
||||
writing some assembly code for the exception handling and garbage collection.
|
||||
Alternatively, a fallback implementation based on setjmp/longjmp can be used.
|
||||
|
||||
To build (see section below for required dependencies):
|
||||
Building
|
||||
--------
|
||||
|
||||
### Dependencies
|
||||
|
||||
To build the unix port locally then you will need:
|
||||
|
||||
* git command line executable, unless you downloaded a source .tar.xz file from
|
||||
https://micropython.org/download/
|
||||
* gcc (or clang for macOS) toolchain
|
||||
* GNU Make
|
||||
* Python 3.x
|
||||
|
||||
To build the default "standard" variant and configuration, then you will also
|
||||
need:
|
||||
|
||||
* `pkg-config` tool
|
||||
* `libffi` library and headers
|
||||
|
||||
On Debian/Ubuntu/Mint and related Linux distros, you can install all these
|
||||
dependencies with a command like:
|
||||
|
||||
```
|
||||
# apt install build-essential git python3 pkg-config libbfi-dev
|
||||
```
|
||||
|
||||
(See below for steps to build either a standalone or minimal MicroPython
|
||||
executable that doesn't require system `libffi` or `pkg-config`.)
|
||||
|
||||
### Default build steps
|
||||
|
||||
To set up the environment for building (not needed every time), starting from
|
||||
the top-level MicroPython directory:
|
||||
|
||||
$ cd ports/unix
|
||||
$ make -C ../../mpy-cross
|
||||
$ make submodules
|
||||
|
||||
The `mpy-cross` step builds the [MicroPython
|
||||
cross-compiler](https://github.com/micropython/micropython/?tab=readme-ov-file#the-micropython-cross-compiler-mpy-cross).
|
||||
The `make submodules` step can be skipped if you didn't clone the MicroPython
|
||||
source from git.
|
||||
|
||||
Next, to build the actual executable (still in the `ports/unix` directory):
|
||||
|
||||
$ make
|
||||
|
||||
Then to give it a try:
|
||||
|
|
@ -45,40 +87,59 @@ Browse available modules at
|
|||
[Package management](https://docs.micropython.org/en/latest/reference/packages.html)
|
||||
for more information about `mip`.
|
||||
|
||||
External dependencies
|
||||
---------------------
|
||||
### Minimal Variant
|
||||
|
||||
The `libffi` library and `pkg-config` tool are required. On Debian/Ubuntu/Mint
|
||||
derivative Linux distros, install `build-essential`(includes toolchain and
|
||||
make), `libffi-dev`, and `pkg-config` packages.
|
||||
|
||||
Other dependencies can be built together with MicroPython. This may
|
||||
be required to enable extra features or capabilities, and in recent
|
||||
versions of MicroPython, these may be enabled by default. To build
|
||||
these additional dependencies, in the unix port directory first execute:
|
||||
The "standard" variant of MicroPython is the default. It enables most features,
|
||||
including external modules interfaced using `libffi`. To instead build the
|
||||
"minimal" variant, which disables almost all optional features and modules:
|
||||
|
||||
$ cd ports/unix
|
||||
$ make submodules
|
||||
$ make VARIANT=minimal
|
||||
|
||||
This will fetch all the relevant git submodules (sub repositories) that
|
||||
the port needs. Use the same command to get the latest versions of
|
||||
submodules as they are updated from time to time. After that execute:
|
||||
The executable will be built at `build-minimal/micropython`.
|
||||
|
||||
$ make deplibs
|
||||
Additional variants can be found in the `variants` sub-directory of the port,
|
||||
although these are mostly of interest to MicroPython maintainers.
|
||||
|
||||
This will build all available dependencies (regardless whether they are used
|
||||
or not). If you intend to build MicroPython with additional options
|
||||
(like cross-compiling), the same set of options should be passed to `make
|
||||
deplibs`. To actually enable/disable use of dependencies, edit the
|
||||
### Standalone build
|
||||
|
||||
By default, the "standard" variant uses `pkg-config` to link to the system's
|
||||
shared `libffi` library.
|
||||
|
||||
It is possible to instead build a standalone MicroPython where `libffi` is built
|
||||
from source and linked statically into the `micropython` executable. This is
|
||||
mostly useful for embedded or cross-compiled applications.
|
||||
|
||||
Building standalone requires `autoconf` and `libtool` to also be installed.
|
||||
|
||||
To build standalone:
|
||||
|
||||
$ export MICROPY_STANDALONE=1
|
||||
$ make submodules # fetches libffi submodule
|
||||
$ make deplibs # build just the external libraries
|
||||
$ make # build MicroPython itself
|
||||
|
||||
`make deplibs` causes all supported external libraries (currently only `libffi`)
|
||||
to be built inside the build directory, so it needs to run again only after
|
||||
`make clean`.
|
||||
|
||||
If you intend to build MicroPython with additional options (like
|
||||
cross-compiling), the same set of options should be passed to both `make
|
||||
deplibs` and `make`.
|
||||
|
||||
### Other dependencies
|
||||
|
||||
To actually enable/disable use of dependencies, edit the
|
||||
`ports/unix/mpconfigport.mk` file, which has inline descriptions of the
|
||||
options. For example, to build the SSL module, `MICROPY_PY_SSL` should be
|
||||
set to 1.
|
||||
|
||||
Debug Symbols
|
||||
-------------
|
||||
### Debug Symbols
|
||||
|
||||
By default, builds are stripped of symbols and debug information to save size.
|
||||
|
||||
To build a debuggable version of the Unix port, there are two options
|
||||
To build a debuggable version of the Unix port, there are two options:
|
||||
|
||||
1. Run `make [other arguments] DEBUG=1`. Note setting `DEBUG` also reduces the
|
||||
optimisation level, so it's not a good option for builds that also want the
|
||||
|
|
|
|||
|
|
@ -37,7 +37,7 @@ MICROPY_PY_JNI = 0
|
|||
|
||||
# Avoid using system libraries, use copies bundled with MicroPython
|
||||
# as submodules (currently affects only libffi).
|
||||
MICROPY_STANDALONE = 0
|
||||
MICROPY_STANDALONE ?= 0
|
||||
|
||||
MICROPY_ROM_TEXT_COMPRESSION = 1
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue