From mboxrd@z Thu Jan 1 00:00:00 1970 From: Jan Nieuwenhuizen Subject: [PATCH] doc: add Creating a New Cross Target. Date: Wed, 07 Dec 2016 17:47:14 +0100 Message-ID: <87shpzelf1.fsf@gnu.org> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:58460) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cEfNb-0001vn-Sh for guix-devel@gnu.org; Wed, 07 Dec 2016 11:47:41 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cEfNX-0001k9-Pb for guix-devel@gnu.org; Wed, 07 Dec 2016 11:47:39 -0500 List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: "Guix-devel" To: guix-devel@gnu.org --=-=-= Content-Type: text/plain Hi, Here's my doc draft on the cross build system. Suggestions/additions welcome! Greetings, Jan --=-=-= Content-Type: text/x-patch; charset=utf-8 Content-Disposition: inline; filename=0001-doc-add-Creating-a-New-Cross-Target.patch Content-Transfer-Encoding: quoted-printable >From e887762bd07d77b68ff19b0ced3ab41c15faa1ac Mon Sep 17 00:00:00 2001 From: Jan Nieuwenhuizen Date: Wed, 7 Dec 2016 17:45:29 +0100 Subject: [PATCH] doc: add Creating a New Cross Target. * doc/guix.texi: Add Creating a New Cross Target. --- doc/guix.texi | 170 +++++++++++++++++++++++++++++++++++++++++++++= ++++ gnu/packages/mingw.scm | 6 +- 2 files changed, 171 insertions(+), 5 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index 738b7fb..91a83e9 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -182,6 +182,7 @@ GNU Distribution * Packaging Guidelines:: Growing the distribution. * Bootstrapping:: GNU/Linux built from scratch. * Porting:: Targeting another platform or kernel. +* Creating a New Cross Target:: =20 System Installation =20 @@ -259,6 +260,12 @@ Coding Style * Data Types and Pattern Matching:: Implementing data structures. * Formatting Code:: Writing conventions. =20 +Creating a New Cross Target + +* Rebuilding My World:: How to avoid rebuilding too often. +* GCC and Cross Environment Paths:: Details on the cross build setup. +* The MinGW Cross Target:: Some notes on MinGW. + @end detailmenu @end menu =20 @@ -6457,6 +6464,7 @@ For information on porting to other architectures or = kernels, * Packaging Guidelines:: Growing the distribution. * Bootstrapping:: GNU/Linux built from scratch. * Porting:: Targeting another platform or kernel. +* Creating a New Cross Target:: @end menu =20 Building this distribution is a cooperative effort, and you are invited @@ -14361,6 +14369,168 @@ Second, some of the required packages could fail = to build for that platform. Lastly, the generated binaries could be broken for some reason. =20 +@node Creating a New Cross Target +@section Creating a New Cross Target + +As a first step of making a full port, you may want to start by creating +a cross target. A cross target in essence is a cross compiler +@code{cross-gcc-@var{}}, which depends on +@code{cross-binutils-@var{}} a @code{libc-@var{}} and +possibly @code{kernel-headers-@var{}}. Several cross targets +are available, such as @code{i586-pc-hurd}, @code{armhf-linux}, +@code{avr}, @code{i686-w64-mingw32} and @code{mips64el-linux}. + +Building a full gcc cross compiler depends on a c-library for the +target. We can build a c-library for the target once we have a cross +compiler. To break this loop a minimal gcc compiler can be built +without a c-library; we call this +@code{gcc-cross-sans-libc-@var{}}. With this minimal gcc +compiler we cross compile the c-library and then we build the full cross +gcc. + +In @code{gnu/packages/cross-base.scm} are functions to create these +cross packages. Also, Guix needs to know the name of the dynamic +linker, see @var{glibc-dynamic-linker} in +@code{gnu/packages/bootstrap.scm}. + +@menu +* Rebuilding My World:: How to avoid rebuilding too often. +* GCC and Cross Environment Paths:: Details on the cross build setup. +* The MinGW Cross Target:: Some notes on MinGW. +@end menu + +@node Rebuilding My World +@subsection Rebuilding My World + +Why is it that we all tend love to rebuild our world, yet like it +somewhat less when others decide do it for us? One of the great things +of Guix is that it tracks all dependencies and will rebuild any package +that is out of date: We never have to worry that doing a fresh, clean +build does not reproduce. + +However, if we make the tiniest change for our cross build to the +@var{ncurses} package then Guix will first rebuild world before starting +the cross-build. If we made a silly typo in the cross-build recipe, it +takes a long time to get feedback on that. + +Say our target is to cross-build @var{Guile} which needs a cross-built +@var{readline} which requires making a change to the @var{ncurses} +package. What we can do is create a temporary alternative package +hierarchy. We copy @var{ncurses} to @var{cross-ncurses} + +@example +(define-public cross-ncurses + @dots{} + (name "cross-ncurses") + @dots{}) +@end example + +@noindent +and because we are really aiming for @var{readline}, we copy that too + +@example +(define-public cross-readline + @dots{} + (name "cross-readline") + @dots{} + (propagated-inputs `(("ncurses" ,cross-ncurses))) + @dots{}) +@end example + +@noindent +which we then use in our copied @var{cross-guile} package. We replace +the original packages descriptions with the @var{cross-} variants and +remove the @var{cross-} prefixes. + +Now it is time to check what the impact of our changes in @var{ncurses} + +@smallexample +$ ./pre-inst-env guix refresh -l ncurses +Building the following 1056 packages would ensure 2658 dependent packages = are rebuilt: @dots{} +@end smallexample + +When we are satisfied with our changes, we can enjoy our favorite +beverage while we having our worlds rebuild. If we decide the impact is +too great we can rewrite our changes in a way so that they do not change +the regular package recipe, e.g. + +@smallexample + (patches (search-patches "ncurses-mingw.patch")))) + @dots{} + (inputs + `(;; breaks with MinGW...not needed? ("coreutils" ,coreutils) + ("zlib" ,zlib))) +@end smallexample + +can be written as + +@smallexample + (patches (if (target-mingw?) + (search-patches "ncurses-mingw.patch") + '())))) + @dots{} + (inputs + `(;; fails with MinGW and could be removed unconditionally + ;; but that triggers a rebuild + ,@@(if (target-mingw?) + '() + `(("coreutils" ,coreutils))) + ("zlib" ,zlib)) +@end smallexample + +and the original non-cross build recipe remains identical to the +builder. + +@node GCC and Cross Environment Paths +@subsection GCC and Cross Environment Paths + +@c See +@c and +@c +@c for a discussion of what follows. +Some build systems compile and run programs at build time to generate +host-specific data. This means we usually have two compilers installed: +@code{gcc} and @code{-gcc}. Guix does not use +@file{/usr/include} and @file{/usr/lib} to install additional headers +and libraries, instead it adds to environment path variables such as +@var{C_INCLUDE_PATH} and @var{LIBRARY_PATH}. + +To distinguish between native build-time headers and libraries and +cross-built target system headers and libraries, we use a patched gcc as +cross compiler. The cross compiler instead looks at +@var{CROSS_C_INCLUDE_PATH} and @var{CROSS_LIBRARY_PATH}. + +@node The MinGW Cross Target +@subsection The MinGW Cross Target + +The MinGW target is somewhat special in that it does not support +@var{glibc}. @var{Gcc} needs to be passed the @code{--with-newlib} flag +and instead we use the combined c-library and free re=C3=AFmplementation of +Windows kernel-headers and system-libraries provided by the MinGW-w64 +project. Also, it's not POSIX so it often needs explicit support, +sometimes we need to create a patch ourselves. + +For standard libc headers and libraries that are missing in MinGW such +as @var{libiconv} and @var{gettext} helper functions are available + +@example + (inputs + @dots{} + ,@@(libiconv-if-needed) + ,@@(gnu-gettext-if-needed)) +@end example + +Finally, a simple example of how MinGW can be used/tested + +@example +$ guix build --target=3Di686-w64-mingw32 hello +@dots{} +/gnu/store/@dots{}-hello-2.10 +$ guix environment --ad-hoc wine +$ wine /gnu/store/@dots{}-hello-2.10/bin/hello.exe +Hello, world! +@end example + @c ********************************************************************* @include contributing.texi =20 diff --git a/gnu/packages/mingw.scm b/gnu/packages/mingw.scm index 4eb2c8f..dd9b597 100644 --- a/gnu/packages/mingw.scm +++ b/gnu/packages/mingw.scm @@ -21,14 +21,10 @@ #:use-module (gnu packages) #:use-module (gnu packages base) #:use-module (gnu packages cross-base) - #:use-module (gnu packages gcc) - #:use-module (gnu packages compression) - #:use-module (gnu packages multiprecision) #:use-module (guix build-system gnu) #:use-module (guix packages) #:use-module (guix download) - #:use-module (guix utils) - #:use-module (ice-9 match)) + #:use-module (guix utils)) =20 (define-public mingw-w64 (package --=20 2.10.2 --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable --=20 Jan Nieuwenhuizen | GNU LilyPond http://lilypond.org Freelance IT http://JoyofSource.com | Avatar=C2=AE http://AvatarAcademy.nl= =20=20 --=-=-=--