~aleteoryx/muditaos

66415929584a3f3a7d3fe87ed8eae0e0e96596b7 — Wiktor S. Ovalle Correa 5 years ago 1bdc829 
[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.
patch browse .tar.gz 
1 files changed, 111 insertions(+), 103 deletions(-)

M doc/quickstart.md

M doc/quickstart.md => doc/quickstart.md +111 -103
@@ 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 <test_name>; ./<test_name>
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>                                                 # 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 <build-dir>
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>:$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 <build folder>`
 - 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>                                                 # 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 <build-dir>
make check
cd ./build-linux-Debug ; make <test_name>; ./<test_name>
```
## 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>:$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 <build folder>`
 - 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