Configuration files

Overview

SoCLib’s configuration file is parsed by soclib_cc.config, and is used by other modules:

• soclib_desc uses the list of module “search paths”.
• soclib_builder uses the definition of compilers, libraries and build environments.
• finally The soclib-cc command uses it to set default environment and command-line visual feedback (verbosity, etc.).

Configuration file paths

SoCLib configuration module will set default parameters, then look for the following files, in order:

• utils/conf/soclib.conf in soclib installation directory,
• ~/.soclib/global.conf in user home directory,
• ./soclib.conf in current directory.

All configuration items defined in these files override previously set items. Therefore the soclib.conf file in current directory can override everything else.

Any of these files can be absent, this will be silently ignored.

Configuration file format

SoCLib configuration files are:

• Python-parseable. All python types and indentation rules apply,
• made of assignments to the config variable and its attributes,
• only the config variable is evaluated.

Configuration attributes

Some attributes are reserved for special meanings, all other are considered to be build environment specifiers.

config.verbose

Boolean. Whether to print each performed action of The soclib-cc command, overridden by soclib-cc -v.

config.quiet

Boolean. Whether to print as few as possible from The soclib-cc command, overridden by soclib-cc -q.

config.debug

Boolean. Whether to print debug messages for all actions performed by The soclib-cc command, overridden by soclib-cc -d.

config.progress_bar

Boolean. Whether to print The soclib-cc command progress as a progress-bar, overridden by soclib-cc -P.

config.max_name_length

Integer. Filesystem limitation workaround. Sets the maximal file name length for temporary files in Temporary objects reuse.

config.mode

String. Current compilation mode, overridden by soclib-cc -m.

config.workpath

String. work directory expected by EDA tools, overridden by soclib-cc --work.

Build environment specifiers

Configuration files contain 3 types of objects:

• Library, a library definition
  • with a name
  • compilation flags and paths
  • mode-specific flags (debug, prof, release)
• Toolchain, a compiler
  • which commands, tools
  • compilation flags and paths
  • mode-specific flags (debug, prof, release)
• BuildEnv, a build environment, assembling the latter two

As definition of compiler and library variants are often nearly the same, build-environment specifiers can be inherited. Moreover, some build environment specifiers can be templates where usual data is provided with parts to replace. See inheriting configuration for an example, see soclib_cc.config.objects for implementation details.

Configuration directives

There are also some configuration directives.

config.set_default(name)

Sets the build-environment named name as default. This can be overridden with soclib-cc -t.

config.addDescPath(path)

Adds a path to the Metadata paths. Command line can also add such description paths with soclib-cc -I.

config.add_desc_parser(parser)

Adds a python module named parser as another metadata provider.

Built-In configuration

Built-In configuration is made of:

• One default toolchain in config.toolchain, using gcc and g++.
• One default SystemC library declaration in config.systemc expecting the ${SYSTEMC} environment variable to be set. It includes ${SYSTEMC}/include and links ${SYSTEMC}/lib-<os>/libsystemc.<ext>.
• One default build environment config.build_env using the default toolchain and SystemC as sole library.

See utils/lib/python/soclib_cc/config/built-in.conf for its implementation. Dont modify this file directly, use configuration file paths.

Inheriting configuration

Library, Toolchain and BuildEnv all can take a parent = construction keyword argument of the same type, and will inherit all their attributes.

Example creating a new toolchain with ccache and gcc-4.2:

config.my_toolchain = Toolchain(
  parent = config.toolchain,
  tool_CC = ["ccache", "gcc-4.2"],
  tool_CXX = ["ccache", "g++-4.2"],
  )

This does not define a new build environment, therefore we cant use it yet. We now have to define a new build environment:

config.my_build_env = BuildEnv(
  parent = config.build_env,
  toolchain = config.my_toolchain,
  )

Now if we use soclib-cc, we’ll see:

$ soclib-cc -h
...
--type=TYPE, -t TYPE    Use a different configuration: <*build_env,
                        my_build_env>

So we can use our my_build_env with soclib-cc -t my_build_env. Now if we set my_build_env as default with:

config.set_default("my_build_env")

we’ll have:

$ soclib-cc -h
...
--type=TYPE, -t TYPE    Use a different configuration: <*my_build_env,
                        build_env>

and explicitly setting -t wont be necessary any more.

Expected data

Library(name, vendor = "name", ...)

Parameters:

• name (string) –

  Mandatory.

  Name of the library. Expected library name, for SystemC implementations, is "systemc". Other libraries have a free naming.

• vendor (string) –

  Mandatory for SystemC implementations.

  Vendor of implementation of SystemC. Defined values are "OSCI", "systemcass" and "modelsim". This changes quirks used in the compilation process.

• libs (list of strings) – Flags added at linking stage. Always used.
• release_libs (list of strings) – Flags added at linking stage. Used if in release compilation mode.
• debug_libs (list of strings) – Flags added at linking stage. Used if in debug compilation mode.
• prof_libs (list of strings) – Flags added at linking stage. Used if in prof compilation mode.
• cflags (list of strings) – Flags added at compilation stage. Always used.
• release_cflags (list of strings) – Flags added at compilation stage. Used if in release compilation mode.
• debug_cflags (list of strings) – Flags added at compilation stage. Used if in debug compilation mode.
• prof_cflags (list of strings) – Flags added at compilation stage. Used if in prof compilation mode.

Toolchain(...)

Parameters:

• obj_ext (string) – extension of object files. defaults to o. some compilation drivers use other extensions.
• lib_ext (string) – Extension of a library archive. Defaults to a. Some compilation drivers use other extensions.
• always_include (list of strings) – C/C++-specific. List of header files to unconditionally add to compilation commands with -include <file>.
• max_processes (int) –

  Maximal count of concurrent build processes.

• tool_<TOOL_IDENTIFIER> (string or list of strings) – Definition of command used for TOOL_IDENTIFIER. Known tool identifiers are CC, CXX, CC_LINKER, CXX_LINKER, LD, VHDL and VERILOG.
• libs (list of strings) – Flags added at linking stage. Always used.
• release_libs (list of strings) – Flags added at linking stage. Used if in release compilation mode.
• debug_libs (list of strings) – Flags added at linking stage. Used if in debug compilation mode.
• prof_libs (list of strings) – Flags added at linking stage. Used if in prof compilation mode.
• cflags (list of strings) – Flags added at compilation stage. Always used.
• release_cflags (list of strings) – Flags added at compilation stage. Used if in release compilation mode.
• debug_cflags (list of strings) – Flags added at compilation stage. Used if in debug compilation mode.
• prof_cflags (list of strings) – Flags added at compilation stage. Used if in prof compilation mode.

BuildEnv(libraries =[], toolchain = obj, ...)

Parameters:

• libraries (list of Library objects.) – Libraries to use with this build environment
• toolchain (Toolchain) – Toolchain to use with this build environment
• repos (string) –

  Writeable path in filesystem, used as temporary object spool directory.

• cache_file (string) – Metadata cache file path, defaults to a file under repos.
• sd_ignore_regexp (string) – Regexp of filenames to ignore while indexing metadata files. This can be used to ensure VCS files are ignored.