Cross compiler

[shym]

This PR makes it possible to build OCaml cross compilers without the various patches that all cross-compiler projects apply at the moment. It builds upon many previous PRs that have made this a lot simpler now than a couple of years ago.

Context

Recall that building a compiler involves 3 system types described by triplets:

• build: the machine on which the compiler is built, usually automatically detected by autoconf's configure
• host: the machine on which the compiler will run,
• target: the machine on which the code generated by the compiler will run.

So when build != host, we are cross-compiling. When host != target, we are building a cross compiler. This PR tackles issues in that latter case, cross compilers.

Currently, the only supported configurations are when build ~ host = target, where by ~ I mean that the code generated for host runs on build even when they differ (such as when build is Cygwin and host is Windows (MSVC or MinGW)).

Even though this is not officially supported yet, many projects use OCaml cross compilers. All those projects generate a cross compiler by assuming a non-cross OCaml compiler is available in PATH (where “non-cross” means generating code that will run on build = host).

Summary

This PR proposes the following main improvements for building cross compilers.

• It disambiguates host and target in configure, where currently most tests about host in fact mean to test target.
• It fixes the implementation of the %ostype_* primitives that were reporting the OS type of the host instead of the target.
• It teaches sak about cross compilation between Unix and Windows and autodetect the C toolchain to build it if needed.
• When building a cross compiler, it adds new make targets: crossopt to drive the build of the cross compiler and installcross to drive its installation.

Note that all the changes of this PR are transparent in the non-cross-compiler cases.

This PR comes with a CI workflow to help review the PR but not intended to be merged (at least, not as is). This CI workflow runs on x86 Linux and:

• builds a non-cross compiler
• builds a cross compiler to Windows MinGW and:
  • compiles a tiny program that displays Sys.os_type, Sys.unix, etc.
  • runs that program on Windows
• builds a cross compiler to arm Linux and:
  • compiles a tiny program that displays Sys.os_type, Sys.unix, etc.
  • runs that program using qemu-user
• tests the sak cross compiling behavior (Unix to Windows and vice versa).

How to test it

To build a cross compiler you first need to have a non-cross compiler of the same version installed in your $PATH. Note that they need to be of the same version since the cross compilers will contain the runtime of the non-cross compiler because the C toolchain that will be detected during the configure for the OCaml cross compiler will be the C cross compiler to target.

Build the non-cross compiler

It could be by creating an opam trunk switch or by building manually as usual. For instance,

$ ./configure --prefix=$PWD/non-cross # and any other option you want...
$ make -j
$ make install
$ export PATH="$PWD/non-cross:$PATH"

It may be useful to keep a note of the flags used to link with zstd, if any:

$ grep ZSTD_LIBS Makefile.config

Build the cross compiler

After cleaning the working directory, call configure with the target triplet, possibly setting where the library will be installed on the target. So for instance, with the GCC MinGW cross compiler installed, it could be:

$ ./configure --prefix=$PWD/cross --target=x86_64-w64-mingw32 --with-target-libdir='C:\somedir' ...
$ make crossopt -j
$ make installcross

Notes:

• The cross compiler to Windows needs flexdll to link the binaries. A simple way to get it is to use the flexdll submodule (git submodule update --init if needed) and let the crossopt target bootstrap flexdll.

• If pkg-config --libs libzstd doesn’t return the flags used to link the non-cross runtime, you can specify them with:

  $ make crossopt -j HOST_ZSTD_FLAGS="..."
  

Use the cross compiler

If you have built a cross compiler to a Unix target, you can simply run as usual:

cross/bin/ocamlopt.opt -o test test.ml

If you have built a cross compiler to Windows on a Unix host, you must first make sure that ocamlopt can find the flexlink executable in $PATH when it needs to link. Boostrapping flexdll builds a flexlink.exe (note the .exe), so you can:

ln -s flexlink.exe cross/bin/flexlink
(export PATH="$PWD/cross/bin:$PATH"; ocamlopt.opt.exe -o test.exe test.ml)

or any other possibility to make sure flexlink can be invoked.

Overview of the commits

This PR is meant to be reviewed commit per commit.

• Fix some small issues
  • 378e958 Add the missing $(EXE) for stripdebug invocations
  • 665c3e0 Include the runtime directory only for ocamltest
• Fix configure to handle properly the cross-compiler cases
  • 58584d9 Use target instead of host to detect the C toolchain
  • 15d5e8a Use target instead of host when relevant in configuration
  • c84d2a8 Detect and use {CC,...}_FOR_BUILD to build sak
  • 561a67a Check that the OCaml versions are compatible for a cross compiler
  • e6fb79b Add a configurable library directory on target
  • 4876024 Detect flexlink only on relevant targets
• Add a Makefile.cross with the cross-compiler recipes
  • 2495303 Add a Makefile.cross for recipes to build a cross compiler
  • ce91988 Enable bootstrapping flexdll in the cross-compiler setting
• Fix sak in cross-compiler cases
  • 58baaa2 Add cross-compilation cases to sak
• Fix the ostype_* primitives
  • ff09ae4 Add a Config entry for the target OS type
  • 69863c9 Bootstrap
• Misc
  • 8049dd1 Document cross compilers in INSTALL.adoc
  • 1f40f9e Add a changelog entry for cross compilers
  • 613e2c2 DROPME Add a CI workflow to test cross compilers

[shym]

Opened upstream as 13526.