fab.steps.archive_objects

Object archive creation from a list of object files for use in static linking.

Functions

archive_objects(config[, source, ...])

Create an object archive for every build target, from their object files.

fab.steps.archive_objects.archive_objects(config, source=None, output_fpath=None, output_collection=ArtefactSet.OBJECT_ARCHIVES)

Create an object archive for every build target, from their object files.

An object archive is a set of object (.o) files bundled into a single file, typically with a .a extension.

Expects one or more build targets from its artefact getter, of the form Dict[name, object_files]. By default, it finds the build targets and their object files in the artefact collection named by fab.constants.COMPILED_FILES.

This step has three use cases:

• The object archive is the end goal of the build.

• The object archive is a convenience step before linking a shared object.

• One or more object archives as convenience steps before linking executables.

The benefit of creating an object archive before linking is simply to reduce the size of the linker command, which might otherwise include thousands of .o files, making any error output difficult to read. You don’t have to use this step before linking. The linker step has a default artefact getter which will work with or without this preceding step.

Creating a Static or Shared Library:

When building a library there is expected to be a single build target with a None name. This typically happens when configuring the Analyser step without a root symbol. We can assume the list of object files is the entire project source, compiled.

In this case you must specify an output_fpath.

Creating Executables:

When creating executables, there is expected to be one or more build targets, each with a name. This typically happens when configuring the Analyser step with a root symbol(s). We can assume each list of object files is sufficient to build each <root_symbol> executable.

In this case you cannot specify an output_fpath path because they are automatically created from the target name.

Parameters:

• config (BuildConfig) – The fab.build_config.BuildConfig object where we can read settings such as the project workspace folder or the multiprocessing flag.

• source (Optional[ArtefactsGetter]) – An ArtefactsGetter which give us our lists of objects to archive. The artefacts are expected to be of the form Dict[root_symbol_name, list_of_object_files]. (default: None)

• output_fpath –

  The file path of the archive file to create. This string can include templating, where “$output” is replaced with the output folder.

  • Must be specified when building a library file (no build target name).

  • Must not be specified when building linker input (one or more build target names). (default: None)

• output_collection – The name of the artefact collection to create. Defaults to the name in fab.artefacts.ArtefactSet.OBJECT_ARCHIVES. (default: <ArtefactSet.OBJECT_ARCHIVES: 11>)