7. Dependency Management

foxBMS 2 uses other tools in order to build embedded sources, unit tests, documentation and other tools. These dependencies are either part of the repository (e.g., FreeRTOS) or are programs that need to be installed in order work with the repository (e.g., Python).

The following sections list these dependencies, describes how to update them and includes a maintenance plan to keep dependencies up-to-date.

7.1. Internal Dependencies

Internal dependencies referr to dependencies where the dependency (i.e., some files) is actually commited to the repository, not just a configuration file.

  • FreeRTOS kernel: src/os/freertos/freertos

  • FreeRTOS-Plus-TCP: src/os/freertos/freertos-plus/freertos-plus-tcp

  • Waf: tools/waf

7.2. External Dependencies

Dependencies that are installed locally on the developer’s machine.

  • Doxygen

  • drawio-desktop

  • mingw-w64

  • Git

  • Graphviz

  • pre-commit hooks: defined through .pre-commit-config.yaml.

  • Python

  • Python packages: defined through requirements.txt.

  • Ruby

  • Ruby gems

  • TI Code Composer Studio

  • TI HALCoGen

  • VS Code

7.3. Management Plan

  • All dependencies SHALL be updated at the end of every quarter by the Dependency Update Responsible.

  • The Dependency Update Responsible SHOULD be changed in every update cycle, so that all team members know how to update the dependencies.

  • Every update cycle SHALL have a ticket that follows the naming conventions Dependency update: <XXXX>/Q<Y>, where <XXXX> is the year <Y> the quarter. Use .gitlab/issue_templates/issue-dependency-update.md as template for the issue.

  • After closing the ticket for the current update cycle, the ticket for the new update cycle SHALL be opened.

  • If a dependency can not be updated, it shall be document in the ticketing system for the next update cycle why a dependency has not been updated.

  • Every dependency SHALL be updated in a separate commit. Use .gitlab/merge_request_templates/mr-dependency-update.md as template for the merge request. The commit message (i.e., the merge request title) SHALL be Dependency update: <XXXX>/Q<Y>: <Dependency name> <version number>.

Note

Check that the following documentation sources are aligned:

  • .gitlab/issue_templates/issue-dependency-update.md,

  • .gitlab/merge_request_templates/mr-dependency-update.md

  • INSTALL.md,

  • docs/getting-started/software-installation.rst and the files linked in it, and

  • docs/general/license.rst and the files linked in it.

7.4. How to Update the Individual Dependencies

7.4.1. Updating Internal Dependencies

7.4.1.1. FreeRTOS kernel

  • Verify that the license of the latest release is aligned with our licensing policy. If not, open a ticket to discuss with the team members on how to proceed with that dependency (finding a replacement etc.), otherwise start the update process.

  • Download the latest release from https://github.com/FreeRTOS/FreeRTOS-Kernel/releases.

  • Replace src/os/freertos/freertos with the new version.

  • Verify the changes in src/os/freertos/freertos/portable against the foxBMS 2 specific changes.

  • Update the relevant license information in in docs/general/license-tables/internal/license-info_freertos-kernel.csv.

  • Add a changelog entry. If updating the dependency required other changes than the dependency itself, document this in this changelog entry..

  • Add the changes and commit the changes using the following commit message Dependency update: <XXXX>/Q<Y>: FreeRTOS kernel <version number>.

7.4.1.2. FreeRTOS-Plus-TCP

  • Verify that the license of the latest release is aligned with our licensing policy. If not, open a ticket to discuss with the team members on how to proceed with that dependency (finding a replacement etc.), otherwise start the update process.

  • Download the latest release from https://github.com/FreeRTOS/FreeRTOS-Plus-TCP/releases/.

  • Replace src/os/freertos/freertos-plus/freertos-plus-tcp with the new version.

  • Update the relevant license information in in docs/general/license-tables/internal/license-info_freertos-plus-tcp.csv.

  • Add a changelog entry. If updating the dependency required other changes than the dependency itself, document this in this changelog entry..

  • Add the changes and commit the changes using the following commit message Dependency update: <XXXX>/Q<Y>: FreeRTOS-Plus-TCP Library <version number>.

7.4.1.3. Waf

  • Verify that the license of the latest release is aligned with our licensing policy. If not, open a ticket to discuss with the team members on how to proceed with that dependency (finding a replacement etc.), otherwise start the update process.

  • Download the latest release from https://waf.io/.

  • Replace tools/waf with the new version.

  • Update the relevant license information in docs/general/license-tables/internal/license-info_waf.csv.

  • Add a changelog entry. If updating the dependency required other changes than the dependency itself, document this in this changelog entry..

  • Add the changes and commit the changes using the following commit message Dependency update: <XXXX>/Q<Y>: Waf <version number>.

