doc/HOWTO-use-crosscompile

   1 Cross-compilation in pkgsrc (user's guide)              -*- outline -*-
   2 Taylor R. Campbell <riastradh@NetBSD.org>
   3
   4 $NetBSD$
   5
   6 The following steps enable you to build binary packages for a machine
   7 architecture other than the one you are building on.  For example, you
   8 might use them on your beefy umpteen-core amd64-based build machine
   9 (the `native' machine) to build packages for your feeble powerpc-based
  10 network appliance (the `target' machine).
  11
  12 These instructions assume you use the conventional privileged paths:
  13 /usr/src for the NetBSD source tree, /usr/obj for the NetBSD object
  14 tree, and /usr/pkgsrc for the pkgsrc tree.  If you want to do it
  15 unprivileged, see `* Unprivileged notes' below.
  16
  17 XXX This currently works only for NetBSD.
  18
  19 * Build NetBSD tools and distribution for the target system
  20
  21 Use build.sh to build NetBSD tools and a distribution, and remember
  22 what the destdir and tooldir are -- you'll need them for pkgsrc's
  23 mk.conf.
  24
  25    $ cd /usr/src
  26    $ ./build.sh -m evbppc tools
  27    $ ./build.sh -m evbppc distribution
  28
  29 By default, the destdir will be /usr/obj/destdir.evbppc, and the
  30 tooldir will be (say) /usr/obj/tooldir.NetBSD-6.1.amd64 if you're
  31 running NetBSD 6.1 on amd64.
  32
  33 * Set up mk.conf
  34
  35 In addition to whatever else you want in your mk.conf for pkgsrc, add:
  36
  37    # Cross-compile by default.
  38    #
  39    # XXX This currently can't be set to `yes' on the command line,
  40    # which is a bug.
  41    USE_CROSS_COMPILE?=  yes
  42
  43    # This is a kludge for cross-libtool.
  44    #
  45    # XXX Should not need this.
  46    CROSSBASE=           ${LOCALBASE}/cross-${TARGET_ARCH:U${MACHINE_ARCH}}
  47
  48    .if !empty(USE_CROSS_COMPILE:M[yY][eE][sS])
  49    # Specify the machine architecture of target packages.
  50    #
  51    # XXX This currently can't be set on the command line, which is a
  52    # bug.
  53    MACHINE_ARCH=        powerpc
  54
  55    # Point pkgsrc at the NetBSD tooldir and destdir.
  56    #
  57    # XXX There is no obvious variable that is set to amd64 so that we
  58    # could use
  59    #
  60    #    TOOLDIR=        /usr/obj/tooldir.${OPSYS}-${OS_VERSION}.${NATIVE_xyz}
  61    #
  62    # MACHINE is amd64 but, since it's not NATIVE_xyz, it's wrong.
  63    # NATIVE_MACHINE_ARCH is x86_64, not amd64.
  64    TOOLDIR=             /usr/obj/tooldir.NetBSD-6.1.amd64
  65    CROSS_DESTDIR=       /usr/obj/destdir.evbppc
  66
  67    # Put target work and packages in separate directories.  (You might
  68    # use OBJMACHINE=yes or WRKOBJDIR=/tmp/work.${MACHINE_ARCH} instead
  69    # for the work directories.)
  70    #
  71    # XXX Should not need this.
  72    PACKAGES=            ${PKGSRCDIR}/packages.${MACHINE_ARCH}
  73    WRKDIR_BASENAME=     work.${MACHINE_ARCH}
  74    .endif
  75
  76 You can bootstrap pkgsrc or not; it shouldn't make a difference for
  77 cross-compilation.  If you do, replace `make' by `bmake' below, of
  78 course.
  79
  80 XXX Some variables, notably LOCALBASE and other paths that get baked
  81 into packages, cannot currently be set differently for native and
  82 target packages.
  83
  84 * Work around libtool
  85
  86 Libtool's build system is broken -- it misuses the GNU build system
  87 build/host/target settings.  For now we need to kludge around it
  88 manually:
  89
  90    $ cd /usr/pkgsrc/cross/libtool-base
  91    $ make package
  92    $ pkg_add -m powerpc /usr/pkgsrc/packages.powerpc/All/cross-libtool-base-powerpc-2.4.2.tgz
  93
  94 (This builds a libtool package for the target, and then installs the
  95 target package natively.  This *shouldn't* work, and pkg_add normally
  96 refuses this, but it does work because libtool is a shell script, and
  97 `pkg_add -m powerpc' makes pkg_add pretend we are powerpc to suppress
  98 its refusal.)
  99
 100 * Make some packages
 101
 102 Now packages you build normally will be cross-compiled for the target:
 103
 104    $ cd /usr/pkgsrc/net/isc-dhcpd4 && make package
 105
 106 You can find the shiny new powerpc package at
 107
 108    /usr/pkgsrc/packages.powerpc/
 109
 110 Any packages needed on natively to build the target packages will be
 111 built and installed automatically, but if for some reason you want to
 112 build a native package, you can run
 113
 114    $ cd /usr/pkgsrc/net/isc-dhcpd4 && make package USE_CROSS_COMPILE=no
 115
 116 XXX Note that currently you cannot omit USE_CROSS_COMPILE?=yes from
 117 your mk.conf and pass USE_CROSS_COMPILE=yes on the make command line.
 118 This is a bug.
 119
 120 * Unprivileged notes
 121
 122 I do all this stuff unprivileged in directories under my home
 123 directory so that it's easy for me to nuke build products without
 124 messing with the package installations I use for development.
 125
 126    NetBSD srcdir:       ~/netbsd/current/src
 127    NetBSD objdir:       ~/netbsd/current/obj.evbppc
 128    NetBSD tooldir:      ~/netbsd/current/obj.evbppc/tooldir.NetBSD-6.1.amd64
 129    NetBSD destdir:      ~/netbsd/current/obj.evbppc/destdir.evbppc
 130    pkgsrc:              ~/pkgsrc/current/pkgsrc
 131    pkgsrc LOCALBASE:    ~/pkgsrc/current/pkg
 132
 133 (~/netbsd/current/src and ~/pkgsrc/current/pkgsrc are actually
 134 read-only null mounts of ~/netbsd/current/src-cvs and
 135 ~/pkgsrc/current/pkgsrc-cvs, respectively.)
 136
 137 To build NetBSD, I run:
 138
 139    $ cd ~/netbsd/current/src
 140    $ ./build.sh -O ../obj.evbppc -U -u -m evbppc -j12 tools
 141    $ ./build.sh -O ../obj.evbppc -U -u -m evbppc -j12 distribution
 142
 143 My mk.conf additionally has UNPRIVILEGED=yes, and I bootstrap pkgsrc
 144 with
 145
 146    $ cd ~/pkgsrc/current/pkgsrc/bootstrap
 147    $ ./bootstrap \
 148         --gzip-binary-kit ~/pkgsrc/current/bootstrap/20130422.tgz \
 149         --mk-fragment ~/pkgsrc/current/bootstrap/20130422.mk \
 150         --prefix ~/pkgsrc/current/pkg \
 151         --unprivileged \
 152         --workdir /tmp/bootwork
 153
 154 and various other crud to customize the build and package options.
 155 This requires putting ~/pkgsrc/current/pkg/{bin,sbin} before
 156 /usr/{bin,sbin} in your PATH so that you see bmake and use the right
 157 pkg_* tools.  Send me a note if you have questions about my setup.
 158
 159 * Terminology
 160
 161 This document and the relevant pkgsrc variables call the machine on
 162 which the packages are built the `native' machine, and the machine on
 163 which the packages are to be run the `target' machine.
 164
 165 This is different from the GNU build system, which considers three
 166 different machines for so-called Canadian cross-builds, which pkgsrc
 167 does not support:
 168
 169    The `build' machine is the machine on which the software is built.
 170    The `host' machine is the machine on which the software will run.
 171    The `target' machine is the machine that the software is being
 172      configured to operate on, such as a cross-compiler or cross-linker.
 173
 174 These correspond to the pkgsrc nomenclature as follows:
 175
 176 - Native packages configured for native compilation:
 177
 178         GNU     pkgsrc
 179         ---     ------
 180         build   native
 181         host    native
 182         target  native
 183
 184 - Native packages configured for cross-compilation:
 185
 186         GNU     pkgsrc
 187         ---     ------
 188         build   native
 189         host    native
 190         target  target
 191
 192 - Target packages:
 193
 194         GNU     pkgsrc
 195         ---     ------
 196         build   native
 197         host    target
 198         target  target