~aleteoryx/muditaos

18422ef0cf0bc006db5739ee3b439caaf17625c5 — Wojtek Cichoń 5 years ago 680c816 
Added links, corrected small typos, etc. (#809)

Fixed links, added new README draft, etc.
patch browse .tar.gz 
11 files changed, 126 insertions(+), 422 deletions(-)

M CONTRIBUTING.md
D README-NEW.md
M README.md
M doc/README.md
M doc/boot_and_update.md
M doc/changelog_howto.md
D doc/contribute.md
M doc/development_workflow.md
M doc/host_keyboard_bindings.md
M doc/quickstart.md
M doc/setup_ide.md

M CONTRIBUTING.md => CONTRIBUTING.md +4 -2
@@ 2,11 2,13 @@

MuditaOS is an open source project and we're more than happy to receive contributions from our community. There are many ways in which you can contribute to the project from reporting bugs, suggesting features to writing code and documentation.

Before contributing please read and accept our [Code of Conduct](./CODE_OF_CODUCT.md).

## Reporting bugs

If you think you found a bug or a security issue in MuditaOS, we'd love to hear from you. Before you create a relevant GitHub issue please:

- make sure you're using the latest MuditaOS release when spotting the bug by heading to the `Settings` -> `Information` section on your Phone or emulator. Here you can see the all the details about the version of MuditaOS you're currently using. Please compare it with the latest stable release of MuditaOS which is always available at the top of our [changelog](https://github.com/mudita/PurePhone/blob/master/changelog.md).
- make sure you're using the latest MuditaOS release when spotting the bug by heading to the `Settings` -> `Information` section on your Phone or emulator. Here you can see the all the details about the version of MuditaOS you're currently using. Please compare it with the latest stable release of MuditaOS which is always available at the top of our [changelog](./changelog.md).

- make sure that the issue hasn't been already reported on GitHub issues (if it has, please add a 👍 reaction to it).



@@ 31,4 33,4 @@ If you have an idea for a feature that could possibly land in MuditaOS please le

If you would like to contribute a new feature or a bug fix to MuditaOS, please discuss your idea first in Github issues. If there is no Github issue for your idea, please open one. It may be that somebody from Mudita core team is already working on it, or that there are particular complexities that you should know about before starting the implementation.

Please refer to the [Development workflow article](#) to learn how to submit code and documentation changes to the MuditaOS repository.
Please refer to the [Development workflow article](#./doc/development_workflow.md) to learn how to submit code and documentation changes to the MuditaOS repository.


D README-NEW.md => README-NEW.md +0 -76
@@ 1,76 0,0 @@
# MuditaOS

MuditaOS is a mobile operating system optimized for E Ink displays. Built from scratch with Mudita Pure minimalist phone in mind.

![MuditaOS screenshot]()

## Table of contents

* [Quickstart](#)
* [Contributing]
   * [Discussions](#)
   * [Reporting issues and feature requests](#)
   * [Development workflow](#)
* [Documentation](#documentation)
   * [How to generate documentation using Doxygen](#)    
* [License](#license)

## Quickstart

You can quickstart the project by going through one of the following guides:

- [Quickstart using Docker](#)
- [Quickstart in your local environment](#)
- [Super dirty quickstart on Linux](#)
- [Super dirty quickstart with unit tests](#)
- [Super dirty quickstart on the phone](#)
- [Longstart](#)
- [Building your own Docker image](#)

## Contributing

Pull requests are welcome. Please follow the guidelines in the ["Contributing to MuditaOS"](#) article.

### Discussions

For general questions and ideas regarding MuditaOS please post in the [“MuditaOS” section on Mudita Forum](#). Please explore all existing posts to make sure you’re not posting about an issue that has already been discussed.

### Reporting bugs and feature requests

You can report bugs and feature requests on [GitHub](#). This is also a good place to discuss architecture decisions and things that aren’t yet covered by the documentation. Please refer to the ["Contributing to MuditaOS"](#) article for more details.

### Development workflow

When contributing code or documentation changes please follow the guidleines inside the ["Development workflow"](#) article.

## Documentation

For everything that you need to kickstart your development environment please go to the [Documentation](#) folder on Github.

A fully detailed documentation can be build locally using [Doxygen](https://www.doxygen.nl/index.html).

### How to generate documentation using Doxygen

You can build code documentation with the following command:
```sh
./configure linux Debug
cd build-linux-Debug
make doc
```
If you prefer to build documentation always with `all` target instead, configure `cmake`
with `BUILD_DOC_WITH_ALL` option set to `ON`, e.g.:
```sh
./configure <target> <build_type> -DBUILD_DOC_WITH_ALL=ON
```

Documentation is generated in the `doc/html` subdirectory of the build directory. To view it open `index.html` using a web browser, e.g.:
```sh
firefox build-<target>-<build_type>/doc/html/index.html
```

## Changelog

The [MuditaOS changelog](#) is regularly updated by the core development team.

## License
MuditaOS is licensed on [GPL3](https://choosealicense.com/licenses/gpl-3.0/).


M README.md => README.md +48 -238
@@ 1,270 1,80 @@
PurePhone repository
====================
# MuditaOS

# Quickstart in docker
You can build project in docker container, to that
MuditaOS is a mobile operating system optimized for E Ink displays. Built from scratch with Mudita Pure minimalist phone in mind.

1. Get docker
`./config/bootstrap.sh 8`
![MuditaOS screenshot]()

2. Add yourself to a `docker` group
```bash
NAME=$(wohami)
sudo usermod -aG docker ${NAME}
```
After that you have to logo out and login back, groups are set during the login process.
To make sure you are in docker group call:
`groups`
you will see the list of groups your login 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`

5. build rt1051 Release
`./in_docker.sh config rt1051 Release`
`./in_docker.sh make build-rt1051-Release`

6. build & run tests (linux only)
`./in_docker.sh make build-linux-Debug`
`./in_docker.sh make check`
__do not call `make test` it will make fool of you__

To build manually selected test in work-dir in attached docker image:
`cd ./build-linux-Debug ; make <test_name>; ./<test_name>`
i.e.:
`cd ./build-linux-Debug ; make unittest_gui && ./unittest_gui`
## Table of contents

Running tests checks memory leaks too. This might be helpful in creation of new widgets
* [Quickstart](#Quickstart)
* [Contributing](#Contributing)
   * [Discussions](#Discussions)
   * [Reporting issues and feature requests](#Reporting-bugs-and-feature-requests)
   * [Development workflow](#Development-workflow)
* [Documentation](#documentation)
   * [How to generate documentation using Doxygen](#How-to-generate-documentation-using-Doxygen)    
* [License](#license)

# Quickstart
## Quickstart

Prior to any build setup environment, need to be run once. (See: `## Run provisioning`)
`cd config && ./bootstrap.sh`
boostrap.sh will show you list of changes that may be required for you.
If this is new checkout you need to update your git config (step 0 and 1).
You can quickstart the project by going through one of the following guides:

## Bootstrap steps:
* `./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 builds *but it is not installed*
* `./config/bootstrap.sh 3`  - setup arm toolchain, download and install in home dir
* `./config/bootstrap.sh 4`  - setup cmake, download and install in home dir
* `./config/bootstrap.sh 5`  - list of commands for required for switching default gcc/g++ to version 9
* `./config/bootstrap.sh 6`  - adds Paths for arm toolchain to your PATH environment variable - this is also used by ./env.cmake
* `./config/bootstrap.sh 7`  - adds Paths for cmake to your PATH environment variable
* `./config/bootstrap.sh 8`  - install docker
- [Quickstart using Docker](./doc/quickstart.md#quickstart-using-docker)
- [Building your own Docker image](./doc/quickstart.md#building-your-own-docker-image)
- [Quickstart in your local environment](./doc/quickstart.md#quickstart-in-your-local-environment)
- [Longstart](./doc/quickstart.md#longstart)
- [Super dirty quickstart on Linux](./doc/quickstart.md#super-dirty-quickstart-on-linux)
- [Super dirty quickstart with unit tests](./doc/quickstart.md#super-dirty-quickstart-with-unit-tests)
- [Super dirty quickstart on the phone](./doc/quickstart.md#super-dirty-quickstart-on-the-phone)
- [Preparing packages](./doc/quickstart.md#preparing-packages)

*6 add_to_path gcc_arm... is required because new ./env.cmake uses environment variables set by this target.*
## Contributing

Pull requests are welcome. Please follow the guidelines in the ["Contributing to MuditaOS"](./CONTRIBUTING.md) article. Before contributing or starting a discussion, please make sure that you read our [Code of Conduct](./CODE_OF_CODUCT.md).

### Style git hooks
During the bootstrap you can install git hooks for style checking.
pre-commit.hook             - this hook automatically update style during commit
if you haven't run `bootstrap.sh` you have to copy (or link) `pre-commit.hook` to your git conig directory
`.git/config/hooks` directory, just:
`ln -s `pwd`/config/pre-commit.hook .git/hooks/pre-commit`
### Discussions

By default commit hook only checks if your changes have correct 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`, just call:
`git config user.fixinstage true`
For general questions and ideas regarding MuditaOS please post in the [“MuditaOS” section on Mudita Forum](https://forum.mudita.com/c/MuditaOS/). Please explore all existing posts to make sure you’re not posting about an issue that has already been discussed.

If you prefer "notification than fix" work flow (so you can examine the changes), use default hook behaviour (to notify)
and then call `./config/pre-commit.hoot --fix`, this checks and fixes files in "stage" are,
files that have status "changed" are not tested.
### Reporting bugs and feature requests

```
git commit 
<stele error - commit aborted>
./config/pre-commit.hook --fix
git diff
git add -u
git commit
<commit accepted>
```
You can report bugs and feature requests on [GitHub](https://github.com/mudita/MuditaOS/issues). This is also a good place to discuss architecture decisions and things that aren’t yet covered by the documentation. Please refer to the ["Contributing to MuditaOS"](./CONTRIBUTING.md) article for more details.

To fix style for Pull Request CI:
`./config/pre-commit.hook --branch-fix`

## Super quick and dirty to run app on linux:
```
git submodule update --init --recursive                                     # initialize submodules
cd ./config/ && ./bootstrap.sh && cd ../                                    # bootstrap requirements
./cofnigure.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
```
## Super quick and dirty to run UT
build the app (as in previous point)
```bash
./configure.sh linux debug
cd <build-dir>
make check
```
## Super quick and dirty to run app on Phone
### Development workflow

Prior to all - install JLink driver (see `## Install JLink driver`)
When contributing code or documentation changes please follow the guidleines inside the ["Development workflow"](./doc/development_workflow.md) article.

```
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

```

*now in 3 separate consoles*

Start JLink server
```
./StartJLinkServer.sh
```

Load app with GDB via JLink connected to PurePhone
```
./run.sh <build folder>
```

Catch logs from PurePhone from JLink RTT and write them to /tmp/log.txt
```
JLinkRTTClient | tee /tmp/log.txt
```
## Documentation

Catch logs from PurePhone from UART:
1. in `config/ProjectConfig.cmake` change `RTT_JLINK` to `RTT_LUART`
2. rebuild project
3. catch log: `picocom /dev/ttyACM0 -b 115200  --imap lfcrlf`
Please mind that logs on uart are more costly, so these might show unseen before timing issues.
These might slow down phone too - to avoid that consider `release` build for tests with `uart` enabled
For everything that you need to kickstart your development environment please go to the [Documentation](./doc/) folder on Github.

# Longstart
A fully detailed documentation can be build locally using [Doxygen](https://www.doxygen.nl/index.html).

There is provisioning script `./config/bootstrap.sh` run it to install all dependencies - written for Ubuntu tested on 18.10
* This script will require sudo (for apt)
* needed cmake and GCC will be installed by default to `${HOME}` - in case of other needs, change it
* script doesn't install ccache, but if ccache is on system - it's support is added to env.cmake.sample
* need to be run once (not more on restart or anything)
### How to generate documentation using Doxygen

`cd config && ./bootstrap.sh`
You can build code documentation with the following command:

After running provisioning you are ready to checkout and build project for both linux and rt1051 target:
* checking out project with submodules for the first time
```sh
git submodule update --init --recursive
```
* repo update with submodules
```sh
git pull --recurse-submodules
```
* building project
```sh
./configure.sh [rt1051|linux] [release|debug|relwithdebinfo]
cd build-[rt1051|linux]-[release|debug|relwithdebinfo]
make
```

## Building own docker image

If for some reason you don't want to use existing (on hub.docker.com) docker image you can build your own:
1. download toolchain
```bash
./config/download_assets
```
2. build image
```bash
docker build docker/ -t rwicik/pure_phone_build:latest
./configure linux Debug
cd build-linux-Debug
make doc
```
please make sure that you add proper tag for image (`-t rwicik/pure_phone_build:latest`) as other scripts are using it for building, and if docker couldn't find it locally it will download it from hub.docker.com

## Installing JLink driver

We use JLink driver in version JLink v634f, for ubuntu download from here:
[tested JLink we use](https://www.segger.com/downloads/jlink/JLink_Linux_V634f_x86_64.deb)
If you prefer to build documentation always with `all` target instead, configure `cmake`
with `BUILD_DOC_WITH_ALL` option set to `ON`, e.g.:

To install this driver on linux: `sudo dpkg -i JLink_Linux_V634f_x86_64.deb`

## Preparing Packages

If you need a package, containing everything needed to run application (on target device or on linux)
in the build directory call
```bash
make package
./configure <target> <build_type> -DBUILD_DOC_WITH_ALL=ON
```
on finish command will display the name of the package that was created.

Package name is: *PurePhone-<version>-<target>.<extension>*
where:
    <version>   - is readed from the latest "release-x.y.z" tag
    <target>    - RT1051 or Linux 
    <extension> - `zip` for RT1051 and `tar.gz` for Linux

# Documentation
Documentation is generated in the `doc/html` subdirectory of the build directory. To view it open `index.html` using a web browser, e.g.:

* [doc/development_workflow](./doc/development_workflow.md)
* [doc/config](./doc/config.linux.md)
* [doc/running_on_phone](./doc/running_on_phone.md)
* [GUI](./module-gui/README.md)
* [doc/bluetooth](./doc/bluetooth.md)
    * [./module-bsp/bsp/bluetooth](./module-bsp/bsp/bluetooth/)
    * [./module-bluetooth/](./module-bluetooth/README.md)
* [module-lwip](./module-lwip/README.md)
* [doc/database](./doc/database_v2.md)
* [Linux emulator keyboard bindings](./doc/host_keyboard_bindings.md)
* [test/harness](./test/README.md)
* [changelog](./changelog.md) and [changelog howto](./doc/changelog_howto.md)
* [Creating Release](./doc/release.md)

## Code documentation (doxygen)

You can build code documentation with:
```sh
make doc
```
If you prefer to build documentation always with `all` target instead, configure cmake
with `BUILD_DOC_WITH_ALL` option set, e.g.:
```sh
cmake -DBUILD_DOC_WITH_ALL=ON . build/
```

Documentation is generated in the `doc/html` subdirectory of a build dir. To view
open index with browser, e.g.:
```sh
firefox build/doc/html/index.html
```bash
firefox build-<target>-<build_type>/doc/html/index.html
```

## Miscellaneous CMake configuration options

Following CMake options can be used:
 * `COLOR_OUTPUT` - enable/disable colored output (enabled by default). Useful when you need to process CMake output or your IDE does not support escape codes.
 * `BUILD_DOC_WITH_ALL` - enable/disable building code documentation with the `all` target (disabled by default).
 * `ENABLE_TEST_LOGS` - enable/disable test log output (disabled by default).
 * `LINUX_ENABLE_SANITIZER` - enable/disable building with address sanitizer for Linux (enabled by default). This option is handy when you need to run the app with valgrind.
 * `THIRD_PARTY_DEBUG_OPTIMIZE` - enable/disable third party size optimization for debug build type (enabled by default)
 * `ENABLE_APP_<app>` - enable building application `<app>` (enabled by default). `<app>` name must be consistent with module path, i.e. `module-apps/application-<app>/`.
 * `OPTIMIZE_APP_<app>` - allow optimization of app `<app>` in debug build type (disabled by default for Linux platform, enabled for others).

# Linux Bluetooth device

Bluetooth service by default initializes bluetooth device. 
On linux it's tellit developer kit plugged via USB-CDC. To properly
inteface with bluetooth telit device (and not have conflicts in names)
please add following script as: `/etc/udev/rules.d/99-purephone.rules` on linux.

```
ACTION=="add", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", ATTRS{serial}=="AL02ZDVH", GROUP="dialout", SYMLINK+="telit"
ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE="666", GROUP="dialout"
```
## Changelog

This will enable you to use Bluetooth telit board as `/dev/telit` which 
is expected by code.
To access devices without root priviledges add yourselve to dialout group.
`sudo usermod -a -G dialout $USER`
The [MuditaOS changelog](./changelog.md) is regularly updated by the core development team.

For changes to take place run:
`sudo udevadm control --reload-rules && sudo udevadm trigger`
## License
MuditaOS is licensed on [GPL3](https://choosealicense.com/licenses/gpl-3.0/).


M doc/README.md => doc/README.md +23 -24
@@ 23,27 23,26 @@ firefox build/doc/html/index.html

## Table of contents

- [Setting up development environment](#)
    - [Quickstarts](#)
        - [Quickstart using Docker](#)
        - [Quickstart in your local environment](#)
        - [Super dirty quickstart on Linux](#)
        - [Super dirty quickstart with unit tests](#)
        - [Super dirty quickstart on the phone](#)
        - [Longstart](#)
        - [Building your own Docker image](#)
    - [Setting up integrated development environment](setupide.md)
    - [Running MuditaOS on a phone](#)
    - [GUI](#)
    - [Keybindings on Linux](#)
    - [Tests](#)
- [Development workflow](#)
    - [Creating release](#)
- [Contributing](#)
- [Modules](#)
    - [Bluetooth](#)
    - [lwip](#)
- [SMS and Contacts database](#)
- [Changelog](#)
    - [HOWTO](#)
    - [Latest changelog](#)
\ No newline at end of file
- [Quickstarts](quickstart.md)
    - [Quickstart using Docker](quickstart.md#quickstart-using-docker)
    - [Building your own Docker image](quickstart.md#building-your-own-docker-image)
    - [Quickstart in your local environment](quickstart.md#quickstart-in-your-local-environment)
    - [Longstart](quickstart.md#longstart)
    - [Super dirty quickstart on Linux](quickstart.md#super-dirty-quickstart-on-linux)
    - [Super dirty quickstart with unit tests](quickstart.md#super-dirty-quickstart-with-unit-tests)
    - [Super dirty quickstart on the phone](quickstart.md#super-dirty-quickstart-on-the-phone)
    - [Preparing packages](quickstart.md#preparing-packages)
- [Setting up integrated development environment](setup_ide.md)
- [Running MuditaOS on a phone](running_on_phone.md)
- [GUI](./module-gui/README.md)
- [Keybindings on Linux](host_keyboard_bindings.md)
- [Development workflow](development_workflow.md)
    - [Creating release](release.md)
- [Contributing](./CONTRIBUTING.md)
- Modules
    - [Bluetooth](./module-bluetooth/README.md)
    - [lwip](./module-lwip/README.md)
- [SMS and Contacts database](database_v2.md)
- Changelog
    - [HOWTO](changelog_howto.md)
    - [Latest changelog](./changelog.md)
\ No newline at end of file


M doc/boot_and_update.md => doc/boot_and_update.md +0 -3
@@ 278,6 278,3 @@ This is how gparted should look like if the disk is OK
   
This is a case if the disk is not correct
   ![Gparted OK](./Images/gparted_fail.png "workflow")
   
If the phone fails to start in MSC mode, you can try using the D1_Flash_Loader
program to rescue it - [clone the GitHub repository](https://github.com/muditacom/D1_eMMC_FlashLoader/), open it in [Ozone](https://www.segger.com/products/development-tools/ozone-j-link-debugger/)) and load the `.axf` file attached in the initial release of the project. This will present the phones eMMC storage to the OS and you can partition it correctly then.


M doc/changelog_howto.md => doc/changelog_howto.md +1 -1
@@ 4,7 4,7 @@ This article is based on [keep a changelog](https://keepachangelog.com/en/1.0.0/

**Note:** MuditaOS changelog should be **edited by the MuditaOS core development team only**.

[View MuditaOS changelog](changelog.md).
[View MuditaOS changelog](./changelog.md).

## 1. The purpose of a changelog
To let the end user (not necessarily technically-skilled) know what your Pull Request changes. In practice, this means that if some spectacular crash has been fixed, changelog entry should say e.g. `Fixed system crash on saving SMS draft`.


D doc/contribute.md => doc/contribute.md +0 -36
@@ 1,36 0,0 @@
# Contributing to MuditaOS

MuditaOS is an open source project and we're more than happy to receive contributions from our community. There are many ways in which you can contribute to the project from reporting bugs, suggesting features to writing code and documentation.

## Reporting bugs

If you think you found a bug or a security issue in MuditaOS, we'd love to hear from you. Before you create a relevant GitHub issue please:

- make sure you're using the latest MuditaOS release when spotting the bug by heading to the `Settings` -> `Information` section on your Phone or emulator. Here you can see the all the details about the version of MuditaOS you're currently using. Please compare it with the latest stable release of MuditaOS which is always available at the top of our [changelog](https://github.com/mudita/PurePhone/blob/master/changelog.md).

- make sure that the issue hasn't been already reported on GitHub issues (if it has, please add a 👍 reaction to it).

### Reporting a bug - template

Please make sure that your bug report includes the following data:

- General description (what happened)
- Expected behavior (what you think should happen)
- Current behavior (current 'buggy' behavior)
- Steps to reproduce the bug

Feel free to add any screenshots or gifs/screencasts to illustrate the issue.

## Feature requests

If you have an idea for a feature that could possibly land in MuditaOS please let us know by simply creating an issue on Github in which you **describe the feature**, **why it would be useful** and **how it should work**. Before you create a Feature request on GitHub please:

- make sure you're using the latest MuditaOS release when spotting the bug by heading to the `Settings` -> `Information` section on your Phone or emulator. Here you can see the all the details about the version of MuditaOS you're currently using. Please compare it with the latest stable release of MuditaOS which is always available at the top of our [changelog](https://github.com/mudita/PurePhone/blob/master/changelog.md).

- make sure that the feature request hasn't been already reported on GitHub issues (if it has, please add a 👍 reaction to it).

## Contributing code and documentation changes

If you would like to contribute a new feature or a bug fix to MuditaOS, please discuss your idea first in Github issues. If there is no Github issue for your idea, please open one. It may be that somebody from Mudita core team is already working on it, or that there are particular complexities that you should know about before starting the implementation.

Please refer to the [Development workflow article](development_workflow.md) to learn how to submit code and documentation changes to the MuditaOS repository.


M doc/development_workflow.md => doc/development_workflow.md +18 -11
@@ 11,9 11,10 @@ Create a branch, which name is connected to the feature, bug fix, or documentati
## Commit changes

Commit your work. Each commit should have a description explaining:
	- what are you changing,
	- why are you making the changes (motivation),
	- what is the result of your changes.

- what are you changing,
- why are you making the changes (motivation),
- what is the result of your changes.

If it's impossible to provide the above information then your commit is likely excessive or redundant and should be squashed with other commit(s).



@@ 24,19 25,21 @@ Here's [a helpful article about writing good Git commit messages](https://chris.
## Basic checks before Pull Request

Before submitting a Pull Request please go through some basic checks:
	- test your changes on both Linux and RT1051 platforms (please pay special attention to the things you might break unintentionally, e.g. when working on calling funcionality, check call log too)
	- [include changelog description](changelog_howto.md) (if applicable),
	- run unit tests (`make check`),
	- check if your code formatting complies with [`.clang-format`](.clang-format).

- test your changes on both Linux and RT1051 platforms (please pay special attention to the things you might break unintentionally, e.g. when working on calling funcionality, check call log too)
- [include changelog description](./doc/changelog_howto.md) (if applicable),
- run unit tests (`make check`),
- check if your code formatting complies with [`.clang-format`](./.clang-format).

## Submit a Pull Request

Submit a Pull Request. You can add labels that will help people who know the part of the code you are modifying in spotting the changes you are submitting and do a code review. 

Please use the PR description to:
	- explain what and why you are changing, 
	- what decisions you had to take, 
	- what you have been considering but eventually did not do (if applicable), 

- explain what and why you are changing, 
- what decisions you had to take, 
- what you have been considering but eventually did not do (if applicable), 

Include screenshots and gifs/screencasts if applicable. The more information you provide, the bigger chance that you'll receive a quick review.



@@ 78,7 81,8 @@ git rebase origin/master  # update branch you are at to origin/master

**Git rebase works on an actual branch copy.**

`Rebase` changes your commit history (moves them on top). This means two things:  
`Rebase` changes your commit history (moves them on top). This means two things:

 - when you did a lot of changes in a lot of places - either `git push` your branch on server, or make its copy
 - when you're happy of `git rebase` results - you'll need to push your branch with force to server - since you've changed its history (updated it) 



@@ 99,14 103,17 @@ git status                                            # when done - check that y
```

If there was something that broke your changes you can now either:

* fix it in your next commit
* try rebase again with:
    * `git reset origin/your_branch_name --hard`

If your rebase succeeds:

* `git push origin your_branch_name:your_branch_name`

**Note:**

 - Rebase changes history - don't rebase branches that other people are working on (it's doable, but don't do this if you're not familiar with how to do it properly)
 - Always rebase your feature branches to `origin master`



M doc/host_keyboard_bindings.md => doc/host_keyboard_bindings.md +5 -4
@@ 1,9 1,10 @@
# Keyboard bindinging on Linux

## Table of contents
- [Functional buttons](#Functional-buttons)
- [Numeric buttons](#Numeric-buttons)
- [Battery "buttons"](#Battery-"buttons")

- [Functional buttons](#functional-buttons)
- [Numeric buttons](#numeric-buttons)
- [Battery "buttons"](#battery-buttons)

### Functional buttons
- Volume up         - key [ `R` ] 


@@ 34,7 35,7 @@
- Numeric Ast		- key [ `Z` ]
- Numeric Pnd		- key [ `C` ]

### Battery "buttons"
### Battery buttons
 - Connect/disconnect wall adapter		- key [ `P` ]
 - Decrease battery level		- key [ `[` ]
 - Increase battery level		- key [ `]` ]
\ No newline at end of file


M doc/quickstart.md => doc/quickstart.md +9 -9
@@ 2,14 2,14 @@

You can quickstart the project by going through one of the following guides:

- [Quickstart using Docker](#)
- [Building your own Docker image](#)
- [Quickstart in your local environment](#)
- [Longstart](#)
- [Super dirty quickstart on Linux](#)
- [Super dirty quickstart with unit tests](#)
- [Super dirty quickstart on the phone](#)
- [Preparing packages](#)
- [Quickstart using Docker](#quickstart-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)


## Quickstart using Docker


@@ 192,7 192,7 @@ If you want to catch logs from Mudita Pure from UART please follow these steps:

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.

## Preparing Packages
## Preparing packages

If you need a package, containing everything needed to run the application (on target device or Linux), in the build directory run the following command: `make package`



M doc/setup_ide.md => doc/setup_ide.md +18 -18
@@ 1,11 1,11 @@
# Setting up an integrated development environment

## Table of contents
- Setting up in [Eclipse](#Eclipse)
- Setting up in [CLion](#CLion)
- Additional info
    + Prevent Git from suggesting commits
    + Seperate build folders
- [Setting up in Eclipse](#setting-up-in-eclipse)
- [Setting up in CLion](#setting-up-in -clion)
- [Additional info](#additional-info)
    + [Prevent Git from suggesting commits](#prevent-git-from-suggesting- commits)
    + [Seperate build folders](#separate-build-folders)

### Setting up in Eclipse



@@ 27,16 27,16 @@ To run the project in Eclipse:

1. Open settings (CTRL+ALT+S)
2. Go to `Build, Execution, Deployment` -> `Toolchain`
3. Add new toolchains for Linux and rt1051 (ALT+Ins) of `System` type
3. Add new toolchains for Linux and RT1051 (ALT+Ins) of `System` type
    - Name: Linux
        - CMake should be autodetected - if not, run `which cmake`   
        - Select appropriate `gdb`
        - for x86 it's usually `/usr/bin/gdb`

    - Name: rt1051
    - Name: RT1051
        - CMake should be autodetected - if not, run `which cmake`
        - Select appropriate `gdb`
        - for rt1051 it's usually `~/gcc-arm-eabi…`
        - for RT1051 it's usually `~/gcc-arm-eabi…`

#### Building configurations



@@ 55,7 55,7 @@ To run the project in Eclipse:
  - Generation path: `build-linux`
  - Build options: `-j8`

**Note:** you can set Generation path to `build` if you don't plan to configure CLion for rt1051.
**Note:** you can set Generation path to `build` if you don't plan to configure CLion for RT1051.

4. Add new CMake Profile (ALT+Ins)
  - Name: rt1051


@@ 81,7 81,7 @@ In `Working directory` append `/build`.

Now you can run/debug this configuration.

##### rt1051 configuration
##### RT1051 configuration

Use file `.idea/JLink_server.xml` to setup IDE. It's already in the project folder, so CLion should pick it up automatically.



@@ 95,14 95,14 @@ Try this command to input it there `ln -s %project_root%/.gdbinit-1051-clion ~/.

In the debuging configuration dropdown select a pair of **<exec>** and **<toolchn>** (**[ \<exec\> | \<toolchn\> \]**):
- **\[PurePhone | Linux\]** for run/debug on desktop (Linux)
- **\[JLink server | rt1051\]** for debug on embedded (rt1051)
- **\[JLink server | RT1051\]** for debug on embedded (RT1051)

**Note:** rt1051 doesn't have *run* configuration. Only debug is available.
**Note:** RT1051 doesn't have *run* configuration. Only debug is available.

![Profit](https://user-images.githubusercontent.com/56958031/71167426-f28ac780-2254-11ea-8efb-8375fb004004.png)

##### Running target
It's possible to see logs from a rt1051 booted from eMMC and not from RAM. 
It's possible to see logs from a RT1051 booted from eMMC and not from RAM. 
To do so select `JLink server (no upload)` configuration.

Open `JLinkRTTClient` in a separate terminal.


@@ 143,20 143,20 @@ This will tell git to ignore local changes to the file. In above example we are 

#### Separate build folders

By default both targets (Linux & rt1051) are build into the same destination (the `build` folder).
By default both targets (Linux & RT1051) are build into the same destination (the `build` folder).

With this configuration you have to run `./rebuild.sh` every time you want to change target. Also you can't debug simultaneously Linux and rt1051.
With this configuration you have to run `./rebuild.sh` every time you want to change target. Also you can't debug simultaneously Linux and RT1051.

There is an option for both targets to have separate build folders.

To enable it, set the environmental variable `SEPARATE_BUILDS` to any value (e.g. `=1`) inside `./rebuild.sh`.

**Examples**:
`env SEPARATE_BUILDS=1 ./rebuild.sh rt1051` will cause rt1051 to be build into a separate `build-rt1051` folder.
`env SEPARATE_BUILDS=1 ./rebuild.sh rt1051` will cause RT1051 to be build into a separate `build-rt1051` folder.

By default `./rebuild.sh rt1051` builds into `build`

You can build only the Linux build inside its separate folder, and leave rt1051 in place, thus maintain compatibility with `./run.sh`. 
You can build only the Linux build inside its separate folder, and leave RT1051 in place, thus maintain compatibility with `./run.sh`. 

```
> env SEPARATE_BUILDS=1 ./rebuild.sh linux


@@ 167,7 167,7 @@ You can build only the Linux build inside its separate folder, and leave rt1051 
> ./run.sh
```

Guide for CLion has a dedicated section entitled ["Separate build folders in CLion"]().
Guide for CLion has a dedicated section entitled ["Separate build folders in CLion"](#separate-build-folders-in-clion).

##### How it works