summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMathieu Othacehe <othacehe@gnu.org>2022-05-08 19:43:47 +0200
committerMathieu Othacehe <othacehe@gnu.org>2022-05-22 15:15:34 +0200
commita4aa13c02f13bfefdbcf8f73d75d9485be6049a3 (patch)
treef3b20afe04c0cabb9bbbfbb43e09c6efbcede66a
parentscripts: build: Highlight the current system with --list-systems. (diff)
downloadguix-a4aa13c02f13bfefdbcf8f73d75d9485be6049a3.tar.gz
guix-a4aa13c02f13bfefdbcf8f73d75d9485be6049a3.tar.bz2
guix-a4aa13c02f13bfefdbcf8f73d75d9485be6049a3.tar.xz
doc: Add a 'Foreign architectures' chapter.
* doc/guix.texi ("Foreign architectures"): New chapter.
-rw-r--r--doc/guix.texi173
1 files changed, 172 insertions, 1 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index df9cbf4851..184206bec8 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -41,7 +41,7 @@ Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Julien Lepiller@*
41Copyright @copyright{} 2016 Alex ter Weele@* 41Copyright @copyright{} 2016 Alex ter Weele@*
42Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Christopher Baines@* 42Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Christopher Baines@*
43Copyright @copyright{} 2017, 2018, 2019 Clément Lassieur@* 43Copyright @copyright{} 2017, 2018, 2019 Clément Lassieur@*
44Copyright @copyright{} 2017, 2018, 2020, 2021 Mathieu Othacehe@* 44Copyright @copyright{} 2017, 2018, 2020, 2021, 2022 Mathieu Othacehe@*
45Copyright @copyright{} 2017 Federico Beffa@* 45Copyright @copyright{} 2017 Federico Beffa@*
46Copyright @copyright{} 2017, 2018 Carlo Zancanaro@* 46Copyright @copyright{} 2017, 2018 Carlo Zancanaro@*
47Copyright @copyright{} 2017 Thomas Danckaert@* 47Copyright @copyright{} 2017 Thomas Danckaert@*
@@ -174,6 +174,7 @@ Weblate} (@pxref{Translating Guix}).
174* Development:: Guix-aided software development. 174* Development:: Guix-aided software development.
175* Programming Interface:: Using Guix in Scheme. 175* Programming Interface:: Using Guix in Scheme.
176* Utilities:: Package management commands. 176* Utilities:: Package management commands.
177* Foreign architectures:: Build for foreign architectures.
177* System Configuration:: Configuring the operating system. 178* System Configuration:: Configuring the operating system.
178* Home Configuration:: Configuring the home environment. 179* Home Configuration:: Configuring the home environment.
179* Documentation:: Browsing software user manuals. 180* Documentation:: Browsing software user manuals.
@@ -322,6 +323,10 @@ Invoking @command{guix build}
322* Additional Build Options:: Options specific to 'guix build'. 323* Additional Build Options:: Options specific to 'guix build'.
323* Debugging Build Failures:: Real life packaging experience. 324* Debugging Build Failures:: Real life packaging experience.
324 325
326Foreign architectures
327* Using cross-compilation:: Build for foreign architecture using cross-compilation.
328* Using native building:: Build for foreign architectures natively.
329
325System Configuration 330System Configuration
326 331
327* Using the Configuration System:: Customizing your GNU system. 332* Using the Configuration System:: Customizing your GNU system.
@@ -15211,6 +15216,172 @@ Session_PID: 4278
15211@end table 15216@end table
15212@end table 15217@end table
15213 15218
15219@node Foreign architectures
15220@chapter Foreign architectures
15221
15222GNU Guix can target computers of different CPU architectures when
15223producing packages (@pxref{Invoking guix package}), packs
15224(@pxref{Invoking guix pack}) or full systems (@pxref{Invoking guix
15225system}).
15226
15227GNU Guix supports two distinct mechanisms to target foreign
15228architectures:
15229
15230@enumerate
15231@item
15232The traditional
15233@uref{https://en.wikipedia.org/wiki/Cross_compiler,cross-compilation}
15234mechanism.
15235@item
15236The native building mechanism which consists in building using the CPU
15237instruction set of the foreign system you are targeting. It often
15238requires emulation, using the QEMU program for instance.
15239@end enumerate
15240
15241@menu
15242* Using cross-compilation:: Build for foreign architecture using cross-compilation.
15243* Using native building:: Build for foreign architectures natively.
15244@end menu
15245
15246@node Using cross-compilation
15247@section Using cross-compilation
15248
15249@cindex foreign architectures
15250The GNU Guix commands supporting cross-compilation are proposing the
15251@option{--list-targets} and @option{--target} options.
15252
15253The @option{--list-targets} option lists all the supported targets that
15254can be passed as an argument to @option{--target}.
15255
15256@example
15257$ guix build --list-targets
15258The available targets are:
15259
15260 - aarch64-linux-gnu
15261 - arm-linux-gnueabihf
15262 - i586-pc-gnu
15263 - i686-linux-gnu
15264 - i686-w64-mingw32
15265 - mips64el-linux-gnu
15266 - powerpc-linux-gnu
15267 - powerpc64le-linux-gnu
15268 - riscv64-linux-gnu
15269 - s390x-linux-gnu
15270 - x86_64-linux-gnu
15271 - x86_64-w64-mingw32
15272@end example
15273
15274The targets are specified as GNU triplets (@pxref{Specifying Target
15275Triplets, GNU configuration triplets,, autoconf, Autoconf}).
15276
15277Those triplets are passed to GCC and the other underlying compilers
15278possibly involved when building a package, a system image or any other
15279GNU Guix output.
15280
15281@example
15282$ guix build --target=aarch64-linux-gnu hello
15283/gnu/store/9926by9qrxa91ijkhw9ndgwp4bn24g9h-hello-2.12
15284
15285$ file /gnu/store/9926by9qrxa91ijkhw9ndgwp4bn24g9h-hello-2.12/bin/hello
15286/gnu/store/9926by9qrxa91ijkhw9ndgwp4bn24g9h-hello-2.12/bin/hello: ELF
1528764-bit LSB executable, ARM aarch64 @dots{}
15288@end example
15289
15290The major benefit of cross-compilation is that there are no performance
15291penaly compared to emulation using QEMU. There are however higher risks
15292that some packages fail to cross-compile because few GNU Guix users are
15293using this mecanism extensively.
15294
15295@node Using native building
15296@section Using native building
15297
15298The GNU Guix commands that support impersonating a specific system have
15299the @option{--list-systems} and @option{--system} options.
15300
15301The @option{--list-systems} option lists all the supported systems that
15302can be passed as an argument to @option{--system}.
15303
15304@example
15305$ guix build --list-systems
15306The available systems are:
15307
15308 - x86_64-linux [current]
15309 - aarch64-linux
15310 - armhf-linux
15311 - i586-gnu
15312 - i686-linux
15313 - mips64el-linux
15314 - powerpc-linux
15315 - powerpc64le-linux
15316 - riscv64-linux
15317 - s390x-linux
15318
15319$ guix build --system=i686-linux hello
15320/gnu/store/cc0km35s8x2z4pmwkrqqjx46i8b1i3gm-hello-2.12
15321
15322$ file /gnu/store/cc0km35s8x2z4pmwkrqqjx46i8b1i3gm-hello-2.12/bin/hello
15323/gnu/store/cc0km35s8x2z4pmwkrqqjx46i8b1i3gm-hello-2.12/bin/hello: ELF
1532432-bit LSB executable, Intel 80386 @dots{}
15325@end example
15326
15327In the above example, the GNU Guix current system is @var{x86_64-linux}.
15328The @var{hello} package is however built for the @var{i686-linux}
15329system.
15330
15331This is possible because the @var{i686} CPU instruction set is a subset
15332of the @var{x86_64}, hence @var{i686} targeting binaries can be run on
15333@var{x86_64}.
15334
15335Still in the context of the previous example, if picking the
15336@var{aarch64-linux} system and the @command{guix build
15337--system=aarch64-linux hello} has to build some derivations, an extra
15338step might be needed.
15339
15340The @var{aarch64-linux} targeting binaries cannot directly be run on a
15341@var{x86_64-linux} system. An emulation layer is requested. The GNU
15342Guix daemon can take advantage of the Linux kernel
15343@uref{https://en.wikipedia.org/wiki/Binfmt_misc,binfmt_misc} mechanism
15344for that. In short, the Linux kernel can defer the execution of a
15345binary targeting a foreign platform, here @var{aarch64-linux}, to a
15346userspace program, usually an emulator.
15347
15348There is a GNU Guix service that registers QEMU as a backend for the
15349@code{binfmt_misc} mechanism (@pxref{Virtualization Services,
15350@code{qemu-binfmt-service-type}}). On Debian based foreign
15351distributions, the alternative would be the @code{qemu-user-static}
15352package.
15353
15354If the @code{binfmt_misc} mechanism is not setup correctly, the building
15355will fail this way:
15356
15357@example
15358$ guix build --system=armhf-linux hello --check
15359@dots{}
15360@ unsupported-platform /gnu/store/jjn969pijv7hff62025yxpfmc8zy0aq0-hello-2.12.drv aarch64-linux
15361while setting up the build environment: a `aarch64-linux' is required to
15362build `/gnu/store/jjn969pijv7hff62025yxpfmc8zy0aq0-hello-2.12.drv', but
15363I am a `x86_64-linux'@dots{}
15364@end example
15365
15366whereas, with the @code{binfmt_misc} mechanism correctly linked with
15367QEMU, one can expect to see:
15368
15369@example
15370$ guix build --system=armhf-linux hello --check
15371/gnu/store/13xz4nghg39wpymivlwghy08yzj97hlj-hello-2.12
15372@end example
15373
15374The main advantage of native building compared to cross-compiling, is
15375that more packages are likely to build correctly. However it comes at a
15376price: compilation backed by QEMU is @emph{way slower} than
15377cross-compilation, because every instruction needs to be emulated.
15378
15379The availability of substitutes for the architecture targeted by the
15380@code{--system} option can mitigate this problem. An other way to work
15381around it is to install GNU Guix on a machine which CPU is supporting
15382the targeted instruction set, an set it up as an offload machine
15383(@pxref{Daemon Offload Setup}).
15384
15214@node System Configuration 15385@node System Configuration
15215@chapter System Configuration 15386@chapter System Configuration
15216 15387