From 3c83e8bde365c38ae6e1f4aad787bb8bd0aed34c Mon Sep 17 00:00:00 2001
From: Liviu Ionescu <ilg@livius.net>
Date: Thu, 4 Feb 2021 21:35:47 +0200
Subject: [PATCH] README updates

---
 README.md | 143 +++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 121 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 968603b7..8a57f884 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,88 @@
 
-# µOS++ RTOS
+[![license](https://img.shields.io/github/license/micro-os-plus/rtos-xpack)](https://github.com/micro-os-plus/rtos-xpack/blob/xpack/LICENSE)
+[![CI on Push](https://github.com/micro-os-plus/rtos-xpack/workflows/CI%20on%20Push/badge.svg)](https://github.com/micro-os-plus/rtos-xpack/actions?query=workflow%3A%22CI+on+Push%22)
+
+# A source xPack with the µOS++ RTOS files
 
 A source xPack with the **µOS++ RTOS**, a POSIX inspired open
-source framework, written in C++. The project is hosted on
-GitHub as
+source framework, written in C++. 
+
+The project is hosted on GitHub as
 [micro-os-plus/rtos-xpack](https://github.com/micro-os-plus/rtos-xpack).
 
-## Purpose
+## Maintainer info
+
+This page is addressed to developers who plan to include this package
+into their own projects.
+
+For maintainer infos, please see the
+[README-MAINTAINER](README-MAINTAINER.md) file.
+
+## Install
+
+As a source xPacks, the easiest way to add it to a project is via **xpm**,
+but it can also be used as any Git project, for example as a submodule.
+
+### Prerequisites
+
+A recent [xpm](https://xpack.github.io/xpm/),
+which is a portable [Node.js](https://nodejs.org/) command line application.
+
+For details please follow the instructions in the
+[install](https://xpack.github.io/install/) page.
+
+### xpm
+
+Note: the package will be available from npmjs.com at a later date.
+
+For now, it can be installed from GitHub:
+
+```console
+$ cd <project>
+$ xpm init # Unless a package.json is already present
+
+$ xpm install github:micro-os-plus/rtos-xpack
+```
+
+When ready, this package will be available as
+[`@micro-os-plus/rtos`](https://www.npmjs.com/package/@micro-os-plus/rtos)
+from the `npmjs.com` registry:
+
+```console
+$ cd <project>
+$ xpm init # Unless a package.json is already present
+
+$ xpm install @micro-os-plus/rtos@latest
+```
+
+### Git submodule
+
+If, for any reason, **xpm** is not available, the next recommended
+solution is to link it as a Git submodule below an `xpacks` folder.
+
+```console
+$ cd <project>
+$ git init # Unless already a Git project
+$ mkdir -p xpacks
+
+$ git submodule add https://github.com/micro-os-plus/rtos-xpack.git \
+  xpacks/micro-os-plus-rtos
+```
+
+## Branches
+
+Apart from the unused `master` branch, there are two active branches:
+
+- `xpack`, with the latest stable version
+- `xpack-develop`, with the current development version
+
+All development is done in the `xpack-develop` branch, and contributions via
+Pull Requests should be directed to this branch.
+
+When new releases are published, the `xpack-develop` branch is merged
+into `xpack`.
+
+## User info
 
 The **µOS++** _(micro oh ɛs plus plus)_ project is
 the third iteration of µOS++, a POSIX-like, portable, open source,
@@ -16,12 +92,12 @@ intended for 32/64-bits embedded applications.
 The APIs are documented in the
 [µOS++ reference](http://micro-os-plus.github.io/reference/cmsis-plus/).
 
-## Status
+### Status
 
 The µOS++ project is fully functional for Cortex-M devices and also runs
 on synthetic POSIX platforms (like macOS and GNU/Linux).
 
-## Related projects
+### Related projects
 
 The current µOS++ code tries to be as portable as possible.
 
@@ -32,38 +108,61 @@ Specific implementations are available from separate projects:
 - the synthetic POSIX port of the scheduler is packed as
 [µOS++ POSIX architecture xPack](https://github.com/micro-os-plus/architecture-posix-xpack)
 
-## Build Configuration
+### Build & integration info
 
-To include µOS++ in a project, in addition to one of the port
-specific project, consider the following details:
+To include this package in a project, consider the following details.
 
-### Include folders
+#### Source folders
 
-- `include`
+- `src`
 
-### Source folders
+#### Include folders
 
-- `src`
+- `include`
+
+TODO: list the available headeres
 
-### Symbols
+#### Preprocessor definitions
 
 See [µOS++ Application Config](http://micro-os-plus.github.io/reference/cmsis-plus/group__cmsis-plus-app-config.html).
 
-## Documentation
+#### Compiler options
 
-- [µOS++](http://micro-os-plus.github.io)
-- [µOS++ reference](http://micro-os-plus.github.io/reference/cmsis-plus/)
+- `-std=c++17` or higher for C++ sources
+- `-std=c11` for C sources
 
-## Demo projects
+#### Namespaces
 
-TODO
+TBD
+
+#### Classes
+
+TBD
+
+### Examples
+
+TBD
+
+### Known problems
+
+- none
+
+### Tests
+
+TBD
+
+### Documentation
+
+- [µOS++](http://micro-os-plus.github.io)
+- [µOS++ reference](http://micro-os-plus.github.io/reference/cmsis-plus/)
 
-## Tests
+### Demo projects
 
 TODO
 
 ## License
 
 The original content is released under the
-[MIT License](https://opensource.org/licenses/MIT), with all rights reserved to
-[Liviu Ionescu](https://github.com/ilg-ul).
+[MIT License](https://opensource.org/licenses/MIT/),
+with all rights reserved to
+[Liviu Ionescu](https://github.com/ilg-ul/).