Cross-compiling
===============

There are two ways to cross-compile software in Hare for a different target
architecture: the easy way and the hard way.

.. warning::
   If you need to cross-compile programs that link to libc or system libraries
   compiled for foreign architectures, skip ahead to "the hard way".

.. note::
   Hare supports cross compiling for a different target architecture using the
   same operating system as the host. Cross compiling for a different target OS
   than the host OS is not officially supported, but might be possible if you
   bang your head against binutils for long enough.

The easy way
------------

If your operating system provides a cross toolchain for the target (i.e.
binutils) and Hare was packaged for your system according to the standard
:ref:`packaging-guidelines`, then simply pass the ``-a`` flag to ``hare build``
to compile for a new target.

You can use ``hare version -v`` to find the cross toolchains your local
installation of Hare was configured to use. If not already installed, install
the appropriate toolchain from your system package manager for the target you
are interested in.

.. code-block:: shell

   $ hare version -v
   hare 0.24.1
   build tags:
   	+x86_64
   	+linux
   HAREPATH:
   	/usr/src/hare/stdlib
   	/usr/src/hare/third-party
   toolchains:
    aarch64:
   	AS=aarch64-alpine-linux-musl-as
   	CC=aarch64-alpine-linux-musl-cc
   	LD=aarch64-alpine-linux-musl-ld
    riscv64:
   	AS=riscv64-alpine-linux-musl-as
   	CC=riscv64-alpine-linux-musl-cc
   	LD=riscv64-alpine-linux-musl-ld
    x86_64:
   	AS=as
   	CC=cc
   	LD=ld

Given an output similar to this, and assuming aarch64-alpine-linux-as et al is
installed on your system:

.. code-block:: shell

   $ hare build -a aarch64 -o example example.ha
   $ file example
   example: ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV),
   statically linked, with debug_info, not stripped

The hard way
------------

If your operating system does not provide a cross toolchain, or you have some
other reason to provide your own toolchain, you can build and install the
necessary cross toolchain (binutils) yourself. To set the build driver to use
this toolchain, set the ``AS`` and ``LD`` environment variables as necessary
(you can also add ``ASFLAGS`` and ``LDLINKFLAGS`` if needed).

You still need to pass the ``-a`` flag to ``hare build``, which will cause the
host architecture to be removed from the tag set, and the desired architecture
added.

If you need to link to C libraries, you will need to prepare a cross-compiler
and export ``CC`` (and perhaps ``LDFLAGS``) as well. You will need to configure
the cross-compiler to use a sysroot, and will need to install a sysroot at the
appropriate location with a copy of libc and any needed libraries
cross-compiled for your target architecture. Preparing and managing sysroots is
a topic beyond the scope of this documentation.

.. tip::
   If your operating system provides, for example, a tarball of a fresh root
   filesystem for the target architecture, or a tool like debootstrap, that
   might suffice as a sysroot in a pinch, particularly if you can chroot into
   it with `qemu-user`_ to install additional libraries.

.. _qemu-user: https://www.qemu.org/docs/master/user/main.html