Metadata-Version: 1.1
Name: crossroad
Version: 0.5
Summary: Cross-Compilation Environment Toolkit.
Home-page: http://girinstud.io
Author: Jehan
Author-email: jehan at 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 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
        
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
