Skip to main content
Version: latest

test

clang_build

clang_build.build_type

clang_build.circle

Module for the Circle class.

Circle Objects​

class Circle(list)

List with a circular dependency representation.

Utility class to print circular dependencies. Given a list ["A", "B", "A"], this list will print as:

A -> B -> A

indicating the circular dependency.

__repr__​

def __repr__() -> str

Return a representation of this circle.

Returns​

str An arrow connected string of the circular dependency

__str__​

def __str__() -> str

Return a string representation of this circle.

Returns​

str An arrow connected string of the circular dependency

clang_build.cli

clang-build: TODO: module docstring...

clang_build.conf

clang_build.directories

Directories Objects​

class Directories()

__init__​

def __init__(files, dependencies, public_dependencies)

The root and build directories are taken from target_description, include directories from files and dependencies.

Include directories are made unique.

clang_build.environment

This module contains the Environment class.

clang_build.errors

Module containing custom errors that are raised by clang-build if something goes wrong.

CompileError Objects​

class CompileError(RuntimeError)

Error that is raised if compilation was not successful.

__init__​

def __init__(message, error_dict=None)

Arguments:

  • message: Message of the error
  • error_dict: A dict containing all errors that occurred during compilation

LinkError Objects​

class LinkError(RuntimeError)

Error that is raised if linking was not successful.

__init__​

def __init__(message, error_dict=None)

Arguments:

  • message: Message of the error
  • error_dict: A dict containing all errors that occurred during compilation

BundleError Objects​

class BundleError(RuntimeError)

Error that is raised if creating a bundle was not successful.

__init__​

def __init__(message, error_dict=None)

Arguments:

  • message: Message of the error
  • error_dict: A dict containing all errors that occurred during compilation

RedistributableError Objects​

class RedistributableError(RuntimeError)

Error that is raised if creating a redistributable was not successful.

__init__​

def __init__(message, error_dict=None)

Arguments:

  • message: Message of the error
  • error_dict: A dict containing all errors that occurred during compilation

clang_build.flags

clang_build.git_tools

download_sources​

def download_sources(url, directory, logger, version=None, clone_recursively=True)

Download sources using git.

clang_build.io_tools

clang_build.logging_tools

clang_build.progress_bar

clang_build.project

A class that contains potentially multiple targets and other projects.

Project Objects​

class Project(_NamedLogger,  _TreeEntry)

The Project class is all about organising targets and managing folder structures.

Every start of clang-build, a Project is created that scans a given folder for what could potentially be a large multi-subproject structure. The project will find and configure all targets as specified by the parameters given. Once it is created, the structure that was discovered can be explored and targets can be built.

build_directory​

@property
def build_directory()

Return the output directory for build objects for this project.

Apart from a folder where the project files are stored, a project also has a separate folder where build files (like compiled object files or executables, etc.) are stored.

config​

@property
def config()

Return the config dict of this project.

Non-trivial projects will normally define project details in a toml file. This dict is a :any:dict version of this file.

directory​

@property
def directory()

Return the directory of this project.

Every project is located in a directory that has to be specified. The directory is the one that either contains a toml file or for trivial projects just the default folder structure that can be searched by clang-build.

environment​

@property
def environment()

Return the set of global settings.

identifier​

@property
def identifier() -> str

Returns the unique identifier of this project.

The unique identifier for a project can be:

  • "project" if this is a basic project and no name was given
  • A simple string if a name was given to this project
  • A string with one or more "." if this is a subproject

name​

@property
def name() -> str

Return the name of this project.

Every project can be given a name. A name is a string that does not contain "."s. For basic project no name has to be provided.

parent​

@property
def parent()

Return the parent of this project.

Projects are organised in a tree like structure. This project will return the parent project except for the case where this project is the top level project.

project_tree​

@property
def project_tree()

Return a :any:networkx tree representation of all selected targets.

Targets can have dependencies on each other. This can be represented in a tree structure. Therefore, the targets that were selected during the initialization of the Project are available as a DiGraph. This graph is the global project tree. If you are only interested in subgraphs you have to use the :any:networkx functionality.

