Re: [PATCH] doc: add Creating a New Cross Target.

[ludo@gnu.org (Ludovic Courtès)]

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’.