From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp10.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id YE76LoUDeGIeFgAAbAwnHQ (envelope-from ) for ; Sun, 08 May 2022 19:53:09 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp10.migadu.com with LMTPS id MBX2LYUDeGJyEQAAG6o9tA (envelope-from ) for ; Sun, 08 May 2022 19:53:09 +0200 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 04C72111BC for ; Sun, 8 May 2022 19:53:09 +0200 (CEST) Received: from localhost ([::1]:40992 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nnl5f-0007Oq-Hy for larch@yhetil.org; Sun, 08 May 2022 13:53:07 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:52884) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nnl5a-0007Og-Vt for guix-patches@gnu.org; Sun, 08 May 2022 13:53:03 -0400 Received: from debbugs.gnu.org ([209.51.188.43]:33048) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1nnl5a-0007WO-MG for guix-patches@gnu.org; Sun, 08 May 2022 13:53:02 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1nnl5a-00057Y-JL for guix-patches@gnu.org; Sun, 08 May 2022 13:53:02 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#55321] Document building for foreign architectures Resent-From: Mathieu Othacehe Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Sun, 08 May 2022 17:53:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 55321 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: To: 55321@debbugs.gnu.org X-Debbugs-Original-To: guix-patches@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.165203236419646 (code B ref -1); Sun, 08 May 2022 17:53:02 +0000 Received: (at submit) by debbugs.gnu.org; 8 May 2022 17:52:44 +0000 Received: from localhost ([127.0.0.1]:55178 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nnl5H-00056o-MG for submit@debbugs.gnu.org; Sun, 08 May 2022 13:52:44 -0400 Received: from lists.gnu.org ([209.51.188.17]:50072) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nnl5G-00056g-13 for submit@debbugs.gnu.org; Sun, 08 May 2022 13:52:42 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:52816) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nnl5F-0007OO-Pd for guix-patches@gnu.org; Sun, 08 May 2022 13:52:41 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:36414) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nnl5F-0007Vp-HB for guix-patches@gnu.org; Sun, 08 May 2022 13:52:41 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:Subject:To:From:in-reply-to: references; bh=zs2yC3ksNgeH7c/mVW3VnIuYiMusMkdsvNpPTZ+KG2g=; b=A3R69Aaxc6ZWFH BqzFyi5xKtsb7AYHcf4ahgri4uKv/NrPRZIhgLYPxGsM9bTLFcMCnHGrm/2SSiAbx3okMlHbHg3XF h3qtmDz1GDEXgbuR8kPTeNCzrXlGzbAxkanz7eYR365tR9dD6GBZXlww2mZul2kxI+V+Z5Q2WLXVB SjDDcj+fok4M9mxELC7eNPwuHpwv53PSBUHz8iPGExtpa4txZ6qKJLUN3r2is0IcyhA5J743xdOiP n55mcxGt5E3Ss+ZAqOe48tbs8c/15h4zYa/hlcLydwIhwHKcHzlouuQwugYI5XTps6avyymalxeYr Smk4LxFBL9UZBcKkIFOw==; Received: from 71.125.192.77.rev.sfr.net ([77.192.125.71]:40362 helo=meije) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nnl5E-0002lN-Uf for guix-patches@gnu.org; Sun, 08 May 2022 13:52:41 -0400 From: Mathieu Othacehe User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) Date: Sun, 08 May 2022 19:52:38 +0200 Message-ID: <87k0avdi8p.fsf@gnu.org> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+larch=yhetil.org@gnu.org Sender: "Guix-patches" X-Migadu-Flow: FLOW_IN X-Migadu-To: larch@yhetil.org X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1652032389; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type:resent-cc:resent-from:resent-sender: resent-message-id:list-id:list-help:list-unsubscribe:list-subscribe: list-post:dkim-signature; bh=zs2yC3ksNgeH7c/mVW3VnIuYiMusMkdsvNpPTZ+KG2g=; b=dUGH8W3HWkJ3mI/ZMl+z1WbOn8DvBgdOuNn5trXePQa985aeSSvsgbT6OttGB6Hs+CWosY 9xBjfDeJ3jgOV3sx51K92RRzXEVa0fjezzipcaIb/eqCOFuQib1MNxgR7TDnlXyAJ7tcN7 eKEtd9jAAzO7nGyVTGETKia2e4n6kcP5zEE3btPjp+t5r2/jI0p1imc0nOklVeZd/oHtDM 1j3hCkafgQIH+z9bKA/MpoF/E9/yucOhxuniIqIzeKoB/l9o5iU4pOp6eR3DFwmWPKw7yz iwVIe+KkBHTZGYdoJTn32ti+pQg2+/TUDSeYuuiwg3JAM86jNfQFQ8u9Ql2gFw== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1652032389; a=rsa-sha256; cv=none; b=eFAFbBY9BIiXJBMC3X/cIijT9cWH5T8niQunFCi5WiiVzLZIXyM8SjXGG89WnYCLck7nPH cF5JCGP5GEMbQIA2Ba9UjorciY0tqh6Pjy0OrSrK+ACCScBwN4J/pL2M3a0uHDnG21m8uI wpqmCMSzwwFqkAkMWBUWx5M1dBxSC6oW5YZB1JsE8/D5YR0xvOB31aWMY+j4kiZcbPF4iR vw8e7FHTCwTPxIr/hBp64kTQSafoVib31j/5LpxqjMIIIs4i3LChV1kgXwwzHgqhaud/KU b2N+ieH2+B4rYziXg8WmUqvMxgkL/+WZHR3YG18buixiccCKk3qJa1cMwPRcpQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gnu.org header.s=fencepost-gnu-org header.b=A3R69Aax; dmarc=pass (policy=none) header.from=gnu.org; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: -3.91 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gnu.org header.s=fencepost-gnu-org header.b=A3R69Aax; dmarc=pass (policy=none) header.from=gnu.org; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: 04C72111BC X-Spam-Score: -3.91 X-Migadu-Scanner: scn1.migadu.com X-TUID: tOlNoYRubJXx --=-=-= Content-Type: text/plain Hello, This is a follow-up of https://issues.guix.gnu.org/55220 that is still in discussion. If we were to create a top 10 of the most asked questions on #guix, "What is --target, what's the difference with --system?", and "Why --system=aarch64-linux isn't working on my machine?" would be in good position I guess. This patch builds upon the proposed introduction of --list-systems/--list-targets options as well as --system/--target argument checking to document how to build for foreign architectures. I hope that this will shed some light on the matter. Thanks, Mathieu --=-=-= Content-Type: text/x-patch Content-Disposition: inline; filename=0001-scripts-build-Highlight-the-current-system-with-list.patch >From e1fde962a334c6a5c0f855aaf3e11fa9ea73b2d0 Mon Sep 17 00:00:00 2001 From: Mathieu Othacehe Date: Sun, 8 May 2022 18:52:33 +0200 Subject: [PATCH 1/2] scripts: build: Highlight the current system with --list-systems. * guix/scripts/build.scm (list-systems): Highlight it. --- guix/scripts/build.scm | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/guix/scripts/build.scm b/guix/scripts/build.scm index a09c54451f..4383a399a0 100644 --- a/guix/scripts/build.scm +++ b/guix/scripts/build.scm @@ -21,6 +21,7 @@ (define-module (guix scripts build) #:use-module (guix ui) + #:use-module (guix colors) #:use-module (guix scripts) #:autoload (guix import json) (json->scheme-file) #:use-module (guix store) @@ -342,8 +343,15 @@ (define (list-systems) "Print the available systems." (display (G_ "The available systems are:\n")) (newline) - (format #t "~{ - ~a ~%~}" - (sort (systems) stringFrom 3d70b0f67a0bcbe16d6f5eaea47410a3f526af05 Mon Sep 17 00:00:00 2001 From: Mathieu Othacehe Date: Sun, 8 May 2022 19:43:47 +0200 Subject: [PATCH 2/2] doc: Add a 'Foreign architectures' chapter. * doc/guix.texi ("Foreign architectures"): New chapter. --- doc/guix.texi | 173 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 172 insertions(+), 1 deletion(-) diff --git a/doc/guix.texi b/doc/guix.texi index 1dc1474ec7..55c0049411 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -41,7 +41,7 @@ Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021= Julien Lepiller@* Copyright @copyright{} 2016 Alex ter Weele@* Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Christopher Bain= es@* Copyright @copyright{} 2017, 2018, 2019 Cl=C3=A9ment Lassieur@* -Copyright @copyright{} 2017, 2018, 2020, 2021 Mathieu Othacehe@* +Copyright @copyright{} 2017, 2018, 2020, 2021, 2022 Mathieu Othacehe@* Copyright @copyright{} 2017 Federico Beffa@* Copyright @copyright{} 2017, 2018 Carlo Zancanaro@* Copyright @copyright{} 2017 Thomas Danckaert@* @@ -173,6 +173,7 @@ Weblate} (@pxref{Translating Guix}). * Development:: Guix-aided software development. * Programming Interface:: Using Guix in Scheme. * Utilities:: Package management commands. +* Foreign architectures:: Build for foreign architectures. * System Configuration:: Configuring the operating system. * Home Configuration:: Configuring the home environment. * Documentation:: Browsing software user manuals. @@ -320,6 +321,10 @@ Invoking @command{guix build} * Additional Build Options:: Options specific to 'guix build'. * Debugging Build Failures:: Real life packaging experience. =20 +Foreign architectures +* Using cross-compilation:: Build for foreign architecture using cross-co= mpilation. +* Using native building:: Build for foreign architectures natively. + System Configuration =20 * Using the Configuration System:: Customizing your GNU system. @@ -14814,6 +14819,172 @@ Session_PID: 4278 @end table @end table =20 +@node Foreign architectures +@chapter Foreign architectures + +You might need to use GNU Guix to produce packages (@pxref{Invoking guix +package}), packs (@pxref{Invoking guix pack}) or even full systems +(@pxref{Invoking guix system}) targeting computers with different CPU +architectures than the one of your current CPU. + +GNU Guix supports two distinct mechanisms to target foreign +architectures: + +@enumerate +@item +The first one is the traditional +@uref{https://en.wikipedia.org/wiki/Cross_compiler,cross-compilation} +mechanism. +@item +The second one, called native building, consists in building using the +CPU instruction set of the foreign system you are targeting. It often +requires emulation, using the QEMU program for instance. +@end enumerate + +@menu +* Using cross-compilation:: Build for foreign architecture using cross-co= mpilation. +* Using native building:: Build for foreign architectures natively. +@end menu + +@node Using cross-compilation +@section Using cross-compilation + +@cindex foreign architectures +The GNU Guix commands supporting cross-compilation are proposing the +@option{--list-targets} and @option{--target} options. + +The @option{--list-targets} option lists all the supported targets that +can be passed as an argument to @option{--target}. + +@example +$ guix build --list-targets +The available targets are: + + - aarch64-linux-gnu + - arm-linux-gnueabihf + - i586-pc-gnu + - i686-linux-gnu + - i686-w64-mingw32 + - mips64el-linux-gnu + - powerpc-linux-gnu + - powerpc64le-linux-gnu + - riscv64-linux-gnu + - s390x-linux-gnu + - x86_64-linux-gnu + - x86_64-w64-mingw32 +@end example + +The targets are specified as GNU triplets (@pxref{Specifying Target +Triplets, GNU configuration triplets,, autoconf, Autoconf}). + +Those triplets are passed to GCC and the other underlying compilers +possibly involved when building a package, a system image or any other +GNU Guix output. + +@example +$ guix build --target=3Daarch64-linux-gnu hello +/gnu/store/9926by9qrxa91ijkhw9ndgwp4bn24g9h-hello-2.12 + +$ file /gnu/store/9926by9qrxa91ijkhw9ndgwp4bn24g9h-hello-2.12/bin/hello +/gnu/store/9926by9qrxa91ijkhw9ndgwp4bn24g9h-hello-2.12/bin/hello: ELF +64-bit LSB executable, ARM aarch64 @dots{} +@end example + +The major benefit of cross-compilation is that there are no performance +penalties compared to emulation using QEMU. There are however higher +risks that some packages are failing to cross-compile because few GNU +Guix users are using this mecanism extensively. + +@node Using native building +@section Using native building + +The GNU Guix commands supporting to impersonate a specific system are +proposing the @option{--list-systems} and @option{--system} options. + +The @option{--list-systems} option lists all the supported systems that +can be passed as an argument to @option{--system}. + +@example +$ guix build --list-systems +The available systems are: + + - x86_64-linux [current] + - aarch64-linux + - armhf-linux + - i586-gnu + - i686-linux + - mips64el-linux + - powerpc-linux + - powerpc64le-linux + - riscv64-linux + - s390x-linux + +$ guix build --system=3Di686-linux hello +/gnu/store/cc0km35s8x2z4pmwkrqqjx46i8b1i3gm-hello-2.12 + +$ file /gnu/store/cc0km35s8x2z4pmwkrqqjx46i8b1i3gm-hello-2.12/bin/hello +/gnu/store/cc0km35s8x2z4pmwkrqqjx46i8b1i3gm-hello-2.12/bin/hello: ELF +32-bit LSB executable, Intel 80386 @dots{} +@end example + +In the above example, the GNU Guix current system is @var{x86_64-linux}. +The @var{hello} package is however built for the @var{i686-linux} +system. + +This is possible because the @var{i686} CPU instruction set is a subset +of the @var{x86_64}, hence @var{i686} targeting binaries can be run on +@var{x86_64}. + +Still in the context of the previous example, if picking the +@var{aarch64-linux} system and the @command{guix build +--system=3Daarch64-linux hello} has to build some derivations, an extra +step might be needed. + +The @var{aarch64-linux} targeting binaries cannot directly be run on a +@var{x86_64-linux} system. An emulation layer is requested. The GNU +Guix daemon can take advantage of the Linux kernel +@uref{https://en.wikipedia.org/wiki/Binfmt_misc,binfmt_misc} mechanism +for that. In short, the Linux kernel can defer the execution of a +binary targeting a foreign platform, here @var{aarch64-linux}, to a +userspace program, usually an emulator. + +There is a GNU Guix service that registers QEMU as a backend for the +@code{binfmt_misc} mechanism (@pxref{Virtualization Services, +@code{qemu-binfmt-service-type}}). On Debian based foreign +distributions, the alternative would be the @code{qemu-user-static} +package. + +If the @code{binfmt_misc} mechanism is not setup correctly, the building +will fail this way: + +@example +$ guix build --system=3Darmhf-linux hello --check +@dots{} +@ unsupported-platform /gnu/store/jjn969pijv7hff62025yxpfmc8zy0aq0-hello-2= .12.drv aarch64-linux +while setting up the build environment: a `aarch64-linux' is required to +build `/gnu/store/jjn969pijv7hff62025yxpfmc8zy0aq0-hello-2.12.drv', but +I am a `x86_64-linux'@dots{} +@end example + +whereas, with the @code{binfmt_misc} mechanism correctly linked with +QEMU, one can expect to see: + +@example +$ guix build --system=3Darmhf-linux hello --check + +@end example + +The main advantage of native building compared to cross-compiling, is +that more packages are likely to build correctly. However it comes at a +price: compilation backed by QEMU is @emph{way slower} than +cross-compilation, because every instruction needs to be emulated. + +The availability of substitutes for the architecture targeted by the +@code{--system} option can mitigate this problem. An other way to work +around it is to install GNU Guix on a machine which CPU is supporting +the targeted instruction set, an set it up as an offload machine +(@pxref{Daemon Offload Setup}). + @node System Configuration @chapter System Configuration =20 --=20 2.36.0 --=-=-=--