docs: versioning and native build set up

docs/NativeBuild.md

@@ -0,0 +1,102 @@
+# Set up host to build Ocre
+
+This document provides instructions on how to build the Ocre Runtime from source without requiring Docker. These instructions also work inside a docker container, however this is provided as a reference for whose who need the development enviroment available in the host.
+
+For quick instructions on how to build the Ocre Runtime (potentially using docker), see [Devcontainers](Devcontainers.md), [Getting Started with Linux](GetStartedLinux.md) and [Getting Started with Zephyr](GetStartedZephyr.md) documents.
+
+We detail the procedure to set up the host system prerequisites, and build a native Linux version of the Ocre Runtime, and also how to set up a Zephyr development environment locally, which includes Ocre.
+
+## General Prerequisites
+
+These prerequisites are necessary both for Linux and Zephyr build.
+
+Our reference system is a Ubuntu 24.04 LTS, however these instructions can be easily adapted for other Linux distributions, as well as other POSIX based operating systems.
+
+### Build Tools
+
+Ocre requires CMake and a C compiler such as GCC. For full testing support, we also use clang.
+If we are checking out the Ocre repository, we also need Git to clone Ocre Runtime, and Wget to unpack the WASI-SDK. Install all with:
+
+```sh
+sudo apt update -y
+sudo apt install -y apt install build-essential git cmake clang wget
+```
+
+### WASI-SDK
+
+For building WASM/WASI containers (including the test containers), we need the WASI-SDK.
+Download a WASI-P1 compatible WASI-SDK from [the WASI SDK releases page](https://github.com/WebAssembly/wasi-sdk/releases) for your platform. The current recommended version is `wasi-sdk-29`.
+
+This is usually installed under `/opt/wasi-sdk` for default easy usage without the need to set environment variables.
+
+Download, unpack and install WASI SDK. Note that these are Linux binary packages. Make sure you replace `amd_64` with `arm64` in case your host is ARM64 based:
+
+```sh
+wget https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-29/wasi-sdk-29.0-amd_64-linux.tar.gz
+tar -xzf wasi-sdk-29.0-amd_64-linux.tar.gz
+sudo wasi-sdk-29.0-amd_64-linux /opt/wasi-sdk
+```
+
+You can check that WASI SDK is properly installed by checking the WASI clang version:
+
+```sh
+/opt/wasi-sdk/bin/clang --version
+```
+
+The output should be similar to:
+
+```
+clang version 21.1.4-wasi-sdk (https://github.com/llvm/llvm-project 222fc11f2b8f25f6a0f4976272ef1bb7bf49521d)
+Target: wasm32-unknown-wasi
+Thread model: posix
+InstalledDir: /opt/wasi-sdk/bin
+Configuration file: /opt/wasi-sdk/bin/clang.cfg
+```
+
+## Linux
+
+This environment is enough to build and run Ocre on Linux:
+
+```sh
+git clone --recursive https://github.com/project-ocre/ocre-runtime.git
+cd ocre-runtime
+mkdir build
+cd build
+cmake ..
+make
+```
+
+Check the [Getting Started with Linux](GetStartedLinux.md) and [Linux Build System](BuildSystemLinux.md) for more information.
+
+## Zephyr
+
+As stated in the Zephyr [Getting Started Guide](https://docs.zephyrproject.org/latest/getting_started/index.html),
+Zephyr requires additional tools such as `python3` among others. We can install them with:
+
+```sh
+sudo apt update -y
+sudo apt install --no-install-recommends git cmake ninja-build gperf \
+  ccache dfu-util device-tree-compiler wget python3-dev python3-venv python3-tk \
+  xz-utils file make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1
+```
+
+Then we need `west`. This is usually done in the venv because we might need some more Python packages and we do not want to tamper with the system Python packages (which are outside of the virtual environment).
+
+Create a virtual environment:
+
+```sh
+python3 -m venv .venv
+source venv/bin/activate
+```
+
+Install `west`:
+
+```sh
+pip install west
+```
+
+Now you can proceed to build your Zephyr application as detailed in Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/latest/getting_started/index.html).
+
+Alternatively you can check [Get Started with Zephyr](GetStartedZephyr.md) and [Custom Zephyr Application](CustomZephyrApplication.md) to build a custom application or the Ocre samples.
+
+You can also check the [Zephyr Build System](BuildSystemZephyr.md) for more information about the build configuration.

docs/Versioning.md

@@ -0,0 +1,58 @@
+# Ocre Versioning
+
+## Source components
+
+There are several components of the Ocre version that gets compiled in the project.
+
+The file `src/ocre/version.h` includes the Ocre Library version string.
+While the file `commit_id.h` includes the commit ID of the Ocre Library.
+If this file is not present in the source tree, the file is generated during the build process and is stored in the build directory.
+If the file does not exist, and the source tree is not a valid git repository, the build will fail.
+
+Note that these are unrelated to the Zephyr version and the Zephyr application version mechanism (i.e. through the use of the VERSION file in the Zephyr application directory).
+
+## Version variables
+
+These files together form the Ocre version variables, which are compiled statically into the `struct ocre_config ocre_build_configuration` struct defined in `ocre/library.h`:
+
+```c
+struct ocre_config {
+	const char *version;	/**< Version of the Ocre Library */
+	const char *commit_id;	/**< Commit ID of the build tree */
+	const char *build_info; /**< Host build information */
+	const char *build_date; /**< Build date */
+};
+
+extern const struct ocre_config ocre_build_configuration;
+```
+
+The specific meaning of these variables is as follows:
+
+### version
+
+The version of the Ocre Library. In the form Major.Minor.Patch and is defined in the `version.h` file.
+
+It follows the semantic versioning format.
+
+Note the `version.h` file is not generated automatically. Instead it is maintained manually or automatically whenever we release a new version of the Ocre Runtime.
+
+### commit_id
+
+The commit ID of the build tree.
+Generated every time into `commit_id.h` if the source tree is a valid git repository, otherwise, set to whatever is defined in `commit_id.h`.
+
+The format is `commit-hash[-dirty]`. This is generated by the build system using `git describe --always --abbrev=0 --dirty`, so it means the current commit hash and if there are any uncommitted changes in the working tree (as specificied by the optional `-dirty` suffix).
+
+### build_info
+
+The host build information. Generated on every build system by the build system automatically.
+
+It has the format `user @ system`. Where `user` is the value of the `USER` environment variable and `system` is the output of `uname -a`.
+
+### build_date
+
+The build date. Generated on every build system by the build system automatically.
+
+It has the format `YYYY-MM-DD HH:MM:SS TZ` and is generated by `date +'%Y-%m-%d %H:%M:%S %Z'`
+
+For more information about the build system, see [Linux Build System](BuildSystemLinux.md) and [Zephyr Build System](BuildSystemZephyr.md) documentation.