wscript

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# Copyright (c) 2010 - 2021, Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V.
# All rights reserved.
#
# SPDX-License-Identifier: BSD-3-Clause
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# 1. Redistributions of source code must retain the above copyright notice, this
#    list of conditions and the following disclaimer.
#
# 2. Redistributions in binary form must reproduce the above copyright notice,
#    this list of conditions and the following disclaimer in the documentation
#    and/or other materials provided with the distribution.
#
# 3. Neither the name of the copyright holder nor the names of its
#    contributors may be used to endorse or promote products derived from
#    this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#
# We kindly request you to use one or more of the following phrases to refer to
# foxBMS in your hardware, software, documentation or advertising materials:
#
# - "This product uses parts of foxBMS®"
# - "This product includes parts of foxBMS®"
# - "This product is derived from foxBMS®"

"""Main Build Script: ``./wscript``
================================

This script defines how to configure and build the project. This includes
configuration the toolchain for building foxBMS binaries, the documentation
and running various checks on the source files.
"""


import os
import sys
import tarfile
import shlex
import pathlib
import json
import jsonschema
import tabulate

from waflib import Build, Configure, Context, Errors, Logs, Options, Utils, Scripting
from waflib.Build import (
    BuildContext,
    CleanContext,
    InstallContext,
    ListContext,
    StepContext,
)

Context.Context.line_just = 50
Configure.autoconfig = 1

out = "build"  # pylint:disable=invalid-name
"""output directory"""
top = "."  # pylint:disable=invalid-name
"""waf top directory"""

APPNAME = "foxBMS"
"""name of the application. This is used in various waf functions"""

VERSION = "1.2.1"
"""version of the application. This is used in various waf functions. This
version must match the version number defined in ``macros.txt``. Otherwise a
configuration error is thrown."""

BIN_VARIANTS = ["bin", "axivion"]
"""Binary build command variations that are supported. The commands are then
generated by concatenating the command + the variant, e.g., ``build_bin``"""

MISC_VARIANTS = ["docs", "unit_test", "static_analysis"]
"""Additional commands, that do not need more contexts than build and clean"""

ALL_VARIANTS = {"binary": BIN_VARIANTS, "misc": MISC_VARIANTS}

TOOLDIR = os.path.join("tools", "waf-tools")

for target_type, target_val in ALL_VARIANTS.items():
    contexts = (BuildContext, CleanContext)
    if target_type == "binary":
        contexts += (ListContext, StepContext)
    for var in target_val:
        # save contexts
        old_contexts = contexts
        if var == "bin":
            contexts += (InstallContext,)
        for cont in contexts:
            # pylint: disable=invalid-name
            name = cont.__name__.replace("Context", "").lower()

            # pylint:disable=invalid-name,too-many-ancestors,too-few-public-methods
            class tmp_1(cont):
                """Helper class to create the build variant commands"""

                if name == "build":
                    __doc__ = f"executes the {name} of {var}"
                elif name == "install":
                    __doc__ = f"flash {var} to the target"
                elif name == "clean":
                    __doc__ = f"cleans the project {var}"
                elif name == "list":
                    __doc__ = f"lists the targets to execute for {var}"
                elif name == "step":
                    __doc__ = f"executes tasks in a step-by-step fashion, for debugging of {var}"
                cmd = str(name) + "_" + var
                variant = var

        # restore contexts
        contexts = old_contexts


BLD_VARIANTS = []
CLN_VARIANTS = []
# build and clean variants exist for all commands
for target_type, target_val in ALL_VARIANTS.items():
    for var in target_val:
        BLD_VARIANTS.append(f"build_{var}")
        CLN_VARIANTS.append(f"clean_{var}")

DIST_EXCLUDE = (
    f"{out}/** **/.git **/.gitignore .gitlab/** **/.gitattributes "
    "**/*.tar.bz2 **/*.tar.gz **/*.pyc __pycache__ "
    "tools/waf*.*.**-* .lock-* "
    f".ws *eclipse* .vs* { APPNAME.lower()}/**"
)
"""Files and directories that are excluded when running dist commands"""


def version_consistency_checker(ctx):
    """checks that all version strings in the repository are synced"""
    doc_dir = "docs"
    changelog_file = ctx.path.find_node(
        os.path.join(doc_dir, "general", "changelog.rst")
    )
    changelog_txt = changelog_file.read(encoding="utf-8")
    m_file = ctx.path.find_node(os.path.join(doc_dir, "macros.txt"))
    m_file_txt = m_file.read(encoding="utf-8")
    gs_file = ctx.path.find_node(
        os.path.join(doc_dir, "getting-started", "software-installation.rst")
    )
    gs_file_txt = gs_file.read()
    if m_file_txt.find(f".. |version_foxbms| replace:: ``{VERSION}``") < 0:
        ctx.fatal(
            f"The version information in {m_file} is different from the "
            f"specified version {VERSION}."
        )
    if changelog_txt.find(f"[{VERSION}]") < 0:
        ctx.fatal(
            f"The version information in {changelog_file} is different "
            f"from the specified version {VERSION}."
        )
    repo_url = "https://github.com/foxBMS/foxbms-2"
    must_include_version = [
        f"curl -Ss -L -o foxbms-2-v{VERSION}.zip {repo_url}/archive/v{VERSION}.zip",
        f"tar -x -f foxbms-2-v{VERSION}.zip",
        f"ren foxbms-2-{VERSION} foxbms-2",
    ]
    if not all(gs_file_txt.find(i) > 0 for i in must_include_version):
        ctx.fatal(
            f"The version information in {gs_file} is different from the "
            f"specified version {VERSION}"
        )
    pys = [
        ctx.path.find_node(os.path.join("tools", "gui", "fgui", "__init__.py")),
    ]
    if not all(i.read().find(f'__version__ = "{VERSION}"') > 0 for i in pys):
        ctx.fatal(f"Version information in {pys} is not correct.")


