Matrix/ProjectConfiguration

From SandboxWiki

In Matrix, "config" refers to project configuration. It's mostly about describing the project at a high level. It shouldn't be confused with Makefiles. Every Matrix invocation starts by parsing a config file called main. Some configuration parameters can be overridden or extended via command-line parameters (see the output of "matrix --help").

Contents 1 Finding files 2 File format 3 API functions 3.1 Board parameters

Finding files

Config files are located by going through a list of directories and collecting all files which match the given name or glob pattern (see the glob(7) man page). All of the collected files are parsed. The list of config directories initially contains the current working directory: the main config file is (nearly) always read from the current working directory. New config directories can be added in config files or on the command-line.

File format

The config files are actually snippets of Python code. The user can choose to do anything which is supported by the Python version being used, but most of the configuration tasks can be done using a few functions provided by Matrix; they can be considered the supported API. Manipulating the internal configuration variables directly is also possible, but that might lead to incompatibilities during upgrades. It's also probably a good idea to agree on a minimum Python version when writing advanced config files (Matrix itself is compatible with Python 2.3, which is a good suggestion).

The local variables introduced by config files are local to the file. The syntax is simply name = value. The names of local variables should begin with a lowercase letter (or underscore) to separate them from the Matrix API functions which start with an uppercase letter. If values need to be passed to other scripts, it's possible via environment variables (by using Python's standard "os" module) or by adding variables to Matrix's configuration state (it's a good idea to use some project-specific prefix to avoid namespace pollution).

Nearly all API function parameters are strings. Strings are formed by quoting text with single (') or double (") quotes. Strings can be concatenated with the + operator.

Python function parameters can be specified positionally (func(1, 2, 3)) and/or by name (func(a=1, b=2, c=3)). It's good practise to use the latter form in Matrix config files because some functions can be called in several ways.

API functions

ConfigDir(path)

Append a directory to the config file search list.

ConfigDir(path, url, branch)

Append a directory to the config file search list. If it doesn't exist, try to clone url using Git and check out branch (defaults to "master"). If path is omitted, it will be deducted from url.

ConfigDir(path, url, branch, optional=True)

Same as above, but does nothing unless path is specified on the command line.

Parse(name)

Evaluate the matching config file(s) immediately. (See the "Finding files" section.)

Parse(name, required=False)

Evaluate the matching config file(s) immediately. Don't fail even if no files are found. (See the "Finding files" section.)

Board(name, arch, gcc_march)

Declare a target machine type. (See the "Board parameters" section below.)

UseBoard(name)

Use the given target machine declaration when building packages.

Root(url, branch)

Append a (remote) Git repository location ("root") to the component search list. The url shouldn't be a complete Git repository location, but a prefix under which multiple repositories can be found under "meta" and "source" subdirectories. All components found under the given location will use branch (which defaults to "master") by default.

Component(name)

Declare a source package ("component").

Component(name, branch)

Declare a source package ("component"). Override the default branch (which is defined along with the root location).

ProvideComponent(name)

Declare a component as "environment-provided"; its sources are not needed and other components' dependencies to it are automatically satisfied. It doesn't matter if the component was previously declared using Component().

SetFlag(name)

Set a flag which can be used to customize component build process. A flag can be set multiple times without a problem. The flag is exported in the build environment as a variable the value of which is "1".

ClearFlag(name)

Unset a flag. It won't be exported to the build environment at all.

CacheDir(path)

Use a custom component build cache directory. The default is "build-cache".

GetVariables()

Returns an object containing the internal configuration variables as attributes. New variables can be introduced by simply assigning to a previously nonexistent attribute.

Scratchbox 2 integration:

SB2Target(name)

Enable Scratchbox. This target will be (possibly created and) used. Exported to the build environment in the MATRIX_SB2_TARGET variable.

SB2Compiler(path)

Path to the cross-compiler command to be used. Exported to the build environment in the MATRIX_SB2_COMPILER variable.

Example "/usr/local/arm-2008q1/bin/arm-none-linux-gnueabi-gcc"

SB2InitOptions((option, ...))

Additional options passed to Scratchbox when creating the target.

Example: ("-c", "/usr/local/bin/sbrsh", "-r", "127.0.0.1", "-l", "10.0.2.2")

Note that the actual Scratcbox target creation is not done automatically by Matrix; you can use a special component for that. After the target has been created, Matrix can run all build commands in it.

Board parameters

name

Symbolic name for referring to the board declaration later on.

arch

The high-level CPU architecture family name (used by architecture-specific components).

gcc_march

Passed verbatim to the compiler as a parameter to the -march= option.

It's implemented via the SBOX_EXTRA_CROSS_COMPILER_ARGS mechanism - it can be debugged by setting SBOX_VERBOSE_WRAPPER=1 in the environment.

Options:

gcc_mcpu

Target a specific CPU type. Example: "arm1136j-s"

gcc_mfpu

Select the kind of FPU to generate code for. Example: "vfp""

gcc_options

List of additional options to pass to the compiler. Example: ("-O2", "-msoft-float=softfp")

gnu_host

Tell configure scripts etc. what kind of system we're targeting. Example: "armv5t-unknown-linux-gnueabi"

Options used for root image creation:

flash_erase_size

Defaults to 65536.

flash_pad_size

flash_compression

ubifs_leb_size

ubifs_max_leb_count

ubifs_min_io_size

ubinize_config_vol_size

---

Matrix documentation index