aim-build 0.1.27

A powerful and easy to use build tool for C++.

Aim

A command line tool for building C++ projects.

Introduction

Aim is an attempt to make building C++ projects from source as simple as possible while encouraging a modular approach to software development.

Aim only requires a target.toml file which is used to specify the builds of your project. Each build specifies a component of your project, like a static library, dynamic library, or an executable.

Getting Started

Prerequisites

Aim requires the following dependencies:

• python - version 3.7 or above.
• ninja
• poetry - for development only

Installation

Aim is a python project and is installed using pip.

pip install --user aim-build

Using

There are 3 main commands:

• init - initialises a directory with an empty project structure
• list --target=path/to/target_toml_dir - displays the builds for the target
• build --target=path/to/target_toml_dir <build name> - executes a build

For more information run:

aim <command> --help

The easiest way to get started is to use aim init --demo-files. aim init can be used to generate an empty project structure and the --demo-files flags will copy a small test application into the current directory for demonstration purposes.

You can then list the available builds of a target by specifying:

aim list --target=builds/linux-clang++-debug

And to build:

aim build --target=builds/linux-clang++-debug <build name>

Target files

A target.toml file describes a project and its build components.

Begin by specifying the project root which is the path from the target file to your source files. All relative paths will be relative to this directory.

The compiler frontend informs Aim how to construct compiler arguments. Next specify the compiler, archiver, flags and any defines.

projectRoot = "../.."

compilerFrontend="gcc"
compiler = "clang++"
ar = "ar"

flags = [
    "-std=c++17",
    "-O3",
    "-g",
    "-Wall",
]

# defines = [...]

Next specify your builds. For each build you must specify the name and buildRule. Valid build rules are staticLib, dynamicLib, exe, headerOnly or libraryReference. A build typically looks like:

[[builds]]
    name = "calculatorApp"
    buildRule = "exe"
    requires = ["calculatorDynamic"] # A list of dependancies for this build.
    outputName = "CalculatorApp"     # The output name. Aim will manage any prefixes or suffixes required.
    srcDirs = ["src"]                # A list of source directories.
    includePaths = ["include"]       # A list of include paths.
    # The libraryPaths and libraries fields can be used to specify additional
    # libraries and paths to the build. This allows for linking against third
    # party libraries.
    #libraryPaths = []
    #libraries = []

Aim will automatically generate the correct flags to use dependencies specified in the requires field.

A headerOnly build does not have an outputName or srcDirs. It exists only so the includePaths can be imported into another build using the requires field.

A libraryReference does not have srcDirs. It exists only so the includePaths, libraries and libraryPaths field can be imported into another build using the requires field.

The fields compiler, flags and defines are normally written at the top of the target file before the builds section. By default, all builds will use these fields i.e. they are global, but they can also be overridden by specifying them again in a build. Note that when these fields are specified specifically for a build, they completely replace the global definition; any flags or defines that you specify must be written out in full as they will not share any values with the global definition.

Methodology

Aim treats any build variation as its own unique build target with its own unique target.toml.

A build target is some combination of things that affects the output binary such as:

• operating system (Windows, OSX, Gnu Linux)
• compiler (MSVC, GCC, Clang)
• build type (Release, Debug, Sanitized)
• etc.

Each build target and corresponding target.toml file must have its own directory ideally named using a unique identifier that comprises the 'parts' that make up the build. For example, the target file in the directory linux-clang++-release indicates that the toml file describes a project that is a release build, uses the clang++ compiler and is for the linux operating system.

Note: each target.toml file must be written out in full for each target that you need to support. There is no way for target files to share information or to depend on another. While this leads to duplication between target files, it makes them very explicit and makes debugging builds much easier.

Developing Aim

Aim is a Python project and uses the poetry dependency manager. See poetry installation for instructions.

Once you have cloned the project, the virtual environment and dependencies can be installed simply by executing:

poetry install

Dev Install

Unfortunately, unlike setuptools, there is no means to do a 'dev install' using poetry. A dev install uses the active source files under development, so the application can be tested without being installed each time.

In order to use Aim on the command line, is it recommended creating an alias. The alias needs to:

• adds Aim to PYTHONPATH to resolve import/module paths
• execute the main Aim script using virtualenv's python

Aim provides a dev-env.bash and dev-env.fish for setting an alias to mimic a 'dev' install. These files must be sourced.

Known Limitations

• Windows support is still in development but is coming soon.