Mirror/pmbootstrap
1
0
Fork 1
mirror of https://gitlab.postmarketos.org/postmarketOS/pmbootstrap.git synced 2025-07-12 19:09:56 +03:00
Code Issues Wiki Activity

docs/cross_compiling: new page (MR 2562)

Browse source 
Add the cross compiling documentation to the pmbootstrap docs.

This is based on the following wiki pages, but updated to reflect new
changes with cross-native2 and to make it more readable:
* https://wiki.postmarketos.org/wiki/Pmbootstrap/Cross_Compiling
* https://wiki.postmarketos.org/wiki/Build_internals#Cross-compile_types

Co-authored-by: Caleb Connolly <caleb@postmarketos.org>
This commit is contained in:
Oliver Smith 2025-03-02 16:37:59 +01:00
parent 92fca6614b
commit 7510e80b7b
No known key found for this signature in database
GPG key ID: 5AE7F5513E0885CB
3 changed files with 120 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

118
docs/cross_compiling.md Normal file
View file

@ -0,0 +1,118 @@
# Cross Compiling
## Overview
When building packages, it might be necessary to use cross compilation
depending on the target architecture. Cross compilation is *not* necessary if
the target architecture can directly run on the host CPU (for example building
an `x86_64` or `x86` package on a `x86_64` CPU).
Multiple methods for cross compilation are implemented in pmbootstrap. For all
methods except `cross-native`, a foreign arch chroot (with the target
architecture) gets used during the build in addition to the native chroot.
<!-- markdownlint-disable MD013 MD033 -->
| Method | Native | Foreign | Speed | Limitations |
|-----------------------------|--------|---------|--------|-------------------------------------------------------------------------|
| QEMU only | | x | slow | So slow that it is desirable to<br>use other methods where possible. |
| crossdirect<br>*(default)* | x | x | medium | Cross compiler runs natively,<br>everything else goes through QEMU. |
| cross-native | x | | fast | Cannot depend on libraries<br>(works for kernel, u-boot, etc.). |
| cross-native2 | x | x | fast | Works with e.g. meson build system.<br>Kernel builds not yet supported. |
<!-- markdownlint-enable -->
## Methods
### QEMU only
Enable this method with `options="!pmb:crossdirect"` in the `APKBUILD`.
This method is the most reliable, but also the slowest. We only use it if
faster methods don't work. GTK projects using `g-ir-scanner` (*"Generating
[…].gir with a custom command"*) are currently [known to
fail](https://gitlab.postmarketos.org/postmarketOS/pmbootstrap/-/issues/2567)
with other methods.
### Crossdirect
This is the default method.
This method works for almost all packages, and gives a good speed improvement
over running everything in QEMU. However only the cross compilers run natively.
Linkers and all other commands used during the build still need to run through
QEMU and so these are still very slow.
The native chroot gets mounted in the foreign arch chroot at `/native`. The
[crossdirect](https://gitlab.postmarketos.org/postmarketOS/pmaports/-/blob/master/cross/crossdirect/APKBUILD)
package gets installed into the native chroot and creates wrapper scripts
pointing to the cross compilers. When building packages for `armv7`, the build
runs in the foreign chroot and `PATH` will get prepended with
`/native/usr/lib/crossdirect/armv7`. This leads to invoking the cross compiler
from the native chroot, running at native speed, whenever calling the compiler
from the foreign arch chroot.
### Cross-Native
Enable this method with `options="pmb:cross-native"` in the `APKBUILD`.
This method is only supported for packages that do not depend on foreign arch
libraries, such bare metal software (kernel, u-boot), firmware packages or the
postmarketos-artwork package.
The whole build is done in the native chroot. Environment variables are used
to tell abuild that it is a different arch package (`CARCH`) and to the
kernel-style Makefiles that the cross compilers should be used.
### Cross-Native2
Enable this method with `options="pmb:cross-native2"` in the `APKBUILD`.
This is supported since pmbootstrap 3.4, previous versions will ignore this
option and use the crossdirect method instead.
Packages from `makedepends_host=` in the `APKBUILD` are installed in the native
chroot, and packages from `makedepends_build=` in the foreign chroot.
Environment variables are used to run abuild in the native chroot and use
its cross compilation features rather than running it and the build
system through QEMU. This massively speeds up building when it works.
The foreign chroot is mounted into the native chroot at `/sysroot`. Most build
systems will refer to it as "sysroot", in abuild it is `CBUILDROOT`.
Packages have been built successfully with cross-native2 and the following
build systems:
* meson
* go build
Where possible, we should try to migrate all packages that currently use
crossdirect to cross-native2 to make them build faster.
## Language-specific
### Rust
Rust packages can either be built with QEMU only, or with the crossdirect
method. **Now that we have cross-native2 it makes more sense to try to get
rust support working there as it will be faster and more reliable.** Rust
support in crossdirect is still experimental.
[pmaports!4234](https://gitlab.postmarketos.org/postmarketOS/pmaports/-/merge_requests/4234)
(cross/crossdirect: improve rust handling) describes some of the problems with
this approach.
#### CARGO\_HOME
If a program needs to download git repositories of dependencies with cargo
(ideally they are bundled with the source tarball and don't need to be
downloaded), then these git repositories are cached with pmbootstrap. This
works as long as the program does not override
[CARGO\_HOME](https://doc.rust-lang.org/cargo/guide/cargo-home.html). GNOME
podcasts does this for example, so if building gnome-podcasts from the git
repository with `pmbootstrap build --src`, patch out the override of
`CARGO_HOME` so the dependencies do not get downloaded for every build.
#### Packaging caveats
* `cargo auditable build` is unsupported with crossdirect and falls back to
compiling in QEMU. Change it to `cargo build` to build the package with the
native compiler.
* Running tests doesn't really work (e.g. when building squeekboard, the tests
hang and time out).

1
docs/index.rst
View file

@ -20,6 +20,7 @@ For further information, please check out the `postmarketOS-wiki`_.
usage
chroot
debugging
cross_compiling
ssh-keys
api/modules
mirrors