7.4.2. Updating External Dependencies

7.4.2.1. Doxygen

  • Verify that the license of the latest release is aligned with our licensing policy. If not, open a ticket to discuss with the team members on how to proceed with that dependency (finding a replacement etc.), otherwise start the update process.

  • Download the latest release from https://doxygen.nl.

  • Install the latest release of Doxygen.

  • Update the installation instructions in docs/getting-started/software-installation.rst and INSTALL.md for Doxygen.

  • Update the Doxygen entry in conf/env/paths_win32.txt and conf/env/paths_linux.txt

  • Update the relevant license information in in docs/general/license-tables/external/license-info_doxygen.csv.

  • Add a changelog entry. If updating the dependency required other changes than the dependency itself, document this in this changelog entry..

  • Add the changes and commit the changes using the following commit message Dependency update: <XXXX>/Q<Y>: Doxygen <version number>.

7.4.2.2. drawio-desktop

  • Verify that the license of the latest release is aligned with our licensing policy. If not, open a ticket to discuss with the team members on how to proceed with that dependency (finding a replacement etc.), otherwise start the update process.

  • Download the latest release from https://github.com/jgraph/drawio-desktop/releases.

  • Install the latest release of drawio-desktop.

  • Update the installation instructions in docs/getting-started/software-installation.rst and INSTALL.md for https://github.com/jgraph/drawio-desktop/releases.

  • Update the drawio-desktop entry in conf/env/paths_win32.txt and conf/env/paths_linux.txt

  • Update the relevant license information in in docs/general/license-tables/external/license-info_drawio-desktop.csv.

  • Add a changelog entry. If updating the dependency required other changes than the dependency itself, document this in this changelog entry..

  • Add the changes and commit the changes using the following commit message Dependency update: <XXXX>/Q<Y>: drawio-desktop <version number>.

7.4.2.3. mingw-w64

  • Verify that the license of the latest release is aligned with our licensing policy. If not, open a ticket to discuss with the team members on how to proceed with that dependency (finding a replacement etc.), otherwise start the update process.

  • This section of the documentation is not yet complete.

  • Install the latest release of mingw-w64.

  • Update the installation instructions in docs/getting-started/software-installation.rst and INSTALL.md for mingw-w64.

  • Update the mingw-w64 entry in conf/env/paths_win32.txt and conf/env/paths_linux.txt

  • Update the relevant license information in in docs/general/license-tables/external/license-info_mingw-w64.csv.

  • Add a changelog entry. If updating the dependency required other changes than the dependency itself, document this in this changelog entry..

  • Add the changes and commit the changes using the following commit message Dependency update: <XXXX>/Q<Y>: mingw-w64 <version number>.

7.4.2.4. pre-commit Hooks

  • For every hook defined in .pre-commit-config.yaml: Verify that the license of the latest release is aligned with our licensing policy. If not, open a ticket to discuss with the team members on how to proceed with that dependency (finding a replacement etc.), otherwise start the update process.

  • For every hook that can be updated run

    .\fox.ps1 run-program pre-commit autoupdate https://path-to-repo

  • Update the relevant license information in in docs/general/license-tables/external/license-info_pre-commit-hooks.csv.

  • Add a changelog entry. If updating the dependency required other changes than the dependency itself, document this in this changelog entry..

  • Add the changes and commit the changes using the following commit message Dependency update: <XXXX>/Q<Y>: pre-commit Hooks <newline><comma-separated-list-of-hook-names-including-version-number>.

7.4.2.5. Python

  • Verify that the license of the latest release is aligned with our licensing policy. If not, open a ticket to discuss with the team members on how to proceed with that dependency (finding a replacement etc.), otherwise start the update process.

  • Download the latest release from https://www.python.org.

  • Install the latest release of Python.

  • Update the installation instructions in docs/getting-started/software-installation.rst and INSTALL.md for Python.

  • Create a new Python environment based on this Python version.

  • Update the relevant license information in in docs/general/license-tables/license-info_python.csv.

  • Add a changelog entry. If updating the dependency required other changes than the dependency itself, document this in this changelog entry..

  • Add the changes and commit the changes using the following commit message Dependency update: <XXXX>/Q<Y>: Python <version number>.

7.4.2.6. Python Packages

  • Chose a name for the environment.

  • Retrieve the list of outdated packages

    # Create the new environment
