MatterMatter environment construction reference document

Article directory

Matter Environment Build Reference Documentation
- Tested operating system
- Features of the build system
- Check Matter’s code
- Synchronization submodule
- prerequisites
- - 1. Install Prerequisites on Linux
  - - Construction of the user interface
  - 2. Install Prerequisites on macOS
  - - Construction of the user interface
  - 3. Install Prerequisites on Raspberry Pi 4
  - - Configure wpa_supplicant to store permanent changes
- Install the ZAP tool
- - 1. Linux ARM
  - 2. Which ZAP to use
- prepare for build
- - 1. Update the environment
- Build for the host OS (Linux or macOS)
- Use `build_examples.py`
- - 1. `libfuzzer` unit tests
  - - Configuration of `ossfuzz`
- Build a custom configuration
- build instance
- - 1. Build the example as a standalone project
  - 2. Create an instance at the top level
- Unity Build
- get help
- introspection
- coverage
- Maintenance

Matter Environment Construction Reference Document

Matter supports building with GN configuration, a fast and extensible meta-build system that generates input to ninja.

Tested Operating Systems

The build system has been tested on the following operating systems:

macOS 10.15
Debian 11 (64 bit required)
Ubuntu 22.04 LTS

Characteristics of the build system

The Matter build system has the following features:

Very fast and takes up little space
Cross-platform processing: Linux, Darwin, Embedded Arm, etc.
Multiple toolchains and cross-toolchain dependencies
Integrated with an automated testing framework: ninja check
Introspection: “gn desc”.
Automatic formatting: gn format.

Check Matter’s code

To check out the Matter repository, run the following command:

git clone --recurse-submodules [email protected]:project-chip/connectedhomeip.git

Synchronizing submodules

If you have checked out Matter’s code, run the following command to sync submodules:

git submodule update --init

Prerequisites

Before building, you must install some OS-specific dependencies.

1. Install prerequisites on Linux

On Debian-based Linux distributions, such as Ubuntu, these dependencies can be satisfied with the following command:

sudo apt-get install git gcc g++ pkg-config libssl-dev libdbus-1-dev\
     libglib2.0-dev libavahi-client-dev ninja-build python3-venv python3-dev
     python3-pip unzip libgirepository1.0-dev libcairo2-dev libreadline-dev

Construction of the user interface

If building via the build_examples.py and with-ui variants, also install SDL2:

sudo apt-get install libsdl2-dev

2. Install prerequisites on macOS

On macOS, install Xcode from the Mac App Store.

Construction of the user interface

If building the -with-ui variant, also install SDL2:

brew install sdl2

3. Install prerequisites on Raspberry Pi 4

Complete the following steps:

Usage: rpi-imager installs Ubuntu 22.04 64-bit server operating system for arm64 architecture on the micro SD card.
Boot SD card.
Log in with the default user account “ubuntu” and password “ubuntu”.
Proceed to Installing Prerequisites on Linux.
Install some Raspberry Pi specific dependencies:

sudo apt-get install pi-Bluetooth avahi-utils

After installing “pi-bluetooth”, reboot your Raspberry Pi.

Configure wpa_supplicant to store permanent changes

By default, wpa_supplicant is not allowed to update (overwrite) the configuration. If you want the Matter app to be able to store configuration changes, you need to make the following changes:

Edit the dbus-fi.w1.wpa_supplicant1.service file to use the configuration file instead, run the following command:

sudo nano /etc/systemd/system/bus-fi.w1.wpa_supplicant1.service

Run the following command to change the startup parameter of wpa_supplicant to the value provided:

ExecStart=/sbin/wpa_supplicant -u -s -i wlan0 -c /etc/wpa_supplicant/wpa_supplicant.conf

Add the wpa-supplicant configuration file by running the following command:

sudo nano /etc/wpa_supplicant/wpa_supplicant.conf

Add the following to the wpa-supplicant file:

ctrl_interface=DIR=/run/wpa_supplicant
update_config=1

Reboot your Raspberry Pi.

Install the ZAP tool

bootstrap.sh will download a compatible version of the ZAP tool and set it on $PATH. If you want to install or use a different version of the tool, you can download it from the ZAP project’s Release page.

1. Linux ARM

Zap does not provide binary releases for ARM. Rosetta solves this problem for Darwin. However, for linux arm, you must use the native ZAP, usually by setting $ZAP_DEVELOPMENT_PATH (see the Which ZAP to use section below) .

The file scripts/setup/zap.json contains the version that CIPD will download, so you can download a compatible version Release from the zap project. To check out code as source code, the corresponding tag should exist in the repository tags list in zap.