subprojects​

@property
def subprojects()

Return a list of subprojects.

All direct children of this project (subprojects only, no targets) are returned as a list.

target_list​

@property
def target_list()

Return all targets that are defined in this project.

This list includes only those targets that were defined in this project and not those defined in subprojects.

__init__​

def __init__(name, config, directory, environment, **kwargs)

Initialise a project.

The procedure for initialisation is:

. Setting some instance attributes . Initialising sub-projects and filling the dependency tree recursively . Determining the targets to configure . Configuring the targets

Parameters​

directory : str or :any:pathlib.Path The directory to search for a toml file or source files environment : any:clang_build.environment.Environment An any:clang_build.environment.Environment instance defining some global settings for this run of clang-build. kwargs Used for internal purposes only.

from_directory​

@classmethod
def from_directory(cls, directory, environment, **kwargs)

Generate a project from a directory.

This method covers the following cases in order:

  1. initialization from a "clang-build.py", if present
  2. initialization from a "clang-build.toml", if present
  3. defaults without any configuration

from_config​

@classmethod
def from_config(cls, config: dict, directory, environment, **kwargs)

Generate a project from a config dictionary.

optional kwarg targets: Any of the targets may be a Target or TargetDescription

add_targets​

def add_targets(target_list: list)

Add a list of targets to this project.

This method does the following:

  • check the validity of targets in the given list
  • add to the project's target_list
  • amend the dependency tree:
    • Add nodes and edges for targets in self
    • Add edges for dependencies in targets defined in project
  • optionally create a new dotfile
  • check for circular dependencies in the project

This method integrates this project into the global project tree.

This helper function is part of the initialisation of a project. It adds this project, all targets and their dependencies to the global project tree. If there are illegal dependencies, this function will raise an exception.

build​

def build(build_all: bool = False, target_list: _Optional[list] = None, number_of_threads: _Optional[int] = None)

Build targets of this project.

By default, this function builds all targets in this project as well as all their dependencies. This function will configure all targets that haven't been configured in a previous call.

Parameters​

build_all : bool If set to true, will not only build all targets in this project and their dependencies, but also all targets of all sub-projects. target_list : list If given, will build all targets in this project that are in the given list, as well as all their dependencies. number_of_threads : int If given will compile targets with the given number of threads. Otherwise it will use the default number of CPU cores visible to Python.

get_sources​

def get_sources()

External sources, if present, will be downloaded to build_directory/external_sources.

clang_build.single_source

clang_build.target

Target describes a single build or dependency target with all needed paths and a list of buildables that comprise it's compile and link steps.

Target Objects​

class Target(_TreeEntry,  _NamedLogger)

Base class for all kinds of target, whose sources have been gathered.

Target instances are used in the build method of a project.

name​

@property
def name()

Return the name of this target.

identifier​

@property
def identifier()

Return the unique identifier of this target.

Targets are identified by their parent projects and their name as "[project.subproject.target]".

dependencies​

@property
def dependencies()

Return a list of any:clang_build.target.Target, which this target depends on.

public_dependencies​

@property
def public_dependencies()

Return a list of any:clang_build.target.Target, which this target depends on.

root_directory​

@property
def root_directory()

Folders "include", "src", etc. are searched relative to this folder.

build_directory​

@property
def build_directory()

Return the directory which serves as the root build folder for this target.

headers​

@property
def headers()

Headers found for this project.

directories​

@property
def directories()

Return the any:clang_build.directories.Directories in use by this target.

__init__​

def __init__(target_description, files, dependencies=None, public_dependencies=None)

Initialise a target.

The procedure for initialisation is:

. Setting some instance attributes . Initialising sub-projects and filling the dependency tree recursively . Determining the targets to configure . Configuring the targets

Parameters​

target_description : :any:clang_build.target.TargetDescription All the information on how to gather sources and build the target. environment : any:clang_build.environment.Environment An any:clang_build.environment.Environment instance defining some global settings for this run of clang-build. dependencies Optional. A list of any:clang_build.target.Target which this target depends on. public_dependencies Optional. A list of any:clang_build.target.Target which this target depends on and which should also be available to dependent targets.

