Metadata-Version: 1.1
Name: crossroad
Version: 0.8.0
Summary: Cross-Compilation Environment Toolkit.
Home-page: http://girinstud.io
Author: Jehan
Author-email: jehan@girinstud.io
License: AGPLv3+
Description: =========
        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 on GNU/Linux
        systems: Fedora, Linux Mint, and Mageia, and expected to work on other
        distributions), 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.
        
        9 target environments are supported currently:
        
        - Windows (x86) 32-bit
        - Windows (x86) 64-bit
        - Android (arm)
        - Android (arm64)
        - Android (x86)
        - Android (x86-64)
        - Android (mips)
        - Android (mips64)
        - Native
        
        And 2 embedded ABI on ARM are barely tested and disabled.
        
        *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 or build with appropriate
        flags.*
        
        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
        at first, but it will tell you what you are missing to go further, and
        you won't be able to enter a cross-compilation environment until this is
        installed.
        
        List targets with::
        
            $ crossroad --list-targets
            crossroad, version 0.8
            Available targets:
            - w64                  Windows 64-bit
            - android-mips         Generic Android/Bionic on MIPS
            - android-arm          Generic Android/Bionic on ARM
            - native               Native platform (x86_64 GNU/Linux)
            - android-mips64       Generic Android/Bionic on MIPS64
            - android-x86          Generic Android/Bionic on x86
            - android-x86-64       Generic Android/Bionic on x86-64
            - android-arm64        Generic Android/Bionic on ARM64
        
            Uninstalled targets:
            w32                  Windows 32-bit
        
            See details about any target with `crossroad --help <TARGET>`.
        
        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 (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-targets
            crossroad, version 0.8
            Available targets:
            - w64                  Windows 64-bit
            - w32                  Windows 32-bit
            [… more output …]
            $ 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 myproject
        
        This will set up a *Windows 64-bit* cross-compilation environment called
        "myproject".
        
        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.
        
        Note that several projects, even for a same target, won't share any data.
        For instance if you have a GIMP and Blender both using libpng, you would
        have to install it in both environments. This is because you usually
        don't want to mix data from various projects and keep a clean slate.
        Nevertheless if you wish a holdall project for a given target, you can
        also do so.
        
        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 Fedora repositories (it used to rely on openSUSE
            cross-platform builds but this was changed in crossroad 0.8) for
            this feature and provides basically a package manager for Windows
            cross-compiled packages (see the manual for more details on its
            features as you can also search packages, get info, uninstall them
            and so on). Let's say for instance that your project depends on
            glib. You could just run::
        
                $ crossroad install glib2
        
            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**.
            Of course, a failed `make check` of Windows binaries in a GNU/Linux
            environment does not mean necessarily your build is a failure, because
            running win32 bin through `wine` will never be as ideal as running through
            an actual Windows OS (as you surely know).
        
        (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.
        
            a) Make a zip of your whole cross-compiled tree with the following::
        
                    $ crossroad --compress=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.*
        
            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 --symlink 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, GIMP and many more.*
        
        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: Meson
        ~~~~~~~~~~~~~~
        
        Meson uses toolchain files as well. Here again, Crossroad prepared them
        for you.
        Simply replace the step (3) of the autotools example with this command::
        
            $ crossroad meson /path/to/source/ /path/to/build/
        
        Now you can simply build and install::
        
            $ ninja
            $ ninja install
        
        This has also been used with success on many programs, since Meson-using
        programs are increasing rapidly these days.
        
        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, assuming your scons scripts use `--prefix` option, running
        scons through crossroad could be done this way:
        
            $ crossroad scons install --prefix=$CROSSROAD_PREFIX
        
        In any cases, scons is really not a recommended build system if you wish to have
        an easy cross-buildable project. If you don't manage to cross-compile your
        project, rather than tweaking your SConscript files indefinitely, consider
        taking the time to port your project to autotools or cmake.
        
        Note that crossroad has been used on some scons-using projects back in
        the days, but I have not seen any more of them for a few years now. I am
        not sure of the current level of support.
        
        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`, `ccmake` and `meson` subcommands are simple
        wrappers around respectively any `./configure` script, `cmake`, `ccmake`
        and `meson` 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").
        
        Environments
        ============
        Windows
        ~~~~~~~
        
        This tool has been originally created to cross-build GIMP (and its
        dependencies when needed) for Windows and this is still one my main
        usage. It has proven to be able to generically cross-build many dozens
        of projects and I am confident it should work pretty well for any
        Autotools, CMake or Meson project out there, unless they really use
        non-standard tricks (in which case, the most relevant course of action
        is often to send a patch to the upstream project).
        If you encounter standard cases which crossroad does not properly
        support, please send me a patch!
        
        Native
        ~~~~~~
        
        This target environment may look very weird since this tool was
        originally made for cross-compilation, but it has become my main usage
        of crossroad these days (I mean a daily usage for all my development).
        
        Developers have all sort of tricks to build, install and test their
        software in non-standard prefix by tweaking environment variables.
        
        Sometimes you may have a unique place (set up in your `.bashrc` for
        instance), but then when you want to clean a single program without
        touching the rest, it can be a problem. Worse, you can't install several
        versions of the same program. And last, but not least, installing low
        level libraries (glib, GTK, etc.) may end up breaking your user system
        as these variables are picked up by your desktop.
        
        Other times, you make unique scripts to have these changes only in the
        current shell. This is very inconvenient and bug-prone as it requires
        one script per project with specific paths which you have to manage. You
        are bound to mess up at some point.
        
        With the native environment, `crossroad` just take care of everything
        for me, sets up my environment variable, and manage my prefix. Say I
        want to build GIMP. I'd run::
        
            $ crossroad native gimp
        
        Now I am in a specifically generated environment for my GIMP build.
        Let's build GIMP::
        
            $ cd $build/gimp
            $ crossroad meson $src/gimp && ninja install
        
        I can now run GIMP from command line: `gimp-2.99`
        
        Note that this binary is only visible when inside the crossroad
        environment. I could also install any dependency in the same
        environment, say an experimental version of GTK+ for instance, without
        fearing it to be picked up by my desktop, and potentially breaking it.
        As soon as I get out of this shell, GIMP or any custom code is not
        visible by the rest of the system.
        
        Say now I want to create another GIMP build in another shell (with some
        patchs applied), I could create a new crossroad project::
        
            $ crossroad native gimp-tests
        
        Both environment live next to each other without interfering and I can
        now call one or another without messing up with files.
        
        Now if I want to get rid of my `gimp-tests` project, I could just run::
        
            $ crossroad --reset native gimp-tests
        
        And the whole project and all its files would be just gone. Cleaning as
        simple as ever.
        
        Android
        ~~~~~~~
        
        A few years back, I started to use crossroad to cross-compile C
        libraries for Android. It did pretty well and I could successfully run
        some test programs in Java using these C libraries. I have not worked
        much on this platform since then. It may just be broken now, I don't
        know.
        
        Still I leave this here in case it is helpful to someone. If you need
        Android support and some of the support in `crossroad` is not really
        optimal, I will gladly accept patches.
        
        ARM
        ~~~
        
        I had an early attempt to add arm-linux-gnu and arm-none-eabi (bare
        metal if not mistaken) but in the end didn't include them because I
        never actually tested these for real projects (never had the occasion!)
        so this support is deactivated in released `crossroad`.
        
        If anyone wants to play with it, please feel free to try the development
        version (edit the `deactivated_platforms` variable in `setup.py` before
        installing).
        
        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 in $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.
        
        *Note: I have not used these 2 environment variables for years now and
        wonder if they are really useful. They may become deprecated in a close
        future.*
        
        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 experience) in concerts.
        
        .. _AGPL version 3: http://www.gnu.org/licenses/agpl.html
        .. _author: https://film.zemarmot.net
        .. _support: https://film.zemarmot.net/en/donate
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.3
Classifier: Topic :: Software Development :: Build Tools
