Skip to content

Latest commit

 

History

History
148 lines (110 loc) · 7.62 KB

DEVELOPERS-GUIDE.md

File metadata and controls

148 lines (110 loc) · 7.62 KB
Raw

DAPLink Developers Guide

Setup

DAPLink sources are compiled using progen (from project-generator) which can be run on Linux, MacOS and Windows.

Install the necessary tools listed below. Skip any step where a compatible tool already exists.

  • Install Python 3 . Add to PATH.
  • Install Git . Add to PATH.
  • Install a compiler:
    • GNU Arm Embedded Toolchain . This compiler will be identified as gcc_arm. It is recommended to use version 10.3-2021.10. Versions 11.3 and later of GCC (Arm GNU Toolchain / arm-none-eabi-gcc) are known to require some changes to build (see #1043).
    • Arm Compiler 6 . This compiler will be identified as armclang. Only supported on Linux and Windows.
    • Keil MDK or Arm Compiler 5. This compiler will be identified as armcc. Only supported on Linux and Windows.
  • Install make (tested with GNU Make). CMake can alternatively be used in conjunction with different implementations of make as well as ninja.
  • Install virtualenv in your global Python installation eg: pip install virtualenv.

Step 1. Initial setup.

Get the sources and create a virtual environment

$ git clone https://github.com/mbedmicro/DAPLink
$ cd DAPLink
$ pip install virtualenv
$ virtualenv venv

Activate virtual environment

Step 2. Activate the virtual environment and update requirements. This is necessary when you open a new shell. This should be done every time you pull new changes

$ venv/Scripts/activate   (For Linux)
$ venv/Scripts/activate.bat   (For Windows)
(venv) $ pip install -r requirements.txt

Build

This should be done every time you pull new changes

There are two ways to build DAPLink. You can use the progen command-line tool from project-generator or the tools/progen_compile.py wrapper tool.

Step 3.1. Using progen_compile.py

(venv) $ python tools/progen_compile.py [-t <tool>] [--clean] [-v] [--parallel] [<project> [<project> ...]]
  • -t <tool>: choose the toolchain to build. The default is make_gcc_arm. Other options tested are make_gcc_arm, make_armclang, make_armcc, cmake_gcc_arm, cmake_armclang, cmake_armcc.
  • --clean: will clear existing compilation products and force recompilation of all files.
  • -v: will make compilation process more verbose (typically listing all commands with their arguments)
  • --parallel: enable parallel compilation within a project (projects are compiled sequentially).
  • <project>: target project to compile (e.g. stm32f103xb_bl, lpc11u35_if), if none is specified all (140 to 150) projects will be compiled.

Step 3.2. Using progen with make

The following command combines generation and compilation:

(venv) $ progen generate -t make_gcc_arm -p <project> -b

Alternatively one can separate those task:

(venv) $ progen generate -t make_gcc_arm -p <project>
(venv) $ make -C projectfiles/make_gcc_arm/<project> [<target>] [VERBOSE=1]

Where:

  • <project>: target project to compile (e.g. stm32f103xb_bl, lpc11u35_if).
  • <target>: build target, can be all, clean or help.
  • VERBOSE=1: display additional compilation information.

Step 3.3. Using progen with cmake

The following command combines generation and compilation:

(venv) $ progen generate -t cmake_gcc_arm -o generator=<generator> -p <project> -b
  • <generator>: use CMake generators among the following options:
    • make (Unix Makefiles)
    • mingw-make (MinGW Makefiles)
    • msys-make (MSYS Makefiles, untested)
    • ninja (Ninja)
    • nmake (NMake Makefiles)
  • <project>: target project to compile (e.g. stm32f103xb_bl, lpc11u35_if).

Step 3.4. Using progen for MDK compilation.

This command generates MDK project files under the projectfiles/uvision directory.

$ progen generate -t uvision

To only generate one specific project, use a command like this:

progen generate -f projects.yaml -p stm32f103xb_stm32f746zg_if -t uvision

These options to progen set the parameters:

  • -f for the input projects file
  • -p for the project name
  • -t to specify the IDE name

Contribute

We would love to have your changes! Pull requests should be made once a changeset is rebased onto main. See the contributing guide for detailed requirements and guidelines for contributions.

Port

There are three defined ways in which DAPLink can be extended. These are adding target support, adding board support and adding HIC support. Details on porting each of these can be found below.

Test

DAPLink has an extensive set of automated tests written in Python. They are used for regression testing, but you can use them to validate your DAPLink port. Details are here

An option to search for the daplink firmware build in uvision and mbedcli build folders. python test/run_test.py --project-tool make_gcc_arm ... or python test/run_test.py --project-tool uvision ....

Release

Release using progen_compile.py

  • Create a tag with the correct release version and push it to github
  • Clean the repo you will be building from by running 'git clean -xdf' followed by 'git reset --hard'
  • Run the progen_compile.py command with the following parameters (see above for the -t flag):
(venv) $ python tools/progen_compile.py [-t <tool>] --clean -v --parallel --release
  • All release deliverables will be created and stored in firmware_<version> (where <version> is the DAPLink version). Save this wherever your builds are stored.

Release using uvision

DAPLink contains scripts to automate most of the steps of building a release. In addition to building the release, these scripts also save relevant build information such as git SHA and python tool versions so the same build can be reproduced. The recommended steps for creating a release are below.

  • Create a tag with the correct release version and push it to github
  • Clean the repo you will be building from by running 'git clean -xdf' followed by 'git reset --hard'
  • Run the script build_release_uvision.bat to create all builds.
  • All release deliverables will be created and stored in 'uvision_release'. Save this wherever your builds are stored.

Note: A previous build can be reproduced by using the build_requirements.txt of that build. To do this add the additional argument build_requirements.txt when calling build_release_uvision.bat in step 2. This will install and build with the exact version of the python packages used to create that build.

MDK

If you want to use the MDK (uVision) IDE to work with the DAPLink code, you must launch it in the right environment. The project will fail to build otherwise. To launch uVision properly, use tools/launch_uvision.bat

This script can take arguments to override default virtual environment and python packages to be installed. For example tools\launch_uvision.bat other_env other_requirements.txt