A CONTRIBUTING.md => CONTRIBUTING.md +34 -0
@@ 0,0 1,34 @@
+# 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 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](#) to learn how to submit code and documentation changes to the MuditaOS repository.
A README-NEW.md => README-NEW.md +76 -0
@@ 0,0 1,76 @@
+# 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/).
A doc/README.md => doc/README.md +49 -0
@@ 0,0 1,49 @@
+# MuditaOS Documentation
+
+Thid folder contains everything you need to kickstart your development environment for MuditaOS.
+
+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
+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
+cmake -DBUILD_DOC_WITH_ALL=ON . build/
+```
+
+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/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
D doc/config.linux.md => doc/config.linux.md +0 -68
@@ 1,68 0,0 @@
-
-
-# How to setup environment
-
-## Table of contents
-1. [Eclipse](#Eclipse)
-2. [CLion](#CLion)
-3. [Environment](#Environment)
-4. [Separate build folders](#Separate)
-
-
-### Eclipse <a name="Eclipse"></a>
-
-**To run project in eclipse:**
-
-* Run cmake to create build directory. Create inside build "sys" folder and copy all assets to it (e.g path for font: sys/assets/fonts/gt_pressura_regular_16.mpf ). Faster way is to run following command in main directory: **./rebuild script**
-
-* Open projects properties and in tab 'C/C++ Build'->'Builder Settings' set build directory to: **${workspace_loc:/PurePhone}/build**
-* Create deubg configuration ( right click on project and select debug as: local c/c++ application )
-* Open new debug configuration and in Arguments tab set 'Working directory' to **${workspace_loc:PurePhone/build}**
-* In Debugger tab set GDB command file to **${project_loc}/.gdbinit**
-
-### CLion <a name="CLion"></a>
-See here: [**doc/config.clion.md**](./config.clion.md)
-
-### Environment <a name="Environment"></a>
-
-If you want to prevent git from suggesting you to commit changes to the configuration files where we place for example local paths please cast following spell.
-
-**git update-index --skip-worktree env.cmake**
-
-This will tell git to ignore local changes to the file. In above example we are preventing commiting changes to file called env.cmake where you probably want to place local path to arm's toolchain.
-
-### Separate build folders<a name="Separate">
-By default both targets (Linux & rt1051) are build into the same destination (**build** folder).
-With this configuration you have to `./rebuild.sh` every time you want to change target. Also you cannot debug simultaneously Linux & rt1051.
-
-There is an option for both targets to have _separate_ build folders.
-To do so, set environmental variable `SEPARATE_BUILDS` with any value (e.g. `=1`) to `./rebuild.sh`.
-#### Example:
-`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 linux build to its separate folder, and leave rt1051 in place, thus maintain compatibility with `./run.sh`. See below:
-
-#### Example 2:
-```
-> env SEPARATE_BUILDS=1 ./rebuild.sh linux
-> cd build-linux; ./PurePhone.elf
-> cd ..
-> ./rebuild.sh rt1051 # will be built to the default `build` folder
-> StartJLinkServer.sh &
-> ./run.sh
-```
-
-Guide for **[CLion](#CLion)** has a section on _separate builds_.
-
-How it works:
-By default `./rebuild.sh` copies assets and generates CMakes to generic `build`.
-`SEPARATE_BUILDS=1` overrides it.
-
-Then comes CMake. CMake uses persistent (CACHED) variable `PROJECT_BUILD_DIRECTORY` to build every module.
-You can set it either in `cmake-gui` or by passing environmental variable to `cmake`.
-
-
-This works like a toggle. You don't have to specify it every time. The new build path gets embedded into every `CMakeCache.txt`, so any further `make` doesn't require any extra arguments.>
\ No newline at end of file
A doc/setup_ide.md => doc/setup_ide.md +182 -0
@@ 0,0 1,182 @@
+# 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
+
+To run the project in Eclipse:
+
+1. Run `cmake` to create build directory. Create inside build `sys` folder and copy all assets to it (e.g path for font: `sys/assets/fonts/gt_pressura_regular_16.mpf`). A faster way to do this is to run `./rebuild script` command in the main directory.
+
+2. Open project properties and in tab `C/C++ Build`->`Builder Settings` set build directory to: `${workspace_loc:/PurePhone}/build`
+
+3. Create debug configuration (right click on project and select `Debug as: local c/c++ application`)
+
+4. Open new debug configuration and in `Arguments` tab set `Working directory` to `${workspace_loc:PurePhone/build}`
+
+5. In `Debugger` tab set `GDB command file` to `${project_loc}/.gdbinit`
+
+### Setting up in CLion
+
+#### Setting up Toolchains
+
+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
+ - Name: Linux
+ - CMake should be autodetected - if not, run `which cmake`
+ - Select appropriate `gdb`
+ - for x86 it's usually `/usr/bin/gdb`
+
+ - Name: rt1051
+ - CMake should be autodetected - if not, run `which cmake`
+ - Select appropriate `gdb`
+ - for rt1051 it's usually `~/gcc-arm-eabi…`
+
+#### Building configurations
+
+1. Open settings (CTRL+ALT+S)
+2. Go to `Build, Execution, Deployment` -> `CMake`
+3. Add new CMake Profile (ALT+Ins)
+ - Name: Linux
+ - Build type: Debug
+ - CMake options:
+ ```
+ -DCMAKE_EXPORT_COMPILE_COMMANDS=True
+ -DCMAKE_BUILD_TYPE=Debug
+ -DCMAKE_TOOLCHAIN_FILE=../Target_Linux.cmake
+ -DCMAKE_EXPORT_COMPILE_COMMANDS=1
+ ```
+ - Select appropriate Toolchain created above
+ - 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.
+
+4. Add new CMake Profile (ALT+Ins)
+ - Name: rt1051
+ - Build type: Debug
+ - CMake options:
+ ```
+ -DCMAKE_EXPORT_COMPILE_COMMANDS=True
+ -DCMAKE_BUILD_TYPE=Debug
+ -DCMAKE_TOOLCHAIN_FILE=../Target_RT1051.cmake
+ -DCMAKE_EXPORT_COMPILE_COMMANDS=1 'DBT_STACK_SEL="Bluetopia"' ../
+ ```
+ - Select appropriate Toolchain created above
+ - Generation path: `build-rt1051`
+ - build options: `-j8`
+
+#### Running/debugging
+##### Linux configuration
+
+**Important**
+Before 1st run, execute `Build All in 'Linux'` to generate the `service_renderer` utility.
+
+Go to `Edit Configurations…` (double shift) and select `CMakeApplication` -> `PurePhone`. This is your configuration for Linux executable.
+In `Working directory` append `/build`.
+
+Now you can run/debug this 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.
+
+You'll also need `.gdbinit-1051-clion` file modified for CLion ([source](https://stackoverflow.com/questions/39810593/gdb-monitor-commands-in-clion)).
+
+This file needs to be present in `$HOME/.gdbinit`.
+
+Try this command to input it there `ln -s %project_root%/.gdbinit-1051-clion ~/.gdbinit`.
+
+##### Workflow
+
+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)
+
+**Note:** rt1051 doesn't have *run* configuration. Only debug is available.
+
+
+
+##### Running target
+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.
+
+**Note:** remember to stop this debug session when you want to switch to regular JLink server (with upload), otherwise they will collide.
+
+To properly debug a running target you need to reset it first. Attaching to an already running target won't work.
+
+#### Separate build folders in CLion
+
+To build separately for each architecture you need to:
+
+- Open settings (CTRL+ALT+S)
+- Goto to `Build, Execution, Deployment` -> `CMake`
+- Select `Linux`
+- Add a variable to `Environment`: `PROJECT_BUILD_DIRECTORY=build-linux`
+- Change `Generation Path` to: `build-linux`
+
+and
+
+- Open settings (CTRL+ALT+S)
+- Go to `Build, Execution, Deployment` -> `CMake`
+- Select `rt1051`
+- Add a variable to `Environment`: `PROJECT_BUILD_DIRECTORY=build-rt1051`
+- Change `Generation Path` to: `build-rt1051`
+
+After the above steps:
+- Change run/debug `Working directory` for Linux configuration. (`Edit configurations…` -> `PurePhone`)
+- Change `Working directory` from `…/PurePhone/build` to `…PurePhone/build-linux`
+
+### Additional info
+
+#### Prevent git from suggesting commits
+
+If you want to prevent git from suggesting you to commit changes to the configuration files where we place local paths and other data, please cast following spell: `git update-index --skip-worktree env.cmake`
+
+This will tell git to ignore local changes to the file. In above example we are preventing commiting changes to file called `env.cmake` where you probably want to place local path to Arm's toolchain.
+
+#### Separate build folders
+
+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.
+
+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.
+
+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`.
+
+```
+> env SEPARATE_BUILDS=1 ./rebuild.sh linux
+> cd build-linux; ./PurePhone.elf
+> cd ..
+> ./rebuild.sh rt1051 # will be built to the default `build` folder
+> StartJLinkServer.sh &
+> ./run.sh
+```
+
+Guide for CLion has a dedicated section entitled ["Separate build folders in CLion"]().
+
+##### How it works
+
+By default `./rebuild.sh` copies assets and generates CMakes to generic `build`.
+`SEPARATE_BUILDS=1` overrides it.
+
+Then comes CMake. CMake uses persistent (CACHED) variable `PROJECT_BUILD_DIRECTORY` to build every module.
+You can set it either in `cmake-gui` or by passing environmental variable to `cmake`.
+
+This works like a toggle. You don't have to specify it every time. The new build path gets embedded into every `CMakeCache.txt`, so any following `make` command doesn't require any extra arguments.<
\ No newline at end of file