mirror/MuditaOS
1
0
Fork 0
mirror of https://github.com/mudita/MuditaOS.git synced 2026-04-21 15:38:23 -04:00
Code Issues Packages Projects Releases Wiki Activity
Files
29ba767ef5d9c42c8cc2b2c5f8c799a75ef3fe84
MuditaOS/doc/quickstart.md
Bartosz Cichocki 4ace345471 [EGD-7826] Update quickstart readme 
Updated readme to contain product-specific buiild options
2021-11-10 09:38:09 +01:00

291 lines
13 KiB
Markdown
Raw Blame History

# Quickstart
You can quickstart the project by going through one of the following guides:
- [Introduction](#introduction)
- [CMake options](#CMake-options)
- [Quickstart on Linux](#quickstart-on-linux)
- [Quickstart with unit tests](#quickstart-with-unit-tests)
- [Quickstart on the phone](#quickstart-on-the-phone)
- [More details on preparing your local environment](#more-details-on-preparing-your-local-environment)
- [CI build using Docker](#ci-build-using-docker)
- [Building your own Docker image](#building-your-own-docker-image)
- [Preparing packages](#preparing-packages)
## Introduction
Run the provisioning script `./config/bootstrap.sh` to install all dependencies. The script is written for Ubuntu and tested on 20.04.
To run the script execute the following command: `cd config && ./bootstrap.sh 0-`
Note that this downloads a shellscript from `get.docker.com` and runs it with sudo for Docker installation.
This script also installs few required packages (`cat config/bootstrap_config`) which also require root privileges.
Installation of `GCCv10` and `CMake` is done to `$HOME` directory.
Running the script without parameters will display a list of steps.
After running provisioning you are ready to checkout and build project for both linux and RT1051. Please follow these steps:
1. Check out the project with submodules for the first time:
```bash
git submodule update --init --recursive
```
2. Update the repository with submodules
```bash
git pull --recurse-submodules
```
3. Build the project for proper product:
```bash
./configure.sh [PurePhone|BellHybrid] [rt1051|linux] [release|debug|relwithdebinfo]
cd build-[PurePhone|BellHybrid]-[rt1051|linux]-[release|debug|relwithdebinfo]
make
```
### CMake options
Before configuring the project with `./configure.sh` you can tune it by enabling/disabling options to suite your needs.
This can be done manually, by editing the `.cmake` files (not recommended though) or by CLI/GUI tool like `ccmake`.
| Option | Description | Default value |
| ------------------------------|:-------------------------------------------------------------------------:|:-------------:|
| `COVERAGE_ENABLE` | Enable code coverage report generation | OFF |
| `COLOR_OUTPUT` | Use colored output in RTT logs and compiler diagnostics | ON |
| `SYSTEMVIEW` | Enable usage of Segger's SystemView | OFF |
| `USBCDC_ECHO` | Enable echoing through USB-CDC | OFF |
| `MUDITA_USB_ID` | Enable using Mudita registered USB Vendor ID and Pure Phone USB Product ID| OFF |
| `ENABLE_APP_X` | Build and enable application X | ON |
| `OPTIMIZE_APP_X` | Optimize application X in debug build | ON |
| `LINUX_ENABLE_SANITIZER` | Enable address sanitizer for Linux | ON |
| `ENABLE_SECURE_BOOT` | Build signed binary for Secure Boot | OFF |
| `THIRD_PARTY_DEBUG_OPTIMIZE` | Optimize third party in debug | ON |
| `ENABLE_TEST_LOGS` | Enable logs in unit tests | OFF |
| `GENERATE_STACK_USAGE` | Generate stack usage report | OFF |
| `BUILD_DOC_WITH_ALL` | Build documentation with `all` target | OFF |
By using `ENABLE_APP_X` (where `X` is the name of the application) you can enable/disable any application.
### Quickstart on Linux
Here's the bare minimum that will enable you to bootstrap the environment on Linux.
```bash
git submodule update --init --recursive # initialize submodules
cd ./config/ && ./bootstrap.sh 0- && cd ../ # bootstrap requirements
./configure.sh PurePhone|BellHybrid rt1051|linux Debug|Release|RelWithDebInfo # configure build
cd <build-dir> # build dir depends on configuration
make Pure # build
./PurePhone.elf # run PurePhone - simulator screen will pop up (on the Linux filesystem)
```
If you want to run the simulator with image and our VFS implementation
you need to run the image through the script:
```bash
./run_simulator_on_filesystem_image.sh
```
### Quickstart with unit tests
After going through the Super dirty quickstart on Linux, run the following commands to build and run all unit tests:
```bash
./configure.sh PurePhone|BellHybrid linux debug
cd <build-dir>
make check
```
### Quickstart on the phone
1. First install J-Link driver. We suggest using J-Link driver in version J-Link v634f ([Ubuntu download](https://www.segger.com/downloads/jlink/JLink_Linux_V634f_x86_64.deb))
2. Please run the following commands:
```bash
cp ./env.cmake.sample ./env.cmake && sed -i "s:<HOME>:$HOME:" env.cmake
git submodule update --init --recursive
cd ./config/ && ./bootstrap.sh 0- && cd ../
./configure.sh PurePhone|BellHybrid rt1051 RelWithDebInfo
cd build-PurePhone|BellHybrid-rt1051-RelWithDebInfo
make Pure
```
3. Please take the following steps in three parallel consoles/sessions:
- Start J-Link server: `./StartJLinkServer.sh`
- Load app with GDB via J-Link connected to Mudita Pure: `./run.sh <build folder> --product PurePhone`
- Catch logs from Mudita Pure from J-Link RTT and write them to `/tmp/log.txt`: `JLinkRTTClient | tee /tmp/log.txt`
#### Catching logs using UART
If you want to catch logs from Mudita Pure from UART please follow these steps:
1. In `config/ProjectConfig.cmake` change `RTT_JLINK` to `RTT_LUART`
2. Rebuild the project
3. Catch logs: `picocom /dev/ttyACM0 -b 115200 --imap lfcrlf`
Please mind that logs on UART are more costly, so these might cause timing issues and slow down the phone too. To avoid that consider `release` build for tests with `uart` enabled.
## More details on preparing your local environment
The quickest way to set up your environment is running the following command:
```bash
cd config && ./bootstrap.sh 0-
```
The script is written for Ubuntu and tested on 20.04.
* This script will require `sudo` (for `apt`)
* It will install `cmake` and `gcc` by default in `${HOME}` directory - in case of other needs, please change the script
* The script doesn't install `ccache`, but if `ccache` is on the system - its support is added to `env.cmake.sample`
* The script needs to be run only once
If the script is run after a fresh `git clone` you need to update your git config (step 0 and 1).
### `bootstrap.sh` steps, line by line
* `./config/bootstrap.sh 0` - install style checking scripts to be automatically run on commit
* `./config/bootstrap.sh 1` - `git blame` will ignore style changing commit
* `./config/bootstrap.sh 2` - list packages required for setting up the environment *which are currently not installed*
* `./config/bootstrap.sh 3` - set up arm toolchain, download and install it in home directory
* `./config/bootstrap.sh 4` - set up `cmake`, download and install in home directory
* `./config/bootstrap.sh 5` - list of commands required for switching default gcc/g++ to version 9
* `./config/bootstrap.sh 6` - add paths for arm toolchain to your `PATH` environment variable - this is also used by `./env.cmake` *(this is required because `./env.cmake` uses environment variables set by this target)*
* `./config/bootstrap.sh 7` - add paths for `cmake` to your `PATH` environment variable
* `./config/bootstrap.sh 8` - install Docker
### Code style with git hooks
The `bootstrap.sh` script installs git hooks for code style checking. `pre-commit.hook`automatically updates style during commit. If you haven't run `bootstrap.sh` and want to use git hooks, you have to copy (or link) `pre-commit.hook` to your git config directory `.git/config/hooks`: `ln -s `pwd`/config/pre-commit.hook .git/hooks/pre-commit`
By default commit hook only checks if your changes have the appropriate style, if you would like to fix the style automatically during `git commit` you have to configure your git, by adding new variable `user.fixinstage` and setting it to `true` by running
`git config user.fixinstage true`
If you prefer "notification than fix" workflow (so you can examine the changes), use the default hook behaviour (for notifications) and then call `./config/pre-commit.hook --fix`, this checks and fixes files in "stage", files that have status "changed" are not tested.
```bash
git commit
<stele error - commit aborted>
./config/pre-commit.hook --fix
git diff
git add -u
git commit
<commit accepted>
```
To fix the style for Pull Request CI:
`./config/pre-commit.hook --branch-fix`
### Commit message template
To add a commit message template use this command:
```bash
git config commit.template .gitmessage
```
This way each time you add a new commit you will see the template that will help
you with the proper message format. More about that in (Development Workflow)[./doc/development_workflow.md#commit-changes]
### Commit message hook
This hooks automatically converts your branch name to commit title
rules:
if branch starts with EGD-xxxx it is treated as jira ticket
all `-` and `_` are converted to spaces
#### Adding a hook:
```bash
cd .git/hooks
ln -s ../../config/prepare-commit-msg
```
#### Using a hook:
Create a branch
```bash
git checkout origin/master -b EGD-1234-Add_change_description
```
Do your changes, and prepare commit
```bash
git commit
```
## CI build using Docker
You can build MuditaOS using a Docker container. To do that, follow these steps
1. Get Docker by running `./config/bootstrap.sh 8` or [install it yourself](https://www.docker.com/get-started) (if was not installed previously with `./config/bootstrap.sh 0-`).
After that you have to log out and log back in as groups are set during the login process. To make sure you are in docker group enter the `groups` command and
you will see the list of groups your user is assigned to.
2. Configure for Linux Debug:
```bash
./in_docker.sh config PurePhone|BellHybrid linux Debug
```
3. Build linux Debug:
```bash
./in_docker.sh make build-PurePhone|BellHybrid-linux-Debug
```
4. Build RT1051 Release
```bash
./in_docker.sh config PurePhone|BellHybrid rt1051 Release
./in_docker.sh make build-PurePhone|BellHybrid-rt1051-Release
```
5. Build and run tests (Linux only)
```bash
./in_docker.sh make build-PurePhone|BellHybrid-linux-Debug
./in_docker.sh make build-PurePhone|BellHybrid-linux-Debug check
```
To build selected test manually in the working directory of attached Docker image run:
```bash
cd ./build-PurePhone|BellHybrid-linux-Debug ; make <test_name>; ./<test_name>
```
i.e.:
```bash
cd ./build-PurePhone|BellHybrid-linux-Debug ; make unittest_gui && ./unittest_gui
```
Running tests checks memory leaks too - this might be helpful in creation of new widgets.
### Building your own Docker image
If for some reason (f.ex. testing new dependencies) you need to create your own docker image, you can do it by following:
1. Configure Docker file and download the necessary tool chain packages:
```bash
./config/build_runner_docker
```
2. Build a new Docker image
```bash
docker build docker -f docker/Dockerfile -t "wearemudita/mudita_os_builder:latest"
```
Please be aware that when building custom image you'll have to give it some tag (default from `build_runner_docker` is `latest`). You also need to provide some scripts with your tag (like `CONTAINER_TAG` in `in_docker.sh`), otherwise Docker will download and use original image from Mudita.
## Preparing packages
If you need a package, containing everything needed to run the application, please check (build_targests.md)[./doc/build_targests.md] document.
## Generating code coverage reports
To generate code coverage reports for unit tests, you have to configure the project
with `COVERAGE_ENABLE=ON`. Please note, that code coverage report generation
works for the Linux/Debug configuration only.
Code coverage reports are generated with the `gcovr` application. You can
install it with:
```
pip3 install gcovr
```
Following targets related to coverage report generation are available:
* `coverage-all-html` - run `ctest` and generate a detailed HTML report.
* `coverage-html` - generate detailed HTML report based on the data collected during last execution of a unit test. The report
will be generated in the `coverage-html` subdirectory of a build directory.
* `coverage` - same as above, but generate an XML Cobertura report instead of an HTML.
Reference in New Issue View Git Blame Copy Permalink