diff --git a/README.md b/README.md index 6f0d356..eb9963d 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,15 @@ IRNAS template for a GitHub repository. It comes with a [Zephyr group](https://github.com/IRNAS/irnas-workflows-software/tree/main/workflow-templates/zephyr) of CI workflows for release automation. +The project's documentation can be found in the [doc/](./doc/README.md) folder. + ## Checklist ### General GitHub setup - [ ] Provide a concise and accurate description of your project in the GitHub "description" field. - [ ] Provide a concise and accurate description of your project in this `README.md` file, replace - the title. + the title. Make sure that you leave the link to the documentation there. - [ ] Ensure that your project follows [repository naming scheme]. ### Tooling @@ -21,9 +23,11 @@ of CI workflows for release automation. ### Zephyr specifics -- [ ] Select the version of NCS in the `west.yaml` file, check the below section for specifics. -- [ ] Provide repository setup instructions, use template in _Setup_ section below. Replace - ``, ``, and `` as appropriate for your project. +- [ ] Select the version of NCS in the `west.yaml` file, check the + [west.yml_usage document](./docs/development/west_yml_usage.md) for more information. +- [ ] Provide repository setup instructions, use the template in the + [Setup document](./docs/development/setup.md). Replace `` and `` as + appropriate for your project. ### GitHub Actions @@ -59,99 +63,16 @@ of CI workflows for release automation. [CodeChecker server]: https://github.com/IRNAS/irnas-codechecker-software?tab=readme-ov-file#creating-new-products---codechecker-integration-in-east -## Setup - -If you do not already have them you will need to: - -- [install west](https://docs.zephyrproject.org/3.6.0/develop/west/install.html) -- [install east](https://github.com/IRNAS/irnas-east-software) - -Then follow these steps: - -```shell -east init -m https://github.com/IRNAS/ -cd /project - -# Set up east globally (this only needs to be done once on each machine) -east install nrfutil-toolchain-manager -# Install toolchain for the version of NCS used in this project -east install toolchain - -# Run `west update` via east to set up west modules in the repository -east update - -# Create default VERSION files -make gen-version -``` - -### Setup `pre-commit` - -Turn on `pre-commit` tool by running `pre-commit install`. If you do not have it yet, follow -instructions [here](https://github.com/IRNAS/irnas-guidelines-docs/tree/main/tools/pre-commit). - -## Building and flashing - -To build the application firmware: - -```bash -cd app -east build -b -u -``` - -To flash the firmware: - -```bash -east flash -``` - -To view RTT logs: - -```bash -# Run in first terminal window -east util connect - -# Run in second, new terminal window -east util rtt -``` - -## west.yaml and name-allowlist - -The manifest file (`west.yaml`) that comes with this template by default only allows certain modules -from Nordic's `sdk-nrf` and `sdk-zephyr` repositories, while ignoring/blocking others. - -This means that a setup on the new machine and in CI is faster as the `east update` command does not -clone all modules from the mentioned repositories but only the ones that are needed. - -Manifest file only allows modules that are commonly used by IRNAS, however this can be easily -changed by uncommenting the required modules and running `east update`. - -**IMPORTANT:** Such improvements do not come with some tradeoffs, there are now two things that a -developer must take note of. - -### Compile time errors cause of blocked/missing headers - -If the application source code includes some headers from blocked/missing modules or if included -headers use blocked/missing modules you will get an error that will complain about missing header -files. In that case, you have to go to manifest file, find commented module, run `east update`, -return to the app folder, delete build folder and build again. - -### Updating `sdk-nrf` version - -Whenever you want to update the version of `sdk-nrf` (also know simply as `NCS`) you need to keep -one general thing in mind: you need to manually keep revisions of `sdk-nrf` and `sdk-zephyr` -projects, as well as their imports in sync. - -1. Open `west.yml` file in `sdk-nrf` repository ([link](https://github.com/nrfconnect/sdk-nrf)). - Make sure that you select correct tag from selection from top-left dropdown menu. -2. Check what repos are under `sdk-zepyhr` project's `name-allowlist`, those should match the repos - in `west.yaml` of your project (and this template), under `sdk-zepyhr` project's - `name-allowlist`. Most of the time they should be commented out, but depends. -3. Check what other repositories appear under `sdk-zepyhr` project as standalone projects, they - start appearing around line 100, after `NCS repositories` comment. This projects should match the - repos in `west.yaml` of your project (and this template), under `sdk-nrf` project's - `name-allowlist`. Most of the time they should be commented out, but again, this depends. - -When a new `sdk-nrf` version is released, some new repos as `NCS repositories` might appear or be -moved into `sdk-zephyr`. - -After any change to the `west.yaml` do not forget to run `east update`. +## Repository folder structure + +- `app` - The main application code, intended to be used in the production. +- `boards` - Board definitions files for custom boards. +- `doc` - Project and development documentation. +- `drivers` - Low-level drivers for peripherals. +- `dts` - Device tree bindings file. +- `samples` - Sample/example code, used either to demonstrate the use or functionality of smaller + parts of the main application code or used for some testing purposes. +- `scripts` - Various scripts used for development, testing, or automation. +- `subsys` - Subsystem and libraries used by the application and samples. +- `tests` - Firmware used exclusively for unit testing testing or integration testing purposes. +- `.github` - GitHub Actions workflows and other GitHub related files. diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000..770ec34 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,7 @@ +# Documentation + +This folder contains several different kinds of documentation: + +- [Development documents](./development/README.md) - Instructions on how to setup the development + environment, how to write unit tests, use test runner and generate release artifacts can be found + in the `development` folder. diff --git a/doc/development/README.md b/doc/development/README.md new file mode 100644 index 0000000..9485af9 --- /dev/null +++ b/doc/development/README.md @@ -0,0 +1,7 @@ +# Development documents + +- [Setup](./setup.md) - How to clone this repository to local machine and set up the development + environment. +- [West.yml usage](./west_yml_usage.md) - How to use `west.yml` file to manage dependencies. +- [Writing Unit tests](./unit_tests.md) - How to write unit tests for the firmware. +- [Using Twister](./twister.md) - How to use the Twister test runner. diff --git a/doc/development/setup.md b/doc/development/setup.md new file mode 100644 index 0000000..a313e7e --- /dev/null +++ b/doc/development/setup.md @@ -0,0 +1,30 @@ +# Development Setup + +If you do not already have them you will need to: + +- [install west](https://docs.zephyrproject.org/latest/develop/west/install.html) +- [install east](https://github.com/IRNAS/irnas-east-software) + +Then follow these steps: + +```shell +east init -m https://github.com/IRNAS/ +cd /project + +# Set up east globally (this only needs to be done once on each machine) +east install nrfutil-toolchain-manager +# Install toolchain for the version of NCS used in this project +east install toolchain + +# Run `west update` via east to set up west modules in the repository +east update + +# Create default VERSION files +make gen-version +``` + +## Setup `pre-commit` + +Turn on `pre-commit` tool by running `pre-commit install`. If you do not have it yet **or the +command did not succeed** follow instructions +[here](https://github.com/IRNAS/irnas-guidelines-docs/tree/main/tools/pre-commit). diff --git a/doc/development/twister.md b/doc/development/twister.md new file mode 100644 index 0000000..c8a8b9e --- /dev/null +++ b/doc/development/twister.md @@ -0,0 +1,93 @@ +# Twister + +Twister is a script that scans for the set of unit test applications in the git repository and +attempts to execute them. For listed boards, it can build the applications, run them, check if they +every successful and generate a report. + +Due to the number of features that it has it can take some time to figure out how to do something +that you want, see `east twister --extra-help` for the supported options. + +Also, see [Zephyr's documentation](https://docs.zephyrproject.org/latest/develop/test/twister.html) +for more info. + +## Simple example + +From the project's root directory run: + +```shell +east twister -p native_sim -T tests +``` + +Twister will detect all projects with `testcase.yaml` in their project root under `tests` directory +and execute them. + +To run the same thing on the target you need to provide more info to the Twister: + +```shell +east twister -T tests -p nrf52dk_nrf52832 --device-testing --device-serial /dev/ttyACM0 +``` + +Check the output for the results. + +## `twister-out` folder + +With every invocation of the `east twister` a `twister-out` folder is created. It contains all build +folders of the created projects, as well as the report files. + +Keep in mind, if you keep running `east twister` command and not deleting the `twister-out` folder, +then the command will rename it to `twister-out.X` (Where `X` is a unique ascending number, starting +with 1) before running the full build. + +## `testcase.yaml` file + +`testcase.yaml` file marks that a Twister should pick up the test folder and build it. Its content +defines for which platforms it should be built and tested. + +See [Test Cases] section for more info. + +[test cases]: https://docs.zephyrproject.org/latest/develop/test/twister.html#test-cases + +## Coverage report + +Twister supports creating coverage reports from test runs with `gcovr` tool. Adding extra flags to +the command invocation creates an html file (among others) which shows code coverage for each file. + +```shell +east twister -T tests -p native_sim --coverage --coverage-tool gcovr +``` + +Note that you might need to change `--coverage-basedir` or add new ones for your project. + +To open the coverage report in the browser: + +```shell +firefox twister-out/coverage/index.html +``` + +## Make commands + +`makefile` in the root of the project contains useful targets for running tests. + +To setup host machine for running tests (needed to be run only once): + +```shell +make install-dep +``` + +To run all tests with Twister: + +```shell +make test +``` + +To see unit test results: + +```shell +make test-report +``` + +To see code coverage report: + +```shell +make coverage-report +``` diff --git a/tests/README.md b/doc/development/unit_tests.md similarity index 63% rename from tests/README.md rename to doc/development/unit_tests.md index f2fdcb7..9daf1cc 100644 --- a/tests/README.md +++ b/doc/development/unit_tests.md @@ -80,6 +80,14 @@ CONFIG_DEBUG_OPTIMIZATIONS=y CONFIG_DEBUG_INFO=y ``` +You can also run the binary with `valgrind` to check for memory leaks: + +```shell +sudo apt install valgrind +apt-get install libc6-dbg:i386 +valgrind --leak-check=yes ./build/zephyr/zephyr.exe +``` + ### Running unit tests on the target To build and run it on the target: @@ -133,103 +141,8 @@ ZTEST(my_test_suite, simple_equality) See [zephyr/tests/ztest/base](https://github.com/zephyrproject-rtos/zephyr/tree/main/tests/ztest/base) -for some basic usecases of Ztest framework. +for some basic use cases of Ztest framework. [assertions]: https://docs.zephyrproject.org/latest/develop/test/ztest.html#assertions [creating a test suite]: https://docs.zephyrproject.org/latest/develop/test/ztest.html#creating-a-test-suite - -## Twister - -Twister is a script that scans for the set of unit test applications in the git repository and -attempts to execute them. For listed boards, it can build the applications, run them, check if they -every successful and generate a report. - -Due to the number of features that it has it can take some time to figure out how to do something -that you want, see east twister `--extra-help` for the supported options. - -Also, see [Zephyr's documentation](https://docs.zephyrproject.org/latest/develop/test/twister.html) -for more info. - -### Simple example - -From the project's root directory run: - -```shell -east twister -p native_sim -T tests -``` - -Twister will detect all projects with `testcase.yaml` in their project root under `tests` directory -and execute them. - -To run the same thing on the target you need to provide more info to the Twister: - -```shell -east twister -T tests -p nrf52dk_nrf52832 --device-testing --device-serial /dev/ttyACM0 -``` - -Check the output for the results. - -### `twister-out` folder - -With every invocation of the `east twister` a `twister-out` folder is created. It contains all build -folders of the created projects, as well as the report files. - -Keep in mind, if you keep running `east twister` command and not deleting the `twister-out` folder, -then the command will rename it to `twister-out.X` (Where `X` is a unique ascending number, starting -with 1) before running the full build. - -### `testcase.yaml` file - -`testcase.yaml` file marks that a Twister should pick up the test folder and build it. Its content -defines for which platforms it should be built and tested. - -See [Test Cases] section for more info. - -[test cases]: https://docs.zephyrproject.org/latest/develop/test/twister.html#test-cases - -### Coverage report - -Twister supports creating coverage reports from test runs with `gcovr` tool. Adding extra flags to -the command invocation creates a html file (among others) which shows code coverage for each file. - -```shell -east twister -T tests -p native_sim --coverage --coverage-tool gcovr -``` - -Note that you might need to change `--coverage-basedir` or add new ones for your project. - -To open the coverage report in the browser: - -```shell -firefox twister-out/coverage/index.html -``` - -## Make commands - -`makefile` in the root of the project contains useful targets for running tests. - -To setup host machine for running tests (needed to be run only once): - -```shell -make install-dep -make install-test-dep -``` - -To run all tests with Twister: - -```shell -make test -``` - -To see unit test results: - -```shell -make test-report -``` - -To see code coverage report: - -```shell -make coverage-report -``` diff --git a/doc/development/west_yml_usage.md b/doc/development/west_yml_usage.md new file mode 100644 index 0000000..5fc20a7 --- /dev/null +++ b/doc/development/west_yml_usage.md @@ -0,0 +1,43 @@ +# `west.yml` usage + +## `west.yaml` and `name-allowlist` + +The manifest file (`west.yaml`) that comes with this template by default only allows certain modules +from Nordic's `sdk-nrf` and `sdk-zephyr` repositories, while ignoring/blocking others. + +This means that a setup on the new machine and in CI is faster as the `east update` command does not +clone all modules from the mentioned repositories but only the ones that are needed. + +Manifest file only allows modules that are commonly used by IRNAS, however this can be easily +changed by uncommenting the required modules and running `east update`. + +**IMPORTANT:** Such improvements do not come without some trade-offs. There are now two things that +a developer must take note of. + +### Compile time errors cause of blocked/missing headers + +If the application source code includes some headers from blocked/missing modules or if included +headers use blocked/missing modules you will get an error that will complain about missing header +files. In that case, you have to go to manifest file, find commented module, run `east update`, +return to the app folder, delete build folder and build again. + +### Updating `sdk-nrf` version + +Whenever you want to update the version of `sdk-nrf` (also know simply as `NCS`) you need to keep +one general thing in mind: you need to manually keep revisions of `sdk-nrf` and `sdk-zephyr` +projects, as well as their imports in sync. + +1. Open `west.yml` file in `sdk-nrf` repository ([link](https://github.com/nrfconnect/sdk-nrf)). + Make sure that you select correct tag from selection from top-left drop-down menu. +2. Check what repos are under `sdk-zepyhr` project's `name-allowlist`, those should match the repos + in `west.yaml` of your project (and this template), under `sdk-zepyhr` project's + `name-allowlist`. Most of the time they should be commented out, but depends. +3. Check what other repositories appear under `sdk-zepyhr` project as standalone projects, they + start appearing around line 100, after `NCS repositories` comment. This projects should match the + repos in `west.yaml` of your project (and this template), under `sdk-nrf` project's + `name-allowlist`. Most of the time they should be commented out, but again, this depends. + +When a new `sdk-nrf` version is released, some new repos as `NCS repositories` might appear or be +moved into `sdk-zephyr`. + +After any change to the `west.yaml` do not forget to run `east update`.