View on GitHub


The Z cross build environment

Z Cross Build Environment

Python Package Upload Python Package codecov Maintainability CII Best Practices


The Z cross build environment is a tool for managing cross-compile environments. It comes with concurrent building, dependency tracking and other useful features.



ZCBE is available on PyPI:

pip install zcbe


  1. Understanding concepts:
    • A “build” is an environment with multiple projects.
    • A “project” is a single package. They may depend on other projects.
  2. The first step is to create a basic directory structure. ZCBE uses TOML as its configuration language.
    |-- build.toml
    |-- mapping.toml
    |-- zcbe/
       |-- PROJECT.zcbe/
          |-- conf.toml
    |-- ...

    The sources of projects can be anywhere. But generally it’s suggested that you put them somewhere under the build’s root directory.

  3. Then we can populate the configurations.
    • build.toml: This file describes how to prepare environment. For example, the installation prefix and host triplets are set in this file. Go to templates/build.toml for an example.
    • mapping.toml: This file sets the working directory for each projects. This directory can be absolute or relative to build root. An example is at templates/mapping.toml.
    • zcbe/*.zcbe: Each project has a subdirectory here for holding their configuration, scripts and data.
    • zcbe/*.zcbe/conf.toml: This file contains the information about a project. The dependencies are specified here. An example is also available at templates/conf.toml.
    • zcbe/*.zcbe/ This is the build script.
  4. Start building!
    • To build a single project and its dependencies, run zcbe <NAME>.
    • To build everything, pass -a.
    • To silence stdout, pass -s.
    • By default only one process is run at a time. To build concurrently, pass -j <N>.

    See CLI Usage Section for a complete list of options.


For security-related issues, see

Contributions are very welcome on GitHub. Please try to follow PEP-8 coding guidelines and make sure test suites pass before submitting.

For new features and bug fixes, corresponding tests must be added.

The license is Apache-2.0.

Usage References and Specifications

CLI Usage

usage: zcbe [-h] [-w] [-W WARNING] [-B] [-C CHDIR] [-o FILE] [-e FILE]
            [-f FILE] [-p PREFIX] [-t TARGET_TRIPLET] [-m BUILD_NAME]
            [-j JOBS] [-a] [-s] [-n] [-u] [-y] [-H ABOUT]
            [PROJ ...]

The Z Cross Build Environment

positional arguments:
  PROJ                  List of projects to build

optional arguments:
  -h, --help            show this help message and exit
  -w                    Suppress all warnings
  -W WARNING            Modify warning behavior
  -B, --rebuild, --always-make, --always-build
                        Force build requested projects and dependencies
  -C CHDIR, --chdir CHDIR, --directory CHDIR
                        Change directory to
  -o FILE, --stdout-to FILE
                        Redirect stdout to FILE ('{n}' expands to the name of
                        the project)
  -e FILE, --stderr-to FILE
                        Redirect stderr to FILE ('{n}' expands to the name of
                        the project)
  -f FILE, --file FILE, --build-toml FILE
                        Read FILE as build.toml
  -p PREFIX, --prefix PREFIX, --override-prefix PREFIX
                        Override value for prefix
  -t TARGET_TRIPLET, --target-triplet TARGET_TRIPLET, --override-target TARGET_TRIPLET
                        Override value for target triplet
  -m BUILD_NAME, --build-name BUILD_NAME, --override-build-name BUILD_NAME
                        Override value for build name
  -j JOBS, --jobs JOBS  Number of maximum concurrent jobs
  -a, --all             Build all projects in mapping.toml
  -s, --silent          Silence make standard output(short for -o /dev/null)
  -n, --dry-run, --just-print, --recon
                        Don't actually run any commands
  -u, --show-unbuilt    List unbuilt projects and exit
  -y, --yes             Assume yes for all questions
  -H ABOUT, --about ABOUT
                        Help on a topic("topics" for a list of topics)

Environment Specification

In the build script, there are three environment variables set by ZCBE:

build.toml Specification


mapping.toml Specification


conf.toml Specification