py -m venv C:\foxbms\envs\<name-of-the-new-env>
# Activate the new virtual environment by running
C:\foxbms\envs\<name-of-the-new-env>\Scripts\activate.ps1
# Determine outdated packages
.\fox.ps1 run-program python -m pip list --outdated

  • Install the required packages in the environment using python -m pip install ...

  • Run python -m pip freeze > requirements.txt

  • Verify that the license of the each latest release is aligned with our licensing policy.

    • If a package is not, open a ticket to discuss with the team members on how to proceed with that dependency (finding a replacement etc.)

    • If so, the update process of that hook can be started.

  • Update the installation instructions in docs/getting-started/software-installation.rst and INSTALL.md for the virtual Python environment.

  • Add the new environment name in docs/software/build-environment/build-environment.rst.

  • Update the relevant license information in in docs/general/license-tables/external/license-info_python-packages.csv.

  • Add a changelog entry. If updating the dependency required other changes than the dependency itself, document this in this changelog entry.. The changelog entry SHALL inform the user that environment update is mandatory.

  • Add the changes and commit the changes using the following commit message Dependency update: <XXXX>/Q<Y>: Python packages <newline><comma-separated-list-of-package-names-including-version-number>.

7.4.2.7. Ruby

  • Verify that the license of the latest release is aligned with our licensing policy. If not, open a ticket to discuss with the team members on how to proceed with that dependency (finding a replacement etc.), otherwise start the update process.

  • Download the latest release from https://rubyinstaller.org/downloads/.

  • Use the default installation directory.

  • Update the installation instructions in docs/getting-started/software-installation.rst and INSTALL.md for Ruby.

  • Update the Ruby entry in conf/env/paths_win32.txt and conf/env/paths_linux.txt.

  • Update the relevant license information in in docs/general/license-tables/license-info_ruby.csv.

  • Update the relevant license information in in docs/general/license-tables/license-info_ruby-installer.csv.

  • Add a changelog entry. If updating the dependency required other changes than the dependency itself, document this in this changelog entry.

  • Add the changes and commit the changes using the following commit message Dependency update: <XXXX>/Q<Y>: Ruby <version number>.

7.4.2.8. Ruby gems

  • Verify that the license of the latest release is aligned with our licensing policy. If not, open a ticket to discuss with the team members on how to proceed with that dependency (finding a replacement etc.), otherwise start the update process.

  • Install the latest Ceedling release into the version-specific directory:
    C:\foxbms\Ruby\Ruby34-x64\bin\gem.cmd install --install-dir C:\foxbms\Ceedling\<version> ceedling

  • Update the installation instructions in docs/getting-started/software-installation.rst and INSTALL.md for the Ruby gems.

  • Update the Ceedling entry in conf/env/paths_win32.txt and conf/env/paths_linux.txt

  • Update the GEM_HOME entry in conf/env/env.json.

  • Update the relevant license information in in docs/general/license-tables/external/license-info_ruby-gems.csv.

  • Add a changelog entry. If updating the dependency required other changes than the dependency itself, document this in this changelog entry..

  • Add the changes and commit the changes using the following commit message Dependency update: <XXXX>/Q<Y>: Ceedling <version number>.

7.4.2.9. TI Code Composer Studio

  • Verify that the license of the latest release is aligned with our licensing policy. If not, open a ticket to discuss with the team members on how to proceed with that dependency (finding a replacement etc.), otherwise start the update process.

  • Download the latest release from https://www.ti.com/tool/CCSTUDIO#downloads.

  • Install the latest release of TI Code Composer Studio.

  • Update the installation instructions in docs/getting-started/software-installation.rst and INSTALL.md for TI Code Composer Studio.

  • Update the TI Code Composer Studio entry in conf/env/paths_win32.txt and conf/env/paths_linux.txt

  • Update the relevant license information in in docs/general/license-tables/license-info_ti-code-composer-studio.csv.

  • Add a changelog entry. If updating the dependency required other changes than the dependency itself, document this in this changelog entry.

  • Add the changes and commit the changes using the following commit message Dependency update: <XXXX>/Q<Y>: Texas Instruments Code Composer Studio <version number>.

7.4.2.10. TI HALCoGen

  • Verify that the license of the latest release is aligned with our licensing policy. If not, open a ticket to discuss with the team members on how to proceed with that dependency (finding a replacement etc.), otherwise start the update process.

  • Download the latest release from https://www.ti.com/tool/HALCOGEN.

  • Install the latest release of TI HALCoGen.

  • Update the installation instructions in docs/getting-started/software-installation.rst and INSTALL.md for TI HALCoGen.

  • Update the TI HALCoGen entry in conf/env/paths_win32.txt.

  • Update the relevant license information in in docs/general/license-tables/external/license-info_ti-halcogen.csv.

  • Add a changelog entry. If updating the dependency required other changes than the dependency itself, document this in this changelog entry..

  • Add the changes and commit the changes using the following commit message Dependency update: <XXXX>/Q<Y>: Texas Instruments HALCoGen <version number>.