* [PATCH] doc: add Creating a New Cross Target.
@ 2016-12-07 16:47 Jan Nieuwenhuizen
2016-12-21 16:33 ` Ludovic Courtès
0 siblings, 1 reply; 2+ messages in thread
From: Jan Nieuwenhuizen @ 2016-12-07 16:47 UTC (permalink / raw)
To: guix-devel
[-- Attachment #1: Type: text/plain, Size: 101 bytes --]
Hi,
Here's my doc draft on the cross build system. Suggestions/additions
welcome!
Greetings,
Jan
[-- Attachment #2: 0001-doc-add-Creating-a-New-Cross-Target.patch --]
[-- Type: text/x-patch, Size: 8767 bytes --]
From e887762bd07d77b68ff19b0ced3ab41c15faa1ac Mon Sep 17 00:00:00 2001
From: Jan Nieuwenhuizen <janneke@gnu.org>
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::
System Installation
@@ -259,6 +260,12 @@ Coding Style
* Data Types and Pattern Matching:: Implementing data structures.
* Formatting Code:: Writing conventions.
+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
@@ -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
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.
+@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{<target>}}, which depends on
+@code{cross-binutils-@var{<target>}} a @code{libc-@var{<target>}} and
+possibly @code{kernel-headers-@var{<target>}}. 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{<target>}}. 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 <http://gcc.gnu.org/ml/gcc/2013-02/msg00124.html>
+@c <http://bugs.gnu.org/22186> and
+@c <https://lists.gnu.org/archive/html/guix-devel/2016-04/msg00533.html>
+@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{<target>-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ïmplementation 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=i686-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
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))
(define-public mingw-w64
(package
--
2.10.2
[-- Attachment #3: Type: text/plain, Size: 154 bytes --]
--
Jan Nieuwenhuizen <janneke@gnu.org> | GNU LilyPond http://lilypond.org
Freelance IT http://JoyofSource.com | Avatar® http://AvatarAcademy.nl
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [PATCH] doc: add Creating a New Cross Target.
2016-12-07 16:47 [PATCH] doc: add Creating a New Cross Target Jan Nieuwenhuizen
@ 2016-12-21 16:33 ` Ludovic Courtès
0 siblings, 0 replies; 2+ messages in thread
From: Ludovic Courtès @ 2016-12-21 16:33 UTC (permalink / raw)
To: Jan Nieuwenhuizen; +Cc: guix-devel
Hi Jan!
Thanks for looking into it, and thanks for coping with the latency!
Jan Nieuwenhuizen <janneke@gnu.org> skribis:
> From e887762bd07d77b68ff19b0ced3ab41c15faa1ac Mon Sep 17 00:00:00 2001
> From: Jan Nieuwenhuizen <janneke@gnu.org>
> 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.
[...]
> +@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{<target>}}, which depends on
> +@code{cross-binutils-@var{<target>}} a @code{libc-@var{<target>}} and
> +possibly @code{kernel-headers-@var{<target>}}. 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{<target>}}. 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}.
I feel that some of it is redundant with, or should be added to
the “Porting” node. WDYT?
> +@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.
[...]
> +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
My gut feeling is that an explanation of why something gets rebuilt does
not belong here (it is not specific to cross-compilation). So I would
suggest putting it elsewhere; maybe we need a new “Developing with Guix”
section or similar, that would include this as well as “Defining
Packages” and “Programming Interface”, though I understand this goes
beyond this patch.
Another though is that we should provide a command to make it easier to
understand why something is rebuilt (we discussed this in Berlin last
week). I’m not sure exactly what that command’s output would look like,
but I would welcome mockups of what people would like to see, and we can
work from there.
WDYT?
> +@node GCC and Cross Environment Paths
> +@subsection GCC and Cross Environment Paths
> +
> +@c See <http://gcc.gnu.org/ml/gcc/2013-02/msg00124.html>
> +@c <http://bugs.gnu.org/22186> and
> +@c <https://lists.gnu.org/archive/html/guix-devel/2016-04/msg00533.html>
> +@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{<target>-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ïmplementation 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=i686-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
This sounds useful. The section about search paths is really about
internals (how does it work under the hood?), while the MinGW part is
more practical (how can I cross-compile to MinGW?).
Should we have a new “Cross Compilation” section that would primarily
focus on cross-compiling (as opposed to porting a new platform), and
then have a subsection about things going on under the hood?
I think my questions primarily highlight the weaknesses of the existing
structure of the document, more than problems with your suggestion.
Thanks,
Ludo’.
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2016-12-21 16:33 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-12-07 16:47 [PATCH] doc: add Creating a New Cross Target Jan Nieuwenhuizen
2016-12-21 16:33 ` Ludovic Courtès
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/guix.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.