crossroad 0.6

Example: autotools

Let’s imagine you want to compile any software with a typical GNU compilation system, for Windows 64-bit.

1. First enter crossroad:

   $ crossroad w64 myproject

   Normally here your shell prompt will be modified at this point.

2. Enter your source code:

   $ cd /some/path/to/your/source/

   In a typical autotools project, you will have here access to a `configure` script, or with ways to build one, for instance by running an `autogen.sh` first.

3. Configure your build:

   $ crossroad configure

   There is no need to add a –prefix, a –host, or a –build. These are automatically and appropriately set up for you.

   Of course you should add any other option as you would normally do to your `configure` step. For instance if your project had a libjpeg dependency that you want to deactivate:

   $ crossroad configure –without-libjpeg

   See the ./configure –help of a project for listing of its available options.

   Note: VPATH builds are also supported. You can run a configure from another directory this way:

   $ crossroad ../some/other/path/configure --without-libjpeg

4. Here the configure may fail if you miss any dependency. You may install many dependencies easily through crossroad. Crossroad relies on the openSUSE cross-platform builds for this feature and provides basically a package manager for Windows cross-compiled packages (see the manual for more details on its features). Let’s say for instance that your project depends on glib. You could just run:

   $ crossroad install glib-devel

   Do this step as many times as necessary, until the configure step 3. succeeds. Then go to the next step.

5. Build and install in the most common way possible:

   $ make
   $ make install

6. Test:

   $ make check

   This one may seem weird, but actually if you have Wine installed and registered in binfmt_misc to execute win32 binaries, crossroad set up properly the Wine environment so that it can find the executables and DLLs you installed with make install. As a consequence, a make check might just work, even though there is no certaincy, since this is not exactly the same as running on the native win32 platform. For the records, I have been able to run successful make check on projects as complicated as GIMP.

7. All done! Just exit your cross-compilation environment with ctrl-d or exit. To test your binaries on an actual Windows machine, crossroad provides 2 tools.

   1. Make a zip of your whole cross-compiled tree with the following:

      $ crossroad -c mysoftware.zip w64 myproject

      This will create a zip file mysoftware.zip that you can just move over to your test Windows OS. Then uncompress it, and set or update your PATH environment variable with the bin/ directory of this uncompressed prefix.

      Note: only zip format supported for the moment, since it is the most common compression format for Windows.

   2. If you are running Windows in a VM for instance, or are sharing partitions, you can just add a link in a shared directory. Just cd to the shared directory and run:

      $ crossroad -s w64 myproject

      This will create a symlink named crossroad-w64-myproject/ to the “myproject” project for the “w64” target. Since the directory is shared, it should be visible in Windows as a normal directory.

8. Then run your app, and enjoy!

Note: this has been tested with success on many GNU projects, cross-compiled for Windows: cairo, babl, GEGL, glib, GTK+, libpng, pango, freetype2, gdk-pixbuf and GIMP.

Example: CMake

CMake uses toolchain files. Crossroad prepared one for you, so you don’t have to worry about it. Simply replace the step (3) of the autotools example with this command:

$ crossroad cmake .

A common cmake usage is to create a build/ directory and build there. You can do so with crossroad, of course:

$ mkdir build; cd build
$ crossroad cmake ..

Alternatively crossroad allows also to use the curses interface of cmake:

$ crossroad ccmake .

The rest should be the same, with make && make install, and you can add any options to your build the usual way.

This has been tested with success on allegro 5, and Exiv2 libraries, cross-compiled for Windows.

Example: SCons

A very basic support of scons build system has been added to crossroad, though there seems to be no actual standard there for cross-compilation. As a consequence, the support in crossroad is only following some common usage I saw in a few projects, but it may not work in your case.

Another issue is that scons does not even have standard for basic features either like prefix path. So you have to use the environment variable $CROSSROAD_PREFIX and use it were appropriate yourself.

For instance, assumins your scons scripts use –prefix option, running scons through crossroad could be done this way:

$ crossroad scons install –prefix=$CROSSROAD_PREFIX

Example: other

It has not been tested with any other compilation system up to now. So it all depends what they require for a cross-compilation. But since a crossroad environment prepares a bunch of environment variables for you, and helps you download dependencies, no doubt it will already make your life easier.

The configure, cmake and ccmake command are simple wrappers around any ./configure script, and the cmake/ccmake commands, adding some default options (which crossroad prepared) for successful cross-compilation.

For instance crossroad configure is the equivalent of running:

$ ./configure --prefix=$CROSSROAD_PREFIX --host=$CROSSROAD_HOST --build=$CROSSROAD_BUILD

And crossroad cmake /some/path is nothing more than:

$ cmake /some/path -DCMAKE_INSTALL_PREFIX:PATH=$CROSSROAD_PREFIX -DCMAKE_TOOLCHAIN_FILE=$CROSSROAD_CMAKE_TOOLCHAIN_FILE

Here is the list of useful, easy-to-remember and ready-to-use, environment variables, prepared by crossroad:

• $CROSSROAD_PREFIX;

• $CROSSROAD_HOST;

• $CROSSROAD_BUILD;

• $CROSSROAD_CMAKE_TOOLCHAIN_FILE.

• $CROSSROAD_PLATFORM

• $CROSSROAD_PLATFORM_NICENAME

• $CROSSROAD_PROJECT

• $CROSSROAD_WORD_SIZE

Do not modify these environment variables. They have been set-up for your builds to work successfully. If you modify these, you will get into trouble.

What it means though is that you can use these for other compilation systems. You can also use your crossroad prefix, even for systems which do not require any compilation. Let’s say for instance you wish to include a pure python project in your build. No per-platform compilation is needed, but you still want to carry all the files in the same prefix. So just run:

$ ./setup.py install –prefix=$CROSSROAD_PREFIX

and so on.

Note: as you may have guess `$CROSSROAD_PREFIX` encapsulates your new cross-build and all its dependencies. Though in most cases, you should not need to manually go there do anything, you still can (for instance to change software settings, etc.) with `cd $CROSSROAD_PREFIX`.

Special case: Wine

Some software have proved extremely hard to cross-compile, mostly because of weird custom build systems or strange designs. I had this case for Python, which even went as far as forbidding cross-builds for hosts they didn’t approve with specific configure tests. I have been therefore unable to crossbuild it. One solution could be to fix the build system (which I started to do for Python until I discovered bug reports with patches for specifically this, and opened for eons), or to install in Windows, and import the data (but then you lose the flexibility or building all on the same machine).

My other workaround has been to install with Wine. In my Python example, I have indeed been able to run the 32-bit installer (not the 64-bit one). When doing so in a crossroad environment, the data will be automatically installed under $CROSSROAD_PREFIX/wine/. Then you just have to update any necessary environment variable in order for your builds to discover any library/header if necessary (I don’t see how to do so automatically with a Windows tree being so “random”).