path: root/doc/stdenv/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. However, there are significant advantages to rigorously distinguishing between build-time and run-time environments! Significant, because the benefits apply 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="ssec-cross-platform-parameters">
   <title>Platform parameters</title>

   <para>
    Nixpkgs follows the <link
     xlink:href="https://gcc.gnu.org/onlinedocs/gccint/Configure-Terms.html">conventions of GNU autoconf</link>. We distinguish between 3 types of platforms when building a derivation: <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 will 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>. They are always defined as attributes in the standard environment. That means one can access them like:
<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 can be ignored.
      </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 of specifying this single "target platform" is thus pushed to build time of the compiler. The root cause of this is that the compiler (which will be run on the host) and 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. The first component corresponds to the CPU architecture of the platform and the second to the operating system of the platform (<literal>[cpu]-[os]</literal>). This format 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 <literal>x86_64-unknown-linux-gnu</literal> and <literal>aarch64-apple-darwin14</literal>. This is a standard format called the "LLVM target triple", as they are pioneered by LLVM. In the 4-part form, this corresponds to <literal>[cpu]-[vendor]-[os]-[abi]</literal>. 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>. 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 onto 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 and give them better homes!
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </section>

  <section xml:id="ssec-cross-dependency-categorization">
   <title>Theory of dependency categorization</title>

   <note>
    <para>
     This is a rather philosophical description that isn't very Nixpkgs-specific. For an overview of all the relevant attributes given to <varname>mkDerivation</varname>, see <xref
     linkend="ssec-stdenv-dependencies"/>. For a description of how everything is implemented, see <xref linkend="ssec-cross-dependency-implementation" />.
    </para>
   </note>

   <para>
    In this section we explore the relationship between both runtime and build-time dependencies and the 3 Autoconf platforms.
   </para>

   <para>
    A run time dependency between two packages requires that their host platforms match. This is directly implied by the meaning of "host platform" and "runtime dependency": The package dependency exists while both packages are running