def options(opt):
    """Defines options that can be passed to waf"""
    opt.add_option(
        "--coverage",
        action="store_true",
        help="Builds a coverage report based on the unit test",
    )
    opt.load("f_axivion", tooldir=TOOLDIR)
    opt.load("f_sphinx_build", tooldir=TOOLDIR)
    opt.load("doxygen", tooldir=TOOLDIR)
    opt.load("f_cppcheck", tooldir=TOOLDIR)
    opt.load("f_ti_arm_cgt", tooldir=TOOLDIR)
    # load db-check-tool
    opt.load("f_check_db_vars", tooldir=TOOLDIR)
    # load bootstrap-library-project-tool
    opt.load("f_bootstrap_library_project", tooldir=TOOLDIR)
    opt.load("f_guidelines", tooldir=TOOLDIR)

    for k in (
        "--targets",
        "--out",
        "--top",
        "--prefix",
        "--destdir",
        "--bindir",
        "--libdir",
        "--msvc_version",
        "--msvc_targets",
        "--no-msvc-lazy",
        "--force",
        "--check-c-compiler",
        "doxygen",
    ):
        option = opt.parser.get_option(k)
        if option:
            opt.parser.remove_option(k)

    Context.classes.remove(Build.UninstallContext)

    opt.add_option(
        "--confcache",
        dest="confcache",
        default=0,
        action="count",
        help="Use a configuration cache",
    )

    opt.add_option(
        "--skip-doxygen",
        action="store_true",
        help="Builds the documentation without the Doxygen documentation",
    )

    opt.load("f_miniconda_env", tooldir=TOOLDIR)
    opt.load("f_lauterbach", tooldir=TOOLDIR)
    opt.add_option(
        "--why", dest="WHY", action="store_true", help="Loads the 'why' tool."
    )
    opt.load("f_j_flash", tooldir=TOOLDIR)
    opt.load("f_git_hooks", tooldir=TOOLDIR)


def configure(conf):  # pylint: disable=too-many-statements,too-many-branches
    """Configures the project.
    This includes loading all tools needed to build and link binaries,
    rendering the documentation and checking source files for style violations:
    The loaded tools are:

    - TI ARM compiler (`f_ti_arm_cgt`)
    - Documentation tools (`f_sphinx_build`, `doxygen`)

    To ensure that the active environment is the correct one for the project,
    all conda packages are checked to be installed in the correct version.

    A workspace is generated if Visual Studio Code is found on the machine.
    """
    if " " in conf.path.abspath():
        conf.fatal(f"Project path must not contain spaces ({conf.path}).")
    known_max_depth = 133
    if Utils.is_win32 and len(conf.path.abspath()) + known_max_depth > 260:
        conf.fatal(
            "Build path length will exceed 260 characters.\nClone or move the "
            "repository into a shorter path."
        )
    conf.msg("Checking project path", conf.path.abspath())

    version_consistency_checker(conf)

    conf.find_program("git", var="GIT")
    conf.load("f_node_helper", tooldir=TOOLDIR)
    conf.load("f_ti_arm_cgt", tooldir=TOOLDIR)
    fragment = "#include <stdint.h>\n\nint main() {\n    return 0;\n}\n"
    conf.check(
        features="c", fragment=fragment, msg="Checking for code snippet (object)"
    )

    fragment = "#include <stdint.h>\n\nint sum(int a, int b){\n    return (a + b);}\n"
    conf.check(
        features="c cstlib",
        fragment=fragment,
        msg="Checking for code snippet (library)",
    )

    def full_build(bld):
        c_fragment = "#include <stdint.h>\n\nint main() {\n    return 0;\n}\n"
        h_fragment = (
            "#ifndef GENERAL_H_\n#define GENERAL_H_\n#include <stdbool.h>\n"
            "#include <stdint.h>\n#endif /* GENERAL_H_ */\n"
        )
        source = bld.srcnode.make_node("test.c")
        source.parent.mkdir()
        source.write(c_fragment, encoding="utf-8")
        include = bld.srcnode.make_node("general.h")
        include.write(h_fragment, encoding="utf-8")
        linker_script = bld.path.find_node(
            os.path.join("..", "..", "src", "app", "main", "linker_script_elf.cmd")
        )
        version_header = bld.path.find_node(
            os.path.join(
                "..", "..", "src", "app", "main", "include", "config", "version_cfg.h"
            )
        )
        cflags = []
        if bld.env.RTSV_missing:
            cflags = ["--diag_remark=10366"]
        linker_pulls = bld.path.find_or_declare("linker_pulls.json")
        linker_pulls.write("{}\n")
        bld.tiprogram(
            includes=[include.parent, version_header.parent],
            source=[source],
            cflags=cflags,
            linker_script=linker_script,
            no_version=True,
            linker_pulls=linker_pulls,
        )

    default_env = conf.env
    test_env = conf.env.derive()
    test_env.detach()

    conf.setenv("test_env", test_env)
    rtsv_lib = "rtsv7R4_A_be_v3D16_eabi.lib"
    rtsv_lib_path = os.path.join(
        pathlib.Path(conf.env.get_flat("CC")).parent.parent.absolute(),
        "lib",
        rtsv_lib,
    )
    if not os.path.isfile(rtsv_lib_path):
        Logs.warn(
            f"Runtime support library '{rtsv_lib}' missing. Need to build "
            "it first. The next step may take a while..."
        )
        conf.env.RTSV_missing = True
    else:
        conf.env.RTSV_missing = False
    conf.env.STLIB = ["c"]
    conf.env.TARGETLIB = []
    if "--undef_sym=resetEntry" in conf.env.LINKFLAGS:
        conf.env.LINKFLAGS.remove("--undef_sym=resetEntry")
    conf.check(msg="Checking for code snippet (program)", build_fun=full_build)
    conf.setenv("", default_env)

    conf.load("f_miniconda_env", tooldir=TOOLDIR)
    conf.load("f_check_db_vars", tooldir=TOOLDIR)

    conf.load("f_bootstrap_library_project", tooldir=TOOLDIR)
    conf.load("f_guidelines", tooldir=TOOLDIR)

    # add flasher tool
    conf.load("f_j_flash", tooldir=TOOLDIR)

    # configure the documentation toolchain
    conf.load("f_sphinx_build", tooldir=TOOLDIR)
    conf.load("doxygen", tooldir=TOOLDIR)
    conf.load("f_unit_test", tooldir=TOOLDIR)
    conf.load("f_cppcheck", tooldir=TOOLDIR)
    conf.env.VSCODE_MK_DIRS = [
        os.path.join(out, "unit_test", "test", "mocks"),
        os.path.join(out, "bin", "src", "app", "main"),
        os.path.join(out, "bin", "src", "hal", "include"),
        os.path.join(out, "bin", "src", "hal", "source"),
    ]
    conf.load("f_ozone", tooldir=TOOLDIR)
    conf.load("f_lauterbach", tooldir=TOOLDIR)
    conf.load("f_axivion", tooldir=TOOLDIR)

    # Configure the build for the correct operating system
    bms_config = json.loads(
        conf.path.find_node(os.path.join("conf", "bms", "bms.json")).read()
    )
    bms_config_schema = json.loads(
        conf.path.find_node(
            os.path.join("conf", "bms", "schema", "bms.schema.json")
        ).read()
    )
    try:
        jsonschema.validate(instance=bms_config, schema=bms_config_schema)
    except jsonschema.exceptions.ValidationError as err:
        good_values = ", ".join([f"'{i}'" for i in err.validator_value])
        conf.fatal(
            f"Setting '{err.instance}' in '{'/'.join(list(err.path))}' is not "
            f"supported.\nUse one of these: {good_values}."
        )

    conf.env.append_unique(
        "CONF_OPERATING_SYSTEM_NAME", bms_config["operating-system"]["name"]
    )
    # set define before loading the VS Code tool
    conf.define(f"FOXBMS_USES_{conf.env.CONF_OPERATING_SYSTEM_NAME[0].upper()}", 1)

    # load VS Code setup as last foxBMS specific tool to ensure that all
    # variables have a meaningful value
    conf.load("f_vscode", tooldir=TOOLDIR)
    conf.load("f_git_hooks", tooldir=TOOLDIR)

    # the project has been successfully configured, now we can set the
    # application name and version
    conf.env.APPNAME = APPNAME
    conf.env.VERSION = VERSION
    if conf.options.WHY:
        conf.load("why", tooldir=TOOLDIR)