Command example:

RUN set -x \
     & amp; & amp; mkdir -p /opt/zap -${ZAP_VERSION} \
     & amp; & amp; git clone https://github.com/project-chip/zap.git /opt/zap-${ZAP_VERSION} \
     & amp; & amp; cd /opt/zap-${ZAP_VERSION} \
     & amp; & amp; git checkout ${ZAP_VERSION} \
     & amp; & amp; npm config set user 0 \
     & amp; & amp; npm ci
ENV ZAP_DEVELOPMENT_PATH=/opt/zap-${ZAP_VERSION}

2. Which ZAP to use

The ZAP tool script uses the following detections, in order of importance:

$ZAP_DEVELOPMENT_PATH points to a ZAP checkout.
If you develop ZAP locally and want to run ZAP with your changes.
$ZAP_INSTALL_PATH points to zap-linux.zip or `zap-m

Preparing for build

The scripts/activate.sh environment setup script should be at the top level before running any other build commands. This script is responsible for downloading GN, ninja, and setting up the libraries for building and testing in a Python environment to build and test.

Run the following command:

source scripts/activate.sh

1. Update environment

If the script says the environment is out of date, you can update it by running:

source scripts/bootstrap.sh

The script scripts/bootstrap.sh recreates the environment from scratch, which is expensive, so avoid running it unless the environment is out of date.

Build for the host OS (Linux or macOS)

Run the following command to build all sources, libraries and tests for the host platform:

source scripts/activate.sh

gn gen out/host

ninja -C out/host

These commands generate a configuration suitable for debugging. To configure a build, specify is_debug=false:

gn gen out/host --args='is_debug=false' .

ninja -C out/host

**Note:** The directory name “out/host” can be any directory, usually built under the out directory. This example uses host to emphasize building for the host system. Different build directories can be used for different configurations, or use one directory and reconfigure as needed via gn args if necessary.

To run all tests, run the following command:

ninja -C out/host check

To run only the tests in src/inet/tests, run the following command:

ninja -C out/host src/inet/tests:test_run

**NOTE:** The build system caches passing tests, so you may see the following message:
ninja: no work to do
This means the tests passed in the previous build.

Using `build_examples.py`

The script ./scripts/build/build_examples.py provides a unified compile and build interface, you can use gn, cmake, ninja and other necessary tools to compile for various platforms.

Use ./scripts/build/build_examples.py targets to see supported targets.

Examples of build commands:

# Compile and run all tests on the host:
./scripts/build/build_examples.py --target linux-x64-test build

# Compile fuzzing tags with libfuzzer (clang is required for fuzzing)
./scripts/build/build_examples.py --target linux-x64-test-clang-asan-libfuzzer build

# Compile an esp32 example
./scripts/build/build_examples.py --target esp32-m5stack-all-clusters build

# Compile an nrf example
./scripts/build/build_examples.py --target nrf-nrf5340dk-pump build

1. `libfuzzer`unit test

libfuzzer unit tests Tests are only compiled but not executed (you have to execute them manually). For best error detection some form of sanitizer should be used, eg asan should be used.

The following commands can be executed:

./scripts/build/build_examples.py --target linux-x64-test-lang-asan-libfuzzer build

After that, the tests should be located in out/linux-x64-tests-lang-asan-libfuzzer/tests/.

`ossfuzz`configuration

The ossfuzz configuration is not a stand-alone fuzzer, but serves as an integration point with an external fuzzer’s automated build. They get environment variables like $CFLAGS, $CXXFLAGS and $lib_fuzzing_engine.

You may need a build of libfuzzer + asan instead of testing locally.

Build custom configuration

Builds are configured by setting build parameters. You can set these parameters with:

Pass the --args option to gn gen.
Run gn args on the output directory.
Edit args.gn in the output directory.

To configure a new build or edit the parameters of an existing build, run the following command:

source scripts/activate.sh

gn args out/custom

ninja -C out/custom

Two key built-in build parameters are target_os and target_cpu, which control the OS and CPU of the build, respectively.

To see help for all available build parameters, run the following command:

gn gen out/custom
gn args --list out/custom

Construction example

You can build examples in two ways.

1. Build the example as a standalone project

To build the example as a separate project, in Matter’s third_party directory, run the following command, entering the correct path to the example’s correct path (in this case “chip-shell”):

cd examples/shell
gn gen out/debug
ninja -C out/debug

2. Create an instance at the top level

You can build examples on top of the Matter project. See the Unity Build section below for details.

Unity build

To build a unified configuration that approximates a continuous build set, run the following command:

source scripts/activate.sh

gn gen out/unified --args='is_debug=true target_os="all"'

ninja -C out/unified all

You can use this set of commands to build and test configurations for GCC, Clang, MbedTLS, and examples before changing commit configurations. in a parallel build. Each configuration has a separate subdirectory in the output directory.

This unified build can be used for day-to-day development, although it would be more expensive to build everything for every edit. The cost of building each editorial item. To save time, you can pass the configuration to the build:

ninja -C out/unified host_gcc
ninja -C out/unified check_host_gcc

Replace host_gcc with the name of your configuration, which can be found in “BUILD.gn” in the root directory.

You can also fine-tune the generated configuration with parameters. for example

gn gen out/unified --args='is_debug=true target_os="all" enable_host_clang_build=false'

See the root directory BUILD.gn for a complete list.

In a unity build, targets have multiple instances, which need to be differentiated by adding the (toolchain) suffix. Use gn ls out/debug to list all target instances. For example:

gn desc out/unified '//src/controller(//build/toolchain/host:linux_x64_clang)'

**NOTE:** Some platforms can be built as part of a unity build requiring additional tools to be downloaded. To add these tools to the build, their location must be
Must be provided as a build parameter. For example, to add the Simplelink cc13x2_26x2 example to the Unity build, install SysConfig and add the following to the build:
gn gen out/unified --args="target_os="all" enable_ti_simplelink_builds=true > ti_sysconfig_root="/path/to/sysconfig""

Get help

GN has integrated help, which you can access with the gn help command.

Make sure to check out the recommended topics below:

gn help execution
gn help syntax
gn help toolchain

Introspection

GN has various introspection tools to help you check your build configuration. The following example takes the out/host output directory as an example:

Display all targets in an output directory:
```
gn ls out/host
```
Show all files that will be built:
```
gn output out/host '*'
```
Display the GN representation of the configured target:
```
gn desc out/host //src/inet --all
```
Convert the GN representation of the entire build to JSON format:
```
gn desc out/host/ '*' --all --format=json
```

Show the dependency tree:

gn desc out/host //:all deps --tree --all

Find dependency paths:

gn path out/host //src/transport/tests:test //src/system

List useful information about connecting with `libCHIP’:

gn desc out/host //src/lib include_dirs
gn desc out/host //src/lib defines
gn desc out/host //src/lib outputs

# Everything is in JSON format
gn desc out/host //src/lib --format=json

Coverage

The code coverage script generates a report detailing how much Matter SDK source code was executed. It also provides information on how often the Matter SDK executes the code snippet and generates a copy of the source file, annotated with the frequency of execution.

Run the following command to start the script:

./scripts/build_coverage.sh

By default, code coverage scripts are executed at the unit test level. Unit tests are created by the developers, so that gives them the best idea of what tests to include in the unit tests. You can extend coverage tests by scope and execution using the following parameters:

 -c, --code Specifies the scope to collect coverage data.
                            core": Collect coverage data from the core stack of the Matter SDK. --default
                            clusters": Collect coverage data from the cluster implementation in the Matter SDK.
                            'all': Collect coverage data for the Matter SDK.
  -t, --tests Specify which tools to run coverage checks on.
                            'unit': Run unit tests to drive coverage checks. --default
                            'yaml': Run yaml tests to drive coverage checks.
                            'all': Run unit and yaml tests to drive coverage checks.

Also, see the Matter SDK’s latest unit test coverage report (collected daily): matter coverage.

Maintenance matters

If you make any changes to the GN build system, the next build will automatically regenerate the ninja files. No need to do anything.

Article directory

Matter Environment Construction Reference Document

Tested Operating Systems

Characteristics of the build system

Check Matter’s code

Synchronizing submodules

Prerequisites

1. Install prerequisites on Linux

Construction of the user interface

2. Install prerequisites on macOS

Construction of the user interface

3. Install prerequisites on Raspberry Pi 4

Configure wpa_supplicant to store permanent changes

Install the ZAP tool

1. Linux ARM

2. Which ZAP to use

Preparing for build

1. Update environment

Build for the host OS (Linux or macOS)

Using build_examples.py

1. libfuzzerunit test

ossfuzzconfiguration

Build custom configuration

Construction example

1. Build the example as a standalone project

2. Create an instance at the top level

Unity build

Get help

Introspection

Coverage

Maintenance matters

Using `build_examples.py`

1. `libfuzzer`unit test

`ossfuzz`configuration