path: root/doc/cross-compilation.xml

<chapter xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xml:id="chap-cross">
 <title>Cross-compilation</title>
 <section xml:id="sec-cross-intro">
  <title>Introduction</title>

  <para>
   "Cross-compilation" means compiling a program on one machine for another
   type of machine. For example, a typical use of cross compilation is to
   compile programs for embedded devices. These devices often don't have the
   computing power and memory to compile their own programs. One might think
   that cross-compilation is a fairly niche concern, but there are advantages
   to being rigorous about distinguishing build-time vs run-time environments
   even when one is developing and deploying on the same machine. Nixpkgs is
   increasingly adopting the opinion that packages should be written with
   cross-compilation in mind, and nixpkgs should evaluate in a similar way (by
   minimizing cross-compilation-specific special cases) whether or not one is
   cross-compiling.
  </para>

  <para>
   This chapter will be organized in three parts. First, it will describe the
   basics of how to package software in a way that supports cross-compilation.
   Second, it will describe how to use Nixpkgs when cross-compiling. Third, it
   will describe the internal infrastructure supporting cross-compilation.
  </para>
 </section>
<!--============================================================-->
 <section xml:id="sec-cross-packaging">
  <title>Packaging in a cross-friendly manner</title>

  <section xml:id="sec-cross-platform-parameters">
   <title>Platform parameters</title>

   <para>
    Nixpkgs follows the
    <link xlink:href="https://gcc.gnu.org/onlinedocs/gccint/Configure-Terms.html">common
    historical convention of GNU autoconf</link> of distinguishing between 3
    types of platform: <wordasword>build</wordasword>,
    <wordasword>host</wordasword>, and <wordasword>target</wordasword>. In
    summary, <wordasword>build</wordasword> is the platform on which a package
    is being built, <wordasword>host</wordasword> is the platform on which it
    is to run. The third attribute, <wordasword>target</wordasword>, is
    relevant only for certain specific compilers and build tools.
   </para>

   <para>
    In Nixpkgs, these three platforms are defined as attribute sets under the
    names <literal>buildPlatform</literal>, <literal>hostPlatform</literal>,
    and <literal>targetPlatform</literal>. All three are always defined as
    attributes in the standard environment, and at the top level. That means
    one can get at them just like a dependency in a function that is imported
    with <literal>callPackage</literal>:
<programlisting>{ stdenv, buildPlatform, hostPlatform, fooDep, barDep, .. }: ...buildPlatform...</programlisting>
    , or just off <varname>stdenv</varname>:
<programlisting>{ stdenv, fooDep, barDep, .. }: ...stdenv.buildPlatform...</programlisting>
    .
   </para>

   <variablelist>
    <varlistentry>
     <term>
      <varname>buildPlatform</varname>
     </term>
     <listitem>
      <para>
       The "build platform" is the platform on which a package is built. Once
       someone has a built package, or pre-built binary package, the build
       platform should not matter and be safe to ignore.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <varname>hostPlatform</varname>
     </term>
     <listitem>
      <para>
       The "host platform" is the platform on which a package will be run. This
       is the simplest platform to understand, but also the one with the worst
       name.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <varname>targetPlatform</varname>
     </term>
     <listitem>
      <para>
       The "target platform" attribute is, unlike the other two attributes, not
       actually fundamental to the process of building software. Instead, it is
       only relevant for compatibility with building certain specific compilers
       and build tools. It can be safely ignored for all other packages.
      </para>
      <para>
       The build process of certain compilers is written in such a way that the
       compiler resulting from a single build can itself only produce binaries
       for a single platform. The task specifying this single "target platform"
       is thus pushed to build time of the compiler. The root cause of this
       mistake is often that the compiler (which will be run on the host) and
       the the standard library/runtime (which will be run on the target) are
       built by a single build process.
      </para>
      <para>
       There is no fundamental need to think about a single target ahead of
       time like this. If the tool supports modular or pluggable backends, both
       the need to specify the target at build time and the constraint of
       having only a single target disappear. An example of such a tool is
       LLVM.
      </para>
      <para>
       Although the existence of a "target platfom" is arguably a historical
       mistake, it is a common one: examples of tools that suffer from it are
       GCC, Binutils, GHC and Autoconf. Nixpkgs tries to avoid sharing in the
       mistake where possible. Still, because the concept of a target platform
       is so ingrained, it is best to support it as is.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>

   <para>
    The exact schema these fields follow is a bit ill-defined due to a long and
    convoluted evolution, but this is slowly being cleaned up. You can see
    examples of ones used in practice in
    <literal>lib.systems.examples</literal>; note how they are not all very
    consistent. For now, here are few fields can count on them containing:
   </para>

   <variablelist>
    <varlistentry>
     <term>
      <varname>system</varname>
     </term>
     <listitem>
      <para>
       This is a two-component shorthand for the platform. Examples of this
       would be "x86_64-darwin" and "i686-linux"; see
       <literal>lib.systems.doubles</literal> for more. This format isn't very
       standard, but has built-in support in Nix, such as the
       <varname>builtins.currentSystem</varname> impure string.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <varname>config</varname>
     </term>
     <listitem>
      <para>
       This is a 3- or 4- component shorthand for the platform. Examples of
       this would be "x86_64-unknown-linux-gnu" and "aarch64-apple-darwin14".
       This is a standard format called the "LLVM target triple", as they are
       pioneered by LLVM and traditionally just used for the
       <varname>targetPlatform</varname>. This format is strictly more
       informative than the "Nix host double", as the previous format could
       analogously be termed. This needs a better name than
       <varname>config</varname>!
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <varname>parsed</varname>
     </term>
     <listitem>
      <para>
       This is a nix representation of a parsed LLVM target triple with
       white-listed components. This can be specified directly, or actually
       parsed from the <varname>config</varname>. [Technically, only one need
       be specified and the others can be inferred, though the precision of
       inference may not be very good.] See
       <literal>lib.systems.parse</literal> for the exact representation.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <varname>libc</varname>
     </term>
     <listitem>
      <para>
       This is a string identifying the standard C library used. Valid
       identifiers include "glibc" for GNU libc, "libSystem" for Darwin's
       Libsystem, and "uclibc" for µClibc. It should probably be refactored to
       use the module system, like <varname>parse</varname>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <varname>is*</varname>
     </term>
     <listitem>
      <para>
       These predicates are defined in <literal>lib.systems.inspect</literal>,
       and slapped on every platform. They are superior to the ones in
       <varname>stdenv</varname> as they force the user to be explicit about
       which platform they are inspecting. Please use these instead of those.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <varname>platform</varname>
     </term>
     <listitem>
      <para>
       This is, quite frankly, a dumping ground of ad-hoc settings (it's an
       attribute set). See <literal>lib.systems.platforms</literal> for
       examples—there's hopefully one in there that will work verbatim for
       each platform that is working. Please help us triage these flags </