def build(bld):  # pylint: disable=too-many-branches,too-many-statements
    """High level definition of the build details"""
    if not bld.variant:
        bld.fatal(
            f"A {bld.cmd} variant must be specified. The build variants are: "
            f"{', '.join(BLD_VARIANTS)}.\nFor more details run 'python "
            f"tools{os.sep}waf --help'"
        )
    # we need to patch the build instructions for the Axivion build, and by
    # that the "normal" build using TI ARM CGT gets broken (only in that
    # context!), therefore (build|clean)_axivion must only be used as last
    # build commands if multiple commands are supplied.
    all_commands = [bld.cmd] + Options.commands  # current command + remaining
    if any(x in all_commands for x in ["build_axivion", "clean_axivion"]):
        b_idx = sys.maxsize
        try:
            b_idx = all_commands.index("build_axivion")
        except ValueError:
            pass
        c_idx = sys.maxsize
        try:
            c_idx = all_commands.index("clean_axivion")
        except ValueError:
            pass
        min_idx = min([b_idx, c_idx])
        ax_commands = all_commands[min_idx:]
        err = 0
        for i in ax_commands:
            if not "_axivion" in i:
                err += 1
                Logs.error(f"'{i}' must not be used in that order {all_commands!r}.")
        if err:
            bld.fatal(
                "Axivion related commands must be moved to the end of the "
                "command list, i.e. all other build commands must precede the "
                "axivion commands."
            )
    version_consistency_checker(bld)
    bld.env.append_unique(
        "CMD_FILES",
        [bld.path.find_node(os.path.join("conf", "cc", "remarks.txt")).abspath()],
    )
    bms_config = json.loads(
        bld.path.find_node(os.path.join("conf", "bms", "bms.json")).read()
    )
    bms_config_schema = json.loads(
        bld.path.find_node(
            os.path.join("conf", "bms", "schema", "bms.schema.json")
        ).read()
    )
    try:
        jsonschema.validate(instance=bms_config, schema=bms_config_schema)
    except jsonschema.exceptions.ValidationError as err:
        good_values = ", ".join([f"'{i}'" for i in err.validator_value])
        bld.fatal(
            f"Setting '{err.instance}' in '{'/'.join(list(err.path))}' is not "
            f"supported.\nUse one of these: {good_values}."
        )

    bld.env.append_unique(
        "OPERATING_SYSTEM_NAME", bms_config["operating-system"]["name"]
    )
    if not bld.env.OPERATING_SYSTEM_NAME[0] == bld.env.CONF_OPERATING_SYSTEM_NAME[0]:
        bld.fatal("The operating system has changed. Re-configure the project.")
    # get operatin system includes
    freertos_details = json.loads(
        bld.path.find_node(
            os.path.join(
                "src",
                "os",
                bld.env.OPERATING_SYSTEM_NAME[0],
                f"{bld.env.OPERATING_SYSTEM_NAME[0]}_cfg.json",
            )
        ).read()
    )

    operating_system_includes = [
        os.path.join("src", "os", bms_config["operating-system"]["name"], i)
        for i in freertos_details["include"]
    ]
    bld.env.append_unique(
        "INCLUDES_OPERATING_SYSTEM",
        [bld.path.find_node(i) for i in operating_system_includes],
    )

    slave_config = bms_config["slave-unit"]
    afe = slave_config["analog-front-end"]
    bld.env.afe_manufacturer = afe["manufacturer"]
    bld.env.afe_chip = afe["chip"]
    afe_ic_inc = afe["chip"]
    if afe["chip"] in ("6804-1", "6811-1", "6812-1"):
        afe_ic_inc = "6813-1"
    # get AFE includes
    incs = os.path.join(
        "src",
        "app",
        "driver",
        "afe",
        afe["manufacturer"],
        afe_ic_inc,
        f"{afe['manufacturer']}_{afe_ic_inc}.json",
    )
    afe_details = json.loads(bld.path.find_node(incs).read())
    afe_includes = [
        os.path.join("src", "app", "driver", "afe", afe["manufacturer"], afe["chip"], i)
        for i in afe_details["include"]
    ]
    bld.env.append_unique("INCLUDES_AFE", [bld.path.find_node(i) for i in afe_includes])
    bld.env.balancing_strategy = slave_config["balancing-strategy"]
    bld.env.balancing_possible = slave_config["balancing-strategy"] != "none"

    temperature_sensor_config = slave_config["temperature-sensor"]
    bld.env.temperature_sensor_manuf = temperature_sensor_config["manufacturer"]
    bld.env.temperature_sensor_model = temperature_sensor_config["model"]
    bld.env.temperature_sensor_meth = temperature_sensor_config["method"]

    app_cfg = bms_config["application"]
    # SOx includes
    state_estimators = app_cfg["algorithm"]["state-estimation"]
    bld.env.ALGORITHM_SOC = soc = state_estimators["soc"]
    bld.env.ALGORITHM_SOE = soe = state_estimators["soe"]
    bld.env.ALGORITHM_SOH = soh = state_estimators["soh"]
    estimators_base_path = os.path.join(
        "src", "app", "application", "algorithm", "state_estimation"
    )
    for i, val in zip([soc, soe, soh], ["soc", "soe", "soh"]):
        bld.env.append_unique(
            f"INCLUDES_STATE_ESTIMATOR_+{val.upper()}",
            [bld.path.find_node(os.path.join(estimators_base_path, val, i))],
        )
    imd_cfg = app_cfg["insulation-monitoring-device"]
    bld.env.imd_manufacturer = imd_cfg["manufacturer"]
    bld.env.imd_model = imd_cfg["model"]
    bld.env.append_unique(
        "INCLUDES_IMD",
        [bld.path.find_node(i) for i in [bld.env.imd_manufacturer + bld.env.imd_model]],
    )
    if bld.variant == "bin":
        bld(
            features="swi-check",
            files=bld.path.ant_glob("src/**/*.c src/**/*.h"),
            jump_table_file=bld.path.find_node(
                os.path.join(
                    "src",
                    "os",
                    "freertos",
                    "portable",
                    "ccs",
                    "arm_cortex-r5",
                    "portasm.asm",
                )
            ),
        )
        if Logs.verbose:
            balancing_info_str = "Not supported by chip"
            if bld.env.balancing_possible:
                balancing_info_str = bld.env.balancing_strategy
            info = tabulate.tabulate(
                [
                    ["Setting", "Value"],
                    ["Operating system", bld.env.OPERATING_SYSTEM_NAME[0]],
                    [
                        "AFE",
                        f"{bld.env.afe_manufacturer} {bld.env.afe_chip}",
                    ],
                    ["Balancing strategy", balancing_info_str],
                    [
                        "Battery pack temperature sensing",
                        f"{bld.env.temperature_sensor_manuf} {bld.env.temperature_sensor_model} "
                        f"({bld.env.temperature_sensor_meth})",
                    ],
                ],
                showindex=True,
                headers="firstrow",
            )
            print(info)
        bld.recurse("src")

    if bld.variant == "axivion":
        if not bld.env.AXIVION_CC:
            Logs.warn("Axivion tools not available.")
            return
        bld.patch_for_axivion_build(bld)

        bld.recurse("src")

    if bld.variant == "unit_test":
        Options.commands = ["check_testfiles"] + Options.commands
        if bld.cmd.startswith("clean"):
            return
        if bld.cmd.startswith("build"):
            if not bld.env.CEEDLING:
                bld.fatal("Can not run unit tests as ceedling is missing.")
            if not bld.env.GCC:
                bld.fatal("Can not run unit tests as gcc is missing.")
            if not bld.env.GCOV:
                bld.fatal("Can not run unit tests as gcov is missing.")
            if not bld.env.GCOVR:
                bld.fatal("Can not run unit tests as gcovr is missing.")

        bld(
            features="db_check",
            files=bld.path.ant_glob("tests/unit/**/*.c"),
        )
        bld.add_group()
        source = bld.path.find_node(bld.env.CEEDLING_MAIN_PROJECT_FILE)
        bld(
            features="subst",
            source=source,
            target=source.name,
            is_copy=True,
        )
        source = bld.path.find_node(bld.env.CEEDLING_CMD_FILE)
        bld(
            features="subst",
            source=source,
            target=source.name,
            is_copy=True,
        )
        bld(
            source=os.path.join("conf", "hcg", "hcg.hcg"),
            unit_test=True,
            startup_hash=bld.path.find_node(os.path.join("src", "hal", "startup.hash")),
        )
        bld.add_group()
        bld(features="ceedling")

    if bld.variant == "static_analysis":
        if bld.cmd.startswith("clean"):
            return
        if not bld.env.CPPCHECK and bld.cmd.startswith("build"):
            bld.fatal("Can not run static analysis as cppcheck is missing.")
        bld(
            features="cppcheck",
            config="conf/spa/cppcheck.cppcheck",
            root=".",
            paths="src/app src/opt",
            exclude="src/hal src/os",
            addons="threadsafety y2038 cert misra",
            options=[
                "--std=c11",
                "--force",
                "--enable=warning,style,performance,portability,information,unusedFunction",
            ],
            misra="conf/spa/cppcheckmisra.json",
            suppressions="conf/spa/cppcheck-suppression.txt",
            exit_code=42,
        )
    if bld.variant == "docs":
        # General documentation build
        # There are two contexts defined. The first one copies the ``wscript`` files
        # to the build directory with a ``.py`` extension to make the build scripts
        # autodoc-able.
        # At next the jinja2 templates generate the specific template files for documentation.
        # At next doxygen is run, to ensure that doxygen's xml output is build.
        # After that the regular documentation can be build using sphinx-build, which
        # now includes the build documentation as well as the API documentation from
        # doxygen.
        bld.recurse(
            [
                os.path.join("docs", "developer-manual", "style-guide", "examples"),
                os.path.join(
                    "docs", "developer-manual", "style-guide", "state-machine-example"
                ),
                os.path.join("docs", "software", "modules", "engine", "database"),
                os.path.join("docs", "software", "modules", "task", "ftask"),
            ],
        )
        doc_dir = "docs"
        bld.post_mode = Build.POST_LAZY

        bld.add_group("generate_doc_files")
        bld.add_group("doxygen")
        bld.add_group("sphinx")

        bld.set_group("generate_doc_files")
        # we use absolute paths for the doxygen configuration as it is written
        # during configuration time, and therefore this is okay
        # fmt: off
        # pylint: disable=line-too-long
        _input = [
            bld.path.find_node(os.path.join("docs", "developer-manual", "style-guide", "state-machine-example")),
            bld.path.find_node("src")
        ]
        _project_logo = bld.path.find_node(os.path.join("docs", "_static", "foxbms250px.png"))
        _exclude = [
            bld.path.find_node(os.path.join("src", "hal")),
            bld.path.find_node(os.path.join("src", "os")),
            bld.path.find_node(os.path.join("src", "app", "driver", "imd", "bender")),
            bld.path.find_node(os.path.join("src", "app", "driver", "afe", "ltc", "common", "ltc_pec.c")),
            bld.path.find_node(os.path.join("src", "app", "driver", "afe", "ltc", "common", "ltc_pec.h")),
            bld.path.find_node(os.path.join("src", "app", "driver", "afe", "nxp", "common", "MC33775A.h")),
        ]
        _html_footer = bld.path.find_node(os.path.join("docs", "doxygen_footer.html"))
        _layout_file = bld.path.find_node(os.path.join("docs", "doxygen_layout.xml"))
        _html_stylesheet = bld.path.find_node(os.path.join("docs", "stylesheetfile.css"))
        _html_extra_files = bld.path.find_node(os.path.join("docs", "_static", "cc.large.png"))
        _image_path = bld.path.find_node(os.path.join("docs", "_static", "cc.large.png"))
        # pylint: enable=line-too-long
        # fmt: on
        if not all(
            (
                _input,
                _project_logo,
                _exclude[:],
                _html_footer,
                _layout_file,
                _html_stylesheet,
                _html_extra_files,
                _image_path,
            )
        ):
            bld.fatal("Some doxygen input is not correct.")
        doxy_conf_src = bld.path.get_bld().find_or_declare("doxygen_src.conf")
        bld(
            features="subst",
            source=bld.path.find_node(os.path.join("docs", "doxygen_src.conf.in")),
            target=doxy_conf_src,
            PROJECT_NAME=APPNAME,
            PROJECT_NUMBER=VERSION,
            PROJECT_BRIEF=f'"The {APPNAME} Battery Management System API Documentation"',
            PROJECT_LOGO=_project_logo.abspath(),
            OUTPUT_DIRECTORY="_static/doxygen/src",
            INPUT=" ".join([i.abspath() for i in _input]),
            EXCLUDE=" ".join([i.abspath() for i in _exclude]),
            HTML_FOOTER=_html_footer.abspath(),
            LAYOUT_FILE=_layout_file.abspath(),
            HTML_STYLESHEET=_html_stylesheet.abspath(),
            HTML_EXTRA_FILES=_html_extra_files.abspath(),
            IMAGE_PATH=_image_path.abspath(),
        )
        _input = [
            bld.path.find_node("src/app"),
            bld.path.find_node("tests/unit"),
        ]
        doxy_conf_tests = bld.path.get_bld().find_or_declare("doxygen_tests.conf")
        bld(
            features="subst",
            source=bld.path.find_node(os.path.join("docs", "doxygen_tests.conf.in")),
            target=doxy_conf_tests,
            PROJECT_NAME=f"{APPNAME} - Unit Tests",
            PROJECT_NUMBER=VERSION,
            PROJECT_BRIEF=f'"The {APPNAME} Unit Tests API Documentation"',
            PROJECT_LOGO=_project_logo.abspath(),
            OUTPUT_DIRECTORY="_static/doxygen/tests",
            INPUT=" ".join([i.abspath() for i in _input]),
            EXCLUDE=" ".join([i.abspath() for i in _exclude]),
            HTML_FOOTER=_html_footer.abspath(),
            LAYOUT_FILE=_layout_file.abspath(),
            HTML_STYLESHEET=_html_stylesheet.abspath(),
            HTML_EXTRA_FILES=_html_extra_files.abspath(),
            IMAGE_PATH=_image_path.abspath(),
        )
        bld.set_group("doxygen")
        doxy_conf_src = bld.path.get_bld().find_or_declare("doxygen_src.conf")
        doxy_conf_tests = bld.path.get_bld().find_or_declare("doxygen_tests.conf")
        if not bld.options.skip_doxygen:
            bld(features="doxygen", doxygen_conf=doxy_conf_src)
            bld(features="doxygen", doxygen_conf=doxy_conf_tests)

        bld.set_group("sphinx")
        # fmt: off
        # pylint: disable=line-too-long
        sources = [
            os.path.join(doc_dir, "index.rst"),
            os.path.join(doc_dir, "macros.txt"),
            os.path.join(doc_dir, "units.txt"),
            os.path.join(doc_dir, "general", "changelog.rst"),
            os.path.join(doc_dir, "general", "license.rst"),
            os.path.join(doc_dir, "general", "licenses-packages-conda-env-win32.csv"),
            os.path.join(doc_dir, "general", "licenses-packages-conda-env-spelling.txt"),
            os.path.join(doc_dir, "general", "licenses-packages-conda-env-spelling-build-strings.txt"),
            os.path.join(doc_dir, "general", "licenses-vscode-extensions.csv"),
            os.path.join(doc_dir, "general", "motivation.rst"),
            os.path.join(doc_dir, "general", "releases.rst"),
            os.path.join(doc_dir, "general", "releases.csv"),
            os.path.join(doc_dir, "general", "safety", "safety.rst"),
            os.path.join(doc_dir, "general", "team.rst"),
            os.path.join(doc_dir, "general", "team-ad-sc.rst"),
            os.path.join(doc_dir, "general", "team-dev.rst"),
            os.path.join(doc_dir, "general", "team-former.rst"),
            os.path.join(doc_dir, "introduction", "abbreviations-definitions.rst"),
            os.path.join(doc_dir, "introduction", "bms-overview.rst"),
            os.path.join(doc_dir, "getting-started", "getting-started.rst"),
            os.path.join(doc_dir, "getting-started", "repository-structure.rst"),
            os.path.join(doc_dir, "getting-started", "software-installation.rst"),
            os.path.join(doc_dir, "getting-started", "workspace.rst"),
            os.path.join(doc_dir, "getting-started", "first-steps-on-hardware.rst"),
            os.path.join(doc_dir, "hardware", "hardware.rst"),
            os.path.join(doc_dir, "hardware", "design-resources.rst"),
            os.path.join(doc_dir, "hardware", "connectors.rst"),
            os.path.join(doc_dir, "misc", "bibliography.rst"),
            os.path.join(doc_dir, "misc", "definitions.csv"),
            os.path.join(doc_dir, "misc", "developer-manual-nomenclature.csv"),
            os.path.join(doc_dir, "misc", "indices-and-tables.rst"),
            os.path.join(doc_dir, "software", "api", "overview.rst"),
            os.path.join(doc_dir, "software", "build", "build.rst"),
            os.path.join(doc_dir, "software", "build-process", "library-project_how-to.rst"),
            os.path.join(doc_dir, "software", "build-environment", "build-environment.rst"),
            os.path.join(doc_dir, "software", "build-environment", "build-environment_how-to.rst"),
            os.path.join(doc_dir, "software", "build-process", "build-process.rst"),
            os.path.join(doc_dir, "software", "configuration", "configuration.rst"),
            os.path.join(doc_dir, "software", "configuration", "without-halcogen_how-to.rst"),
            os.path.join(doc_dir, "software", "how-to", "how-to.rst"),
            os.path.join(doc_dir, "software", "modules", "modules.rst"),
            os.path.join(doc_dir, "software", "modules", "application", "algorithm", "state-estimation", "soc", "soc_counting.rst"),
            os.path.join(doc_dir, "software", "modules", "application", "algorithm", "state-estimation", "soc", "soc_debug.rst"),
            os.path.join(doc_dir, "software", "modules", "application", "algorithm", "state-estimation", "soc", "soc_none.rst"),
            os.path.join(doc_dir, "software", "modules", "application", "algorithm", "state-estimation", "soe", "soe_counting.rst"),
            os.path.join(doc_dir, "software", "modules", "application", "algorithm", "state-estimation", "soe", "soe_debug.rst"),
            os.path.join(doc_dir, "software", "modules", "application", "algorithm", "state-estimation", "soe", "soe_none.rst"),
            os.path.join(doc_dir, "software", "modules", "application", "algorithm", "state-estimation", "sof", "trapezoid.rst"),
            os.path.join(doc_dir, "software", "modules", "application", "algorithm", "state-estimation", "soh", "soh_debug.rst"),
            os.path.join(doc_dir, "software", "modules", "application", "algorithm", "state-estimation", "soh", "soh_none.rst"),
            os.path.join(doc_dir, "software", "modules", "application", "algorithm", "state-estimation", "state-estimation.rst"),
            os.path.join(doc_dir, "software", "modules", "application", "algorithm", "algorithm.rst"),
            os.path.join(doc_dir, "software", "modules", "application", "bal", "bal.rst"),
            os.path.join(doc_dir, "software", "modules", "application", "bms", "bms.rst"),
            os.path.join(doc_dir, "software", "modules", "application", "plausibility", "plausibility.rst"),
            os.path.join(doc_dir, "software", "modules", "application", "redundancy", "redundancy.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "adc", "adc.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "can", "can.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "contactor", "contactor.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "dma", "dma.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "foxmath", "foxmath.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "fram", "fram.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "imd", "bender", "bender_ir155.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "imd", "bender", "bender_iso165c.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "imd", "none", "no-imd.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "imd", "imd.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "interlock", "interlock.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "io", "io.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "mcu", "mcu.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "meas", "meas.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "afe", "supported-afes.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "afe", "ltc", "6806.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "afe", "ltc", "6811-1.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "afe", "ltc", "6812-1.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "afe", "ltc", "6813-1.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "afe", "maxim", "max1785x.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "afe", "nxp", "mc33775a.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "rtc", "rtc.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "sbc", "sbc.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "spi", "spi.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "sps", "sps.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "ts", "epcos", "b57251v5103j060.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "ts", "epcos", "b57861s0103f045.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "ts", "fake", "none.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "ts", "vishay", "ntcalug01a103g.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "ts", "vishay", "ntcle317e4103sba.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "ts", "adding-a-new-ts_how-to.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "ts", "ts-sensors.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "ts", "ts.rst"),
            os.path.join(doc_dir, "software", "modules", "driver", "ts", "ts-short-names.csv"),
            os.path.join(doc_dir, "software", "modules", "engine", "database", "database.rst"),
            os.path.join(doc_dir, "software", "modules", "engine", "database", "database_how-to.rst"),
            os.path.join(doc_dir, "software", "modules", "engine", "diag", "diag.rst"),
            os.path.join(doc_dir, "software", "modules", "engine", "diag", "diag_how-to.rst"),
            os.path.join(doc_dir, "software", "modules", "engine", "sys", "sys.rst"),
            os.path.join(doc_dir, "software", "modules", "engine", "sys_mon", "sys_mon.rst"),
            os.path.join(doc_dir, "software", "modules", "main", "fassert_how-to.rst"),
            os.path.join(doc_dir, "software", "modules", "main", "startup.rst"),
            os.path.join(doc_dir, "software", "modules", "main", "version.rst"),
            os.path.join(doc_dir, "software", "modules", "task", "ftask", "ftask.rst"),
            os.path.join(doc_dir, "software", "modules", "task", "ftask", "ftask_how-to.rst"),
            os.path.join(doc_dir, "software", "modules", "task", "os", "os.rst"),
            os.path.join(doc_dir, "software", "unit-tests", "unit-tests.rst"),
            os.path.join(doc_dir, "software", "unit-tests", "unit-tests_how-to.rst"),
            os.path.join(doc_dir, "tools", "halcogen", "halcogen.rst"),
            os.path.join(doc_dir, "tools", "static-analysis", "axivion.rst"),
            os.path.join(doc_dir, "tools", "static-analysis", "cppcheck.rst"),
            os.path.join(doc_dir, "tools", "waf-tools", "f_axivion.rst"),
            os.path.join(doc_dir, "tools", "waf-tools", "f_black.rst"),
            os.path.join(doc_dir, "tools", "waf-tools", "f_bootstrap_library_project.rst"),
            os.path.join(doc_dir, "tools", "waf-tools", "f_check_db_vars.rst"),
            os.path.join(doc_dir, "tools", "waf-tools", "f_clang_format.rst"),
            os.path.join(doc_dir, "tools", "waf-tools", "f_cppcheck.rst"),
            os.path.join(doc_dir, "tools", "waf-tools", "f_git_hooks.rst"),
            os.path.join(doc_dir, "tools", "waf-tools", "f_guidelines.rst"),
            os.path.join(doc_dir, "tools", "waf-tools", "f_hcg.rst"),
            os.path.join(doc_dir, "tools", "waf-tools", "f_miniconda_env.rst"),
            os.path.join(doc_dir, "tools", "waf-tools", "f_ozone.rst"),
            os.path.join(doc_dir, "tools", "waf-tools", "f_pylint.rst"),
            os.path.join(doc_dir, "tools", "waf-tools", "f_sphinx_build.rst"),
            os.path.join(doc_dir, "tools", "waf-tools", "ti-arm-compiler-tools.csv"),
            os.path.join(doc_dir, "tools", "waf-tools", "ti-arm-compiler-tools.rst"),
            os.path.join(doc_dir, "tools", "waf-tools", "compiler-tool", "f_ti_arm_cgt.rst"),
            os.path.join(doc_dir, "tools", "waf-tools", "compiler-tool", "f_ti_arm_helper.rst"),
            os.path.join(doc_dir, "tools", "waf-tools", "compiler-tool", "f_ti_arm_tools.rst"),
            os.path.join(doc_dir, "tools", "waf-tools", "compiler-tool", "f_ti_color_arm_cgt.rst"),
            os.path.join(doc_dir, "tools", "waf-tools", "f_unit_test.rst"),
            os.path.join(doc_dir, "tools", "waf-tools", "f_vscode.rst"),
            os.path.join(doc_dir, "tools", "waf-tools", "waf-tools.rst"),
            os.path.join(doc_dir, "tools", "log-parser.rst"),
            os.path.join(doc_dir, "tools", "debugger", "debug-application.rst"),
            os.path.join(doc_dir, "tools", "debugger", "debugger-ozone.rst"),
            os.path.join(doc_dir, "tools", "debugger", "debugger-lauterbach.rst"),
            os.path.join(doc_dir, "developer-manual", "hardware-developer-manual.rst"),
            os.path.join(doc_dir, "developer-manual", "preface.rst"),
            os.path.join(doc_dir, "developer-manual", "software-developer-manual.rst"),
            os.path.join(doc_dir, "developer-manual", "software", "software-development-process.rst"),
            os.path.join(doc_dir, "developer-manual", "software", "software-programming-language.rst"),
            os.path.join(doc_dir, "developer-manual", "software", "software-testing.rst"),
            os.path.join(doc_dir, "developer-manual", "software", "software-tools.rst"),
            os.path.join(doc_dir, "developer-manual", "software", "software-verification.rst"),
            os.path.join(doc_dir, "developer-manual", "style-guide", "guidelines_c.rst"),
            os.path.join(doc_dir, "developer-manual", "style-guide", "guidelines_rst.rst"),
            os.path.join(doc_dir, "developer-manual", "style-guide", "guidelines_python.rst"),
            os.path.join(doc_dir, "developer-manual", "style-guide", "state-machines_how-to.rst"),
            os.path.join(doc_dir, "developer-manual", "style-guide", "style-guide.rst"),
        ]
        # pylint: enable=line-too-long
        # fmt: on
        source = []
        for src in sources:
            node = bld.path.find_node(src)
            if not node:
                bld.fatal(f"{src} does not exist.")
            source.append(node)
        config = bld.path.find_node(os.path.join("docs", "conf.py"))
        bld(
            features="sphinx",
            builders="html spelling",
            outdir=".",
            source=source,
            confpy=config,
            VERSION=bld.env.version,
            RELEASE=bld.env.version,
        )


def build_all(ctx):  # pylint: disable=unused-argument
    """shortcut to build all variants"""
    # axivion, if existing, needs to be inserted at the end of build commands
    has_ax = ""
    for bld_var in BLD_VARIANTS:
        if "axivion" in bld_var:
            has_ax = "axivion"
            continue
        Options.commands.append(bld_var)
    if has_ax:
        Options.commands.append("build_axivion")


def clean_all(ctx):  # pylint: disable=unused-argument
    """shortcut to clean all variants"""
    # axivion, if existing, needs to be inserted at the end of clean commands
    has_ax = ""
    for cln_var in CLN_VARIANTS:
        if "axivion" in cln_var:
            has_ax = "axivion"
            continue
        Options.commands.append(cln_var)
    if has_ax:
        Options.commands.append("clean_axivion")


def dist(conf):
    """creates a archive based on the current repository state"""
    conf.base_name = APPNAME.lower()
    conf.algo = "tar.gz"
    conf.excl = DIST_EXCLUDE


def distcheck_cmd(self):  # pylint: disable=unused-argument,missing-function-docstring
    # overwrite distcheck_cmd
    cfg = []
    if Options.options.distcheck_args:
        cfg = shlex.split(Options.options.distcheck_args)
    else:
        cfg = [x for x in sys.argv if x.startswith("-")]
    if "-c" in cfg and not "yes" in cfg:
        cfg.insert(cfg.index("-c") + 1, "yes")
    dist_waf = os.path.relpath(sys.argv[0], self.path.abspath())
    cmd = [
        sys.executable,
        os.path.join(self.path.abspath(), self.get_base_name(), dist_waf),
        "configure",
        "build_all",
    ] + cfg
    return cmd


def check_cmd(self):  # pylint: disable=missing-function-docstring
    # overwrite check_cmd
    full_arch = self.get_arch_name().split(self.algo)[0]
    if full_arch.endswith("."):
        full_arch = full_arch[:-1]
    full_arch = f"{full_arch}-build.tar.gz"
    with tarfile.open(self.get_arch_name()) as _tarfile:
        for _file in _tarfile:
            _tarfile.extract(_file)
    cmd = self.make_distcheck_cmd()
    ret = Utils.subprocess.Popen(cmd, cwd=self.get_base_name()).wait()
    if ret:
        raise Errors.WafError(f"distcheck failed with code {ret}")
    if getattr(self, "tar_build", False):
        with tarfile.open(full_arch, "w:gz") as tar:
            tar.add(
                self.get_arch_name(), arcname=os.path.basename(self.get_arch_name())
            )
            tar.add(
                os.path.join(APPNAME.lower(), out),
                arcname=os.path.join(APPNAME.lower(), out),
            )


def distcheck(conf):
    """creates tar.bz form the source directory and tries to run a build"""
    Scripting.DistCheck.make_distcheck_cmd = distcheck_cmd
    Scripting.DistCheck.check = check_cmd
    conf.base_name = APPNAME.lower()
    conf.excl = DIST_EXCLUDE


class DistCheckBin(Scripting.DistCheck):
    """Wrapper class to create a distcheck run that includes the build folder"""

    fun = "distcheck_bin"
    cmd = "distcheck_bin"


def distcheck_bin(conf):
    """creates tar.bz form the source directory and tries to run a build, and
    includes the build output in the archive"""
    conf.tar_build = True
    Scripting.DistCheck.make_distcheck_cmd = distcheck_cmd
    Scripting.DistCheck.check = check_cmd
    conf.base_name = APPNAME.lower()
    conf.excl = DIST_EXCLUDE


def check_testfiles(ctx):
    """Check if test files to corresponding source files exist."""
    prefix = os.path.join(ctx.path.abspath(), "src") + os.pathsep
    sources = [
        i.abspath()[len(prefix) :]
        for i in ctx.path.ant_glob(
            "src/app/**/*.c src/opt/**/*.c",
            excl=[
                "src/app/driver/sbc/fs8x_driver/**",
                "src/app/driver/afe/ltc/common/ltc_pec.*",
                "src/hal/**",
                "src/os/**",
            ],
        )
    ]

    prefix = os.path.join(ctx.path.abspath(), "tests", "unit") + os.pathsep
    tests = [
        i.abspath()[len(prefix) :].replace("test_", "")
        for i in ctx.path.ant_glob("tests/unit/**/test_*.c")
    ]
    diff = set(sources) - set(tests)
    err_msg = ""
    for i in diff:
        test_file = os.path.join(
            ctx.path.abspath(), "tests", "unit", f"test_{pathlib.Path(i).name}"
        )
        test_file = os.path.join(
            "tests",
            "unit",
            i.replace(pathlib.Path(i).name, f"test_{pathlib.Path(i).name}"),
        )
        err_msg += f"Missing test file for:  {i} (should be in: {test_file})\n"
    if diff:
        ctx.fatal(f"{err_msg}\nTest files are missing.")