compile​

@abstractmethod
def compile(process_pool, progress_disabled)

Compile the target, if applicable.

This produces an OS-dependent output in the build/bin folder.

@abstractmethod
def link()

Link the target, if applicable.

This produces an OS-dependent output in the corresponding build folder:

  • "bin" for executables and shared objects
  • "lib" for static libraries

bundle​

def bundle()

For executable and shared library targets, bundle shared library dependencies into the binary output folder and amend the rpath if necessary.

They can therefore be used without amending the system PATH or similar.

redistributable​

def redistributable()

Create a redistributable bundle, suitable for installation.

The redistributable bundle contains

  • an "include" folder with the public headers (preserving folder structure). Note that this includes the headers of public dependencies.
  • "bin" and "lib" folders containing compiled output of the target and its dependencies.

build_flags​

@property
def build_flags()

Return the any:clang_build.flags.BuildFlags of this target.

HeaderOnly Objects​

class HeaderOnly(Target)

HeaderOnly targets are the default target type when no source files are found.

Header-only targets cannot have private compile flags, link flags or dependencies. They are automatically promoted to public instead.

TODO: need to check whether "public" makes sense for header-only, when we have implemented "private" dependencies

__init__​

def __init__(target_description, files, dependencies=None, public_dependencies=None)

Initialise a header-only target.

Header-only targets' private flags and include-directories are public.

Compilable Objects​

class Compilable(Target)

A compilable target will generate object files.

compile​

def compile(process_pool, progress_disabled)

From the list of source files, compile those which changed or whose dependencies (included headers, ...) changed.

Executable Objects​

class Executable(Compilable)

Executable targets are the default target type when source files are found.

An executable cannot be the dependency of another target.

__init__​

def __init__(target_description, files, dependencies=None, public_dependencies=None)

Initialise an executable target.

SharedLibrary Objects​

class SharedLibrary(Compilable)

__init__​

def __init__(target_description, files, dependencies=None, public_dependencies=None)

Initialise a shared library target.

StaticLibrary Objects​

class StaticLibrary(Compilable)

__init__​

def __init__(target_description, files, dependencies=None, public_dependencies=None)

Initialise a static library target.

def link()

Although not really a "link" procedure, but really only an archiving procedure for simplicity's sake, this is also called link

TargetDescription Objects​

class TargetDescription(_TreeEntry,  _NamedLogger)

A hollow Target used for dependency checking.

Before Projects actually configure targets, they first make sure that all dependencies etc are correctly defined. For this initial step, these TargetDescriptions are used. This is also necessary, because some of the target properties like the build folder, depend on the entire project structure and thus the two step procedure is necessary.

TODO: Change Attributes to properties :)

__init__​

def __init__(name: str, config: dict, parent_project)

Generate a TargetDescription.

Parameters​

name: str The name of this target as it will also later be named config : dict The config for this target (e.g. read from a toml) identifier : str Unique str representation of this target parent_project : clang_build.project.Project The project to which this target belongs

identifier​

@property
def identifier()

Return the unique identifier of this target.

Targets are identified by their parent projects and their name as "[project_name.sub_project_name.target_name]".

The default target name is "target".

root_directory​

@property
def root_directory()

Return the root source directory.

By default, the "include" and "src" directories are searched relative to this folder.

The folder can be set by adding a "directory" in the config. If this target has external sources, it is relative to the "external_sources" directory, else it is relative to the parent project's directory.

build_directory​

@property
def build_directory()

Return the directory that serves as root build folder for the target.

get_sources​

def get_sources()

Download external sources, if present, to "build_directory/external_sources".

clang_build.toolchain

Module containing tool chaines used for compiling and linking.

Toolchain Objects​

class Toolchain()

generate_dependency_file​

@abstractmethod
def generate_dependency_file(source_file, dependency_file, flags, include_directories, is_c_target)

Generate a dependency file for a given source file.

If the dependency file is placed into a non-existing folder, this folder is generated before compilation.

Parameters​

source_file : pathlib.Path The source file to compile

dependency_file : pathlib.Path The dependency file to generate

flags : list of str List of flags to pass to the compiler

Returns​

bool True if the dependency file generation was successful, else False str Output of the compiler

compile​

@abstractmethod
def compile(source_file, object_file, include_directories, flags, is_c_target)

Compile a given source file into an object file.

If the object file is placed into a non-existing folder, this folder is generated before compilation.

Parameters​

source_file : pathlib.Path The source file to compile

object_file : pathlib.Path The object file to generate during compilation

flags : list of str List of flags to pass to the compiler

Returns​

bool True if the compilation was successful, else False str Output of the compiler

@abstractmethod
def link(object_files, output_file, flags, library_directories, libraries, is_library, is_c_target)

Link into the given output_file.

The command should contain all object files, library search paths and libraries against which to link. If the output_file is placed in a non-existing folder, the folder and all required parents are generated.

Parameters​

object_files : list of pathlib.Path Object files to link output_file : pathlib.Path The output file to generate flags : list of str Flags to pass to the linker library_directories : list of pathlib.Path Directories to search for libraries during linking libraries : list of pathlib.Path Libraries to link to is_library : bool If true, create a shared library. Else, create an executable.

Returns​

bool True if linking was successful, False otherwise str The output of the linker

archive​

@abstractmethod
def archive(object_files, output_file, flags)

Archive object files into a static library.

Parameters​

object_files : list of pathlib.Path Object files to put in a static library output_file : pathlib.Path The static library to create flags : list of str Flags to pass to the archiver

Returns​

bool True if archiving was successful, False otherwise str The output of the archiver

LLVM Objects​

class LLVM(Toolchain)

The LLVM toolchain: clang and clang++ compilers, etc.

This class abstracts away many features of the compiler and provides mildly generic compile, link and archive functions.

Attributes​

c_compiler : :any:pathlib.Path Path to the clang executable cpp_compiler : :any:pathlib.Path Path to the clang++ executable archiver : :any:pathlib.Path Path to the llvm-ar executable max_cpp_standard : str Compile flag for the latest supported C++ standard of the found compiler

__init__​

def __init__()

Search for clang and detect compiler features.

Raises​

RuntimeError If a compiler or linker tool wasn't found on the system.

dialect_exists​

@_lru_cache(maxsize=1)
def dialect_exists(year)

Check if a given dialect flag is valid.

Parameters​

year : int The last two digits of the dialect. For example 11 for C++11.

Returns​

bool True if the dialect for the given year is supported by clang.

generate_dependency_file​

def generate_dependency_file(source_file, dependency_file, flags, include_directories, is_c_target)

Generate a dependency file for a given source file.

If the dependency file is placed into a non-existing folder, this folder is generated before compilation.

Parameters​

source_file : pathlib.Path The source file to compile

dependency_file : pathlib.Path The dependency file to generate

flags : list of str List of flags to pass to the compiler

Returns​

bool True if the dependency file generation was successful, else False str Output of the compiler

compile​

def compile(source_file, object_file, include_directories, flags, is_c_target)

Compile a given source file into an object file.

If the object file is placed into a non-existing folder, this folder is generated before compilation.

Parameters​

source_file : pathlib.Path The source file to compile

object_file : pathlib.Path The object file to generate during compilation

flags : list of str List of flags to pass to the compiler

Returns​

bool True if the compilation was successful, else False str Output of the compiler

clang_build.tree_entry

Module for the TreeEntry class.

TreeEntry Objects​

class TreeEntry()

Abstract class to make an object insertable into a tree.

Implements means to identify and compare an object based on a member variable called identifier which every subclass has to define.

__eq__​

def __eq__(other) -> bool

Declare two objects identical if identifier is the same.

__hash__​

def __hash__() -> int

Return a hash value.

Hashes the identifier value of this object making every object with the same identifier equal to this one (in terms of hash value).