From 66415929584a3f3a7d3fe87ed8eae0e0e96596b7 Mon Sep 17 00:00:00 2001 From: "Wiktor S. Ovalle Correa" Date: Thu, 17 Dec 2020 18:04:31 +0100 Subject: [PATCH] [EGD-4712] Change quickstart.md to reflect current project state Quickstart documentation was a bit out-of-date, thus containing some minor inaccuracies. Also document didn't actually reflect desired sequence of user actions. --- doc/quickstart.md | 214 ++++++++++++++++++++++++---------------------- 1 file changed, 111 insertions(+), 103 deletions(-) diff --git a/doc/quickstart.md b/doc/quickstart.md index f10589afa51f36719a0ec289d952f1fe808b6cde..e22feae3f0a715acae175ca7d813a65ff99e8c59 100644 --- a/doc/quickstart.md +++ b/doc/quickstart.md @@ -2,76 +2,108 @@ You can quickstart the project by going through one of the following guides: -- [Quickstart using Docker](#quickstart-using-docker) +- [Introduction](#introduction) +- [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) -- [Quickstart in your local environment](#quickstart-in-your-local-environment) -- [Longstart](#longstart) -- [Super dirty quickstart on Linux](#super-dirty-quickstart-on-linux) -- [Super dirty quickstart with unit tests](#super-dirty-quickstart-with-unit-tests) -- [Super dirty quickstart on the phone](#super-dirty-quickstart-on-the-phone) - [Preparing packages](#preparing-packages) +## Introduction -## Quickstart using Docker -You can build MuditaOS using a Docker container. To do that, follow these steps +Run the provisioning script `./config/bootstrap.sh` to install all dependencies. The script is written for Ubuntu and tested on 20.04. -1. Get Docker by running `./config/bootstrap.sh 8` or [install it yourself](https://www.docker.com/get-started). +To run the script execute the following command: `cd config && ./bootstrap.sh 0-` -2. Add yourself to a `docker` group: +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 -NAME=$(whoami) -sudo usermod -aG docker ${NAME} +git submodule update --init --recursive ``` -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. - -3. Configure for Linux Debug: `./in_docker.sh config linux Debug` - -4. Build linux Debug: `./in_docker.sh make build-linux-Debug` +2. Update the repository with submodules -5. Build RT1051 Release ```bash -./in_docker.sh config rt1051 Release -./in_docker.sh make build-rt1051-Release +git pull --recurse-submodules ``` -6. Build and run tests (Linux only) +3. Build the project ```bash -./in_docker.sh make build-linux-Debug -./in_docker.sh make check +./configure.sh [rt1051|linux] [release|debug|relwithdebinfo] +cd build-[rt1051|linux]-[release|debug|relwithdebinfo] +make ``` -To build selected test manually in the working directory of attached Docker image run: + +### Quickstart on Linux + +Here's the bare minimum that will enable you to bootstrap the environment on Linux. + ```bash -cd ./build-linux-Debug ; make ; ./ +git submodule update --init --recursive # initialize submodules +cd ./config/ && ./bootstrap.sh 0- && cd ../ # bootstrap requirements +./configure.sh rt1051|linux Debug|Release|RelWithDebInfo # configure build +cd # build dir depends on configuration +make -j # build +./PurePhone # run PurePhone - emulator screen will pop up (on the Linux filesystem) ``` -i.e.: + +If you want to run the emulator with image and our VFS implementation +you need to run the image through the script: ```bash -cd ./build-linux-Debug ; make unittest_gui && ./unittest_gui +./run_emulator_on_filesystem_image.sh ``` -Running tests checks memory leaks too - this might be helpful in creation of new widgets. -## Building your own Docker image +### Quickstart with unit tests -If for some reason you don't want to use [the existing Docker image](docker push wearemudita/mudita_os_builder:latest) you can build your own by following - -1. Configure Docker file and download the necessary tool chain packages: +After going through the Super dirty quickstart on Linux, run the following commands to build and run all unit tests: ```bash -./config/build_docker_runner +./configure.sh linux debug +cd +make check ``` +### Quickstart on the phone -2. Build a new Docker image +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 -docker build docker -f docker/Dockerfile -t "wearemudita/mudita_os_builder:latest" +cp ./env.cmake.sample ./env.cmake && sed -i "s::$HOME:" env.cmake +git submodule update --init --recursive +cd ./config/ && ./bootstrap.sh 0- && cd ../ +./configure.sh rt1051 RelWithDebInfo +cd build-arm-RelWithDebInfo +make -j + ``` -Please make sure that you add proper tag for image (`-t wearemudita/mudita_os_builder:latest`) as other scripts are using it for building, and if Docker wouldn't be able to find it locally it will download it from Docker Hub. +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 ` + - 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` -## Quickstart in your local environment +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. -Prior to setting up your environment, please run the following command: `cd config && ./bootstrap.sh` The script is written for Ubuntu and tested on 20.04. +## 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 @@ -92,7 +124,7 @@ If the script is run after a fresh `git clone` you need to update your git confi * `./config/bootstrap.sh 7` - add paths for `cmake` to your `PATH` environment variable * `./config/bootstrap.sh 8` - install Docker -#### Code style with git hooks +### 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` @@ -114,7 +146,7 @@ git commit To fix the style for Pull Request CI: `./config/pre-commit.hook --branch-fix` -## Commit message template +### Commit message template To add commit message template use this command: @@ -125,19 +157,19 @@ git config commit.template .gitmessage This way each time you add new commit you will see template that will help you with proper message format. More about that in (Development Workflow)[./doc/development_workflow.md#commit-changes] -## Commit message hook +### 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: +#### Adding a hook: ```bash cd .git/hooks ln -s ../../config/prepare-commit-msg ``` -### using hook: +#### Using a hook: Create a branch @@ -151,92 +183,68 @@ Do your changes, and prepare commit git commit ``` +## CI build using Docker +You can build MuditaOS using a Docker container. To do that, follow these steps -## Longstart - -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` - -After running provisioning you are ready to checkout and build project for both linux and RT1051. Pleasse 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 0-`). -1. Check out the project with submodules for the first time: +2. Add yourself to a `docker` group: ```bash -git submodule update --init --recursive +NAME=$(whoami) +sudo usermod -aG docker ${NAME} ``` -2. Update the repository with submodules +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. +3. Configure for Linux Debug: ```bash -git pull --recurse-submodules +./in_docker.sh config linux Debug ``` -3. Build the project +4. Build linux Debug: ```bash -./configure.sh [rt1051|linux] [release|debug|relwithdebinfo] -cd build-[rt1051|linux]-[release|debug|relwithdebinfo] -make +./in_docker.sh make build-linux-Debug ``` -## Super dirty quickstart on Linux - -Here's the bare minimum that will enable you to bootstrap the environment on Linux. - +5. Build RT1051 Release ```bash -git submodule update --init --recursive # initialize submodules -cd ./config/ && ./bootstrap.sh && cd ../ # bootstrap requirements -./configure.sh rt1051|linux Debug|Release|RelWithDebInfo # configure build -cd # build dir depends on configuration -make -j # build -./PurePhone # run PurePhone - emulator screen will pop up (on the Linux filesystem) +./in_docker.sh config rt1051 Release +./in_docker.sh make build-rt1051-Release ``` +6. Build and run tests (Linux only) -If you want to run the emulator with image and our VFS implementation -you need to run the image through the script: ```bash - ./run_emulator_on_filesystem_image.sh +./in_docker.sh make build-linux-Debug +./in_docker.sh make build-linux-Debug check ``` - -## Super dirty quickstart with unit tests - -After going through the Super dirty quickstart on Linux, run the following commands to build and run all unit tests: - +To build selected test manually in the working directory of attached Docker image run: ```bash -./configure.sh linux debug -cd -make check +cd ./build-linux-Debug ; make ; ./ ``` -## Super dirty 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: - +i.e.: ```bash -cp ./env.cmake.sample ./env.cmake && sed -i "s::$HOME:" env.cmake -git submodule update --init --recursive -cd ./config/ && ./bootstrap.sh && cd ../ -./configure.sh rt1051 RelWithDebInfo -cd build-arm-RelWithDebInfo -make -j - +cd ./build-linux-Debug ; make unittest_gui && ./unittest_gui ``` +Running tests checks memory leaks too - this might be helpful in creation of new widgets. -3. Please take the following steps in three parallel consoles/sessions: +### Building your own Docker image - - Start J-Link server: `./StartJLinkServer.sh` - - Load app with GDB via J-Link connected to Mudita Pure: `./run.sh ` - - Catch logs from Mudita Pure from J-Link RTT and write them to `/tmp/log.txt`: `JLinkRTTClient | tee /tmp/log.txt` +If for some reason (f.ex. testing new dependencies) you need to create your own docker image, you can do it by following: -### Catching logs using UART +1. Configure Docker file and download the necessary tool chain packages: -If you want to catch logs from Mudita Pure from UART please follow these steps: +```bash +./config/build_runner_docker +``` -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` +2. Build a new Docker image -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. +```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