2. Entry Point

The top-level wscript is the entry point for the Waf build system. It registers all build variants, configures the toolchains, and dispatches builds to the correct sub-directories.

Top-level Waf build script for the foxBMS project.

This wscript is the entry point for the Waf build system. It defines how to configure and build all foxBMS variants including embedded firmware binaries (app and bootloader for TI ARM CGT), host-based unit tests (GCC), static program analysis (SPA) builds, Doxygen API documentation, and Sphinx-based general documentation.

The script performs three main tasks:

  1. Variant registration:

    Dynamically creates Waf build/clean/list/step commands for each variant defined in VARIANT_CONFIGS.

  2. Configuration:

    Sets up multiple named build environments (one per toolchain/variant combination), each with its own compiler, flags, and tool settings. Environments are derived from a common default to share project-wide settings (APPNAME, VERSION, BMS_CONFIG).

  3. Build dispatch:

    Selects the correct environment and source directory for the active variant and recurses into the appropriate sub-wscript.

2.1. Usage

  • Configure all environments once:

    waf configure

  • Build a specific variant:

    waf build_app_ti_arm_cgt        # embedded firmware
waf build_app_unit_test_gcc     # host unit tests
waf build_docs                  # Sphinx documentation

    The complete list of variants can be found under waf or via the CLI command waf -h/waf --help.

  • Clean a variant:

    waf clean_app_ti_arm_cgt

2.2. Dependencies

  • Waf (bundled)

  • TI ARM CGT (for embedded builds)

  • GCC (for host/unit-test builds)

  • Ruby + CMock/Unity (for unit-test mock generation)

  • Sphinx, Doxygen (for documentation builds)

wscript.build(bld: BuildContext)

Dispatch the build to the correct variant sub-wscript.

Generates VS Code workspace configurations, selects the named environment for the active variant from VARIANT_CONFIGS, runs a version consistency check, appends the common remarks command file, and recurses into the variant’s directory (src/, tests/, or docs/).

wscript.configure(ctx: ConfigurationContext)

Configure all build environments for the foxBMS project.

Creates a default environment with project-wide settings (APPNAME, VERSION, BMS_CONFIG) and derives specialized environments for each toolchain:

  • gcc:

    Host GCC compiler; validates object, static library, and program compilation.

  • docs:

    Sphinx documentation generation.

  • doxygen:

    Doxygen API documentation generation.

  • ti_arm_cgt:

    TI ARM CGT cross-compiler for TMS570 target binaries; configures silicon version, ABI, optimisation, linker flags, hex/size/nm tools, and Lauterbach trace support.

  • unit_test_gcc:

    Host GCC with CMock/Unity/gcov for unit testing.

  • unit_test_spa_gcc:

    SPA in GCC configuration.

Finally queues the vscode command to regenerate IDE workspace files.

wscript.options(opt: OptionsContext)

Register all command-line options for the foxBMS build system.

Loads option definitions from waf tools, removes unused stock waf options, unregisters the install/uninstall commands, and adds the --confcache switch.