=========
crossroad
=========

**Crossroad** is a command line tool to easily set up your shell
environment for cross-compilation, on a GNU/Linux
distribution.

Be aware that this is essentially a developer tool. Its target audience
are developers working on UNIX systems (tested only under a GNU/Linux
system though), and wishing to cross-compile projects from the same
platform. It is not for end-users, and is useless in *running*
software, only **building** them.

Only two target environments are supported currently:

- Windows (x86) 32-bit;
- Windows (x86) 64-bit.

*Note: no differences are made between Windows platforms other than
32/64-bit (in particular no software API versioning).
This is up to you to make your code portable.*

This is Free Software, under the license `AGPL version 3`_.

If you liked this software, you are free to contact the author_,
or even support_ him.

Also you are more than welcome to propose patches: bugfixes, or new
features, like support of more target environments, other shells than
`bash` and `zsh`, etc.
See the `Contributing`_ section below.

Installation
============

`Crossroad` is a typical python-style project, relying on Python 3.3 or
above. You will also need either `7z` or `rpm2cpio` installed.

To install from `pypi`, just run::

    $ pip3 install crossroad

Or download from the archive::

    $ ./setup.py install

Setting-UP
==========

`Crossroad` does not need any particular cross-compilation tool to run,
but it will tell you what you are missing, and you won't be able to enter
a cross-compilation environment until this is installed.

List targets with::

    $ crossroad --list-all
    crossroad, version 0.4.4
    Available targets:
    w64                  Windows 64-bit

    Uninstalled targets:
    w32                  Windows 32-bit

In the above example, I can compile for Windows 64-bit, not 32-bit.

To get details about a target's missing dependencies, for instance
Windows 32-bit::

    $ crossroad -h w32
    w32: Setups a cross-compilation environment for Microsoft Windows operating systems (32-bit).

    Not available. Some requirements are missing:
    - i686-w64-mingw32-gcc [package "gcc-mingw-w64-i686"] (missing)
    - i686-w64-mingw32-ld [package "binutils-mingw-w64-i686"]

It will return a list of required binaries that crossroad cannot find.
If you actually have them, the most likely reason is that you should
update your `$PATH` with the right location. In the above example,
`crossroad` could find your minGW linker, but not the compiler. It also
informs you of a possible package name (based on a Linux Mint
distribution. Your distribution may use a different name, but it would
still give a useful hint for searching in your package manager).

Install the missing requirements and run crossroad again::

    $ crossroad --list-all
    crossroad, version 0.4.4
    Available targets:
    w32                  Windows 32-bit
    w64                  Windows 64-bit
    $ crossroad -h w32
    w32: Setups a cross-compilation environment for Microsoft Windows operating systems (32-bit).

    Installed language list:
    - C
    Uninstalled language list:
    - Ada                 Common package name providing the feature: gnat-mingw-w64-i686
    - C++                 Common package name providing the feature: g++-mingw-w64-i686
    - OCaml               Common package name providing the feature: mingw-ocaml
    - Objective C         Common package name providing the feature: gobjc++-mingw-w64-i686
    - fortran             Common package name providing the feature: gfortran-mingw-w64-i686

You will notice that now `w32` is available in your list of target, but
also the specific help is more complete and will also tell you a list of
possible languages that MinGW can handle if you installed additional
packages.

*Note: crossroad has actually been tested only with C and C++ projects.
But I welcome any usage report with other languages.*

Usage
=====

The full usage is available as a manual. Once installed, it is available
with `man crossroad`. The below preview presents the main usage examples.

From a command line, run::

    $ crossroad w64

This will set up a *Windows 64-bit* cross-compilation environment.

Your prompt will also be slightly modified (only adding information.
Whatever custom prompt hack you may have — for instance displaying
information on a code repository — will be untouched) to show you are
in your working cross-compilation environment.

*Note: only `bash` and`zsh` are supported right now.*

All necessary environment variables for successful builds, like `PATH`,
`LD_LIBRARY_PATH`, etc., are set for you.
Moreover the crossroad command is modified once in a cross-compilation
environment. You can `crossroad -h` or `crossroad help` to see the new
list of commands.

You are now ready to configure and compile any project for your target
platform.

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

    *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.

(4) Here the configure may fail if you miss any **dependency**. You may
    install many dependencies easily through crossroad. Crossroad relies
    on the `Fedora MinGW project`_ 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**::

        $ make
        $ make install

(6) 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.

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

            $ crossroad -c mysoftware.zip w64

       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.*

    b) 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 `myproject/` to the "w64" target.
       Since the directory is shared, it should be visible in Windows as
       a normal directory.

(7) 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, and you can add any options to your build.

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

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` is nothing more than::

    $ cmake . -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

What it means is that you can use these for other compilation system.
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 --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`.*

Configuration
=============

`Crossroad` relies on XDG standards.
Right now it does not need any configuration file, but it will soon probably.
And these will be in $XDG_CONFIG_HOME/crossroad/ (defaults to $HOME/.config/crossroad/).

Cache is saved in $XDG_CACHE_HOME/crossroad/ and data $XDG_DATA_HOME/crossroad/.

The only configuration right now is that in case you use a
self-installed MinGW-w64 prefix of Windows libraries, if they are not in
the same prefix as the MinGW-64 executables you run, you can set
$CROSSROAD_CUSTOM_MINGW_W32_PREFIX and $CROSSROAD_CUSTOM_MINGW_W64_PREFIX
respectively for your 32-bit and 64-bit installation of MinGW-w64.

Help
====

`Crossroad` provides inline help with `crossroad -h` but also by
installing a man page in section 1::

    $ man crossroad


Contributing
============

You can view the git branch on the web at: http://git.tuxfamily.org/crossroad/crossroad
And clone it with::

    $ git clone git://git.tuxfamily.org/gitroot/crossroad/crossroad.git

Then send your `git-format`-ed patches by email to crossroad <at> girinstud.io.

About the name
==============

The name is a hommage to "*cross road blues*" by Robert Johnson, which
spawned dozens, if not hundreds, of other versions by so many artists.
I myself always play this song (or rather a version with modified lyrics
adapted to my life) in concerts.

.. _AGPL version 3: http://www.gnu.org/licenses/agpl.html
.. _author: http://girinstud.io/
.. _support: http://girinstud.io/support-us/
.. _Fedora MinGW project: http://fedoraproject.org/wiki/MinGW
