doc: document all the current feature of CoreOS

.gitignore

@@ -1,2 +1,4 @@
 build/
 vscode-bitbake-build/
+documentation/_build/
+

documentation/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

documentation/conf.py

@@ -0,0 +1,112 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Belden CoreOS'
+copyright = '2022, Belden CoreOS Team'
+author = 'CoreOS Team'
+
+# The full version, including alpha/beta/rc tags
+try:
+    git_describe = os.popen('git describe --tags --always').read().strip()
+except all:
+    git_describe = ""
+
+release = f'0.0.1 ({git_describe})'
+version = release
+
+
+# -- General configuration ---------------------------------------------------
+
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.extlinks',
+    'sphinx.ext.intersphinx',
+]
+
+# external links and substitutions
+extlinks = {
+    'cve': ('https://nvd.nist.gov/vuln/detail/CVE-%s', 'CVE-%s'),
+    'yocto_home': ('https://www.yoctoproject.org%s', None),
+    'yocto_wiki': ('https://wiki.yoctoproject.org/wiki%s', None),
+    'yocto_dl': ('https://downloads.yoctoproject.org%s', None),
+    'yocto_lists': ('https://lists.yoctoproject.org%s', None),
+    'yocto_bugs': ('https://bugzilla.yoctoproject.org%s', None),
+    'yocto_ab': ('https://autobuilder.yoctoproject.org%s', None),
+    'yocto_docs': ('https://docs.yoctoproject.org%s', None),
+    'yocto_git': ('https://git.yoctoproject.org%s', None),
+    'yocto_sstate': ('http://sstate.yoctoproject.org%s', None),
+    'oe_home': ('https://www.openembedded.org%s', None),
+    'oe_lists': ('https://lists.openembedded.org%s', None),
+    'oe_git': ('https://git.openembedded.org%s', None),
+    'oe_wiki': ('https://www.openembedded.org/wiki%s', None),
+    'oe_layerindex': ('https://layers.openembedded.org%s', None),
+    'oe_layer': ('https://layers.openembedded.org/layerindex/branch/master/layer%s', None),
+}
+
+bitbake_version = "2.0"
+yocto_version = "4.0.4"
+
+# Intersphinx config to use cross reference with BitBake user manual
+intersphinx_mapping = {
+    'bitbake': ('https://docs.yoctoproject.org/bitbake/' + bitbake_version, None),
+    'yocto': ('https://docs.yoctoproject.org/' + yocto_version, None),
+}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+try:
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_options = {
+        'sticky_navigation': False,
+        'collapse_navigation': False,
+        'display_version': True
+    }
+except ImportError:
+    sys.stderr.write("The Sphinx sphinx_rtd_theme HTML theme was not found.\
+    \nPlease make sure to install the sphinx_rtd_theme Python package.\n")
+    sys.exit(1)
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Hide 'Created using Sphinx' text
+html_show_sphinx = False
+
+html_logo = "_static/logo.png"

documentation/genindex.rst

@@ -0,0 +1,3 @@
+=====
+Index
+=====

documentation/index.rst

@@ -0,0 +1,38 @@
+.. Belden CoreOS documentation master file, created by
+   sphinx-quickstart on Fri Sep 30 08:54:14 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Belden CoreOS's documentation!
+=========================================
+
+.. image:: _static/logo2.png
+  :alt: CoreOS Logo
+
+CoreOS is a Linux distribution based on OpenEmbedded-Core.
+
+The CoreOS's documentation complement the :external:ref:`Yocto Project
+Documentation <index:Welcome to the Yocto Project Documentation>` and use the
+same structures.
+
+|
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Introduction and Overview
+
+   Quick Build <quick-build>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Manuals
+
+   Reference Manual <ref-manual/index>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Indexes
+   :hidden:
+
+   Releases <migration-guides/index>
+   Glossary <genindex>

documentation/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

documentation/migration-guides/index.rst

@@ -0,0 +1,14 @@
+====================
+ Release Information
+====================
+
+|
+
+Each document in this chapter provides release notes and information about how
+to move to one release of the CoreOS Project from the previous one.
+
+.. toctree::
+   :caption: Table of Contents
+   :numbered:
+
+   release-master

documentation/migration-guides/release-master.rst

@@ -0,0 +1,8 @@
+Master branch
+=============
+
+The master branch of CoreOS is based on the `kirkstone` branch of
+OpenEmbedded-Core.
+
+More info about this release of OpenEmbedded-Core can be found in the
+:external:ref:`upstream documentation <migration-guides/migration-4.0:Release 4.0 (kirkstone)>`

documentation/quick-build.rst

@@ -0,0 +1,171 @@
+*******************
+Core OS Quick Build
+*******************
+
+Welcome!
+########
+
+This short document will help you generate your first image for any device
+supported by CoreOS. If you are familiar with Yocto, this chapiter was
+inspired and is structured in the same way as the `Yocto Project Quick Build
+documentation <https://docs.yoctoproject.org/brief-yoctoprojectqs/index.html>`_.
+
+Compatible Build Machine
+########################
+
+Building a whole operating system from scratch takes a long time and requires
+a powerful build machine.
+
+We recommend to have at least:
+
+* A modern CPU with at least 6-cores (Intel i7 9th generation or equivalent)
+* A fast SSD for the operating system
+* 32GB of RAM
+
+Optionally, for better performance you should use a separate SSD used only by
+the Yocto build system.
+
+Compatible Linux Distribution
+#############################
+
+At this moment, the CoreOS system is only tested on `Debian 11` build
+machines and it's the recommended operating system for new user. This
+documentation assumes that you have a machine running natively with it.
+
+Before starting, you should ensure that you have at least 250GB of free disk
+space.
+
+Package needed on the build machine
+###################################
+
+Theses packages are needed on your build machine:
+
+.. code-block:: sh
+
+   ~$ sudo apt install gawk wget git diffstat unzip texinfo gcc build-essential \
+      chrpath socat cpio python3 python3-pip python3-pexpect xz-utils \
+      debianutils iputils-ping python3-git python3-jinja2 libegl1-mesa \
+      libsdl1.2-dev pylint3 xterm python3-subunit mesa-common-dev zstd \
+      liblz4-tool bmap-tools
+
+Use Git to clone CoreOS
+########################
+
+.. hint::
+
+   If you read this documentation, you probably already have an account on
+   `BitBucket <bitbucket.gad.local>`_ and you can access `the core-os repository
+   <https://bitbucket.gad.local/projects/ICO/repos/coreos/browse>`_. Otherwise you should
+   ask the person who sent you a copy of this document.
+
+To clone the repository, you have to add an SSH key to your BitBucket account via
+`the BitBucket SSH Key configuration page <https://bitbucket.gad.local/plugins/servlet/ssh/account/keys>`_
+first.
+
+.. code-block:: sh
+
+   ~$ git clone --recurse-submodules ssh://git@bitbucket.gad.local:7999/ico/coreos.git
+   ~$ cd coreos
+
+Building an image
+#################
+
+Before building an image, we have to first configure the build.
+
+To create a build folder with our default configuration, you can run the `oe-init-build-env`
+script:
+
+.. code-block:: sh
+
+   ~/core-os$ source oe-init-build-env
+
+.. note::
+
+    The inilization script has created a `build` directory inside the `core-os` directory and
+    copied some default configuration in the `build/conf` folder. The current working directory
+    was changed and we are now inside `~/coreos/build`
+
+You can open the `build/conf/local.conf` file to change the build configuration. You probably
+want to change the current `MACHINE` to one that is compatible with the hardware that you want
+to build an image for.
+
+Now that you have configured the build, we can build an `image`. Building an `image` will
+generate a bootable disk image that can be used to boot the system. This document assume that
+the machine is set to `cn9130-cf-pro` but you can use any other MACHINE listed in local.conf.
+
+.. hint::
+
+    If you use another machine that `cn9130-cf-pro`, you will have to replace each
+    occurrences of `cn9130-cf-pro` to your machine when executing a command.
+
+For an image that contains a lot of developer tools, the best image to build
+is `coreos-image-full-cmdline`.
+
+.. code-block:: sh
+
+   ~/img-build/build$ bitbake coreos-image-full-cmdline
+
+After a long time, the build system will return. You can list all the artifacts
+produced by `bitbake` using `ls`:
+
+.. code-block:: sh
+
+   ~/coreos/build$ ls tmp/deploy/images/*/
+
+A lot of file was generated, but the file that you can flash to your SD Card can
+be found with this command:
+
+.. code-block:: sh
+
+   ~/coreos/build$ find tmp/deploy/images/${MACHINE} -type l -name "*.wic.xz"
+   tmp/deploy/images/cn9130-cf-pro/coreos-image-full-cmdline-cn9130-cf-pro.wic.xz
+
+.. hint::
+
+   Note that `bitbake` generates a lof of symlinks so that the same file can be
+   accessed using multiple filenames.
+
+Flashing an image to a SD Card
+##############################
+
+.. warning::
+
+   Flashing an image to the wrong disk can remove all your file
+
+The safest way to get the name of your SD card disk is to first run this
+command before inserting the SD Card into your computer:
+
+.. code-block:: sh
+
+   ~/coreos/build$ lsblk | grep disk | grep mmc
+
+This command should return nothing. If it does, do not use any of the disk name
+listed.
+
+Now insert the SD card in your computer and rerun the same command:
+
+.. code-block:: sh
+
+   ~/coreos/build$ lsblk | grep disk | grep mmc
+   mmcblk0            179:0    0  14.8G  0 disk
+
+You should have a single line printed. The name of your SD card device is the
+first word printed, here `mmcblk0`. If you have multiple printed, take the name
+from the single line that was not present the first time you have run the
+command.
+
+.. hint::
+
+   If you are unsure, you can also check that the disk size match the one of
+   your SD Card. I have inserted a 16GB sdcard, and the command report a size of
+   of 14.8G, so this is a match. The command report the size in GiB, you can use
+   google to convert GiB to GB, just search "14.8GiB in GB" and expect some
+   rounding error.
+
+Now, flash the image file to the your card:
+
+.. code-block:: sh
+
+   ~/coreos/build$ bmaptool copy tmp/deploy/images/cn9130-cf-pro/coreos-image-full-cmdline-cn9130-cf-pro.wic.xz /dev/<DISKNAME>
+
+You have to replace `<DISKNAME>` by the name of your SD Card device.

documentation/ref-manual/classes.rst

@@ -0,0 +1,32 @@
+*******
+Classes
+*******
+
+This chapter document the classes that are provided by Belden CoreOS. Classes
+provided by OpenEmbedded-Core are documented in the Yocto Reference Manual.
+
+.. _ref-classes-coreos-metadata-scm:
+.. index:: coreos_metadata_scm.bbclass
+
+``coreos_metadata_scm.bbclass``
+===============================
+
+The ``coreos_metadata_scm`` class is used inside the CoreOS distribution
+configuration file to change the value of ``METADATA_BRANCH`` and
+``METADATA_REVISION`` to the current Git branch and revision of the main CoreOS
+repository instead of the branch and revision of the OpenEmbedded-Core Layer, as
+set by the :external:ref:`metadata_scm <ref-classes-metadata_scm>` class.
+
+The ``coreos_metadata_scm`` is automatically inherited if ``DISTRO`` is set to
+``belden-coreos`` or to any distro based on ``belden-coreos``.
+
+.. _ref-classes-coreos-image:
+.. index:: coreos_image.bbclass
+
+``coreos_image.bbclass``
+========================
+
+The ``coreos-image`` class provides common definitions for the
+``coreos-image-*`` image recipes, such as support for additional
+:extern:ref:`IMAGE_FEATURE <ref-features-image>`.
+

documentation/ref-manual/distro.rst

@@ -0,0 +1,54 @@
+.. index:: DISTRO
+
+******
+Distro
+******
+
+The CoreOS layer provide the following :term:`DISTRO`:
+
+.. _ref-distro-belden-coreos:
+.. index:: belden-coreos.conf
+
+``belden-coreos.conf``
+==================================
+
+This distro is the base distribution of the CoreOS project.
+
+This distro is automatically selected in the default ``build/conf/local.conf``
+created by the ``oe-init-build-env`` script. It is set in this file as follow::
+
+    DISTRO ?= "belden-coreos"
+
+This distribution is similar to Poky, the reference distribution of the Yocto
+Project. But with some change:
+
+
+:term:`SANITY_TESTED_DISTROS` is set to Debian 11, as it's the only host 
+operating system supported.
+
+The init system was changed to `SystemD` by setting `INIT_MANAGER` to
+`systemd`.
+
+Theses default :external:ref:`DISTRO_FEATURES <ref-features-distro>` are enabled:: 
+
+    bluetooth usbhost pci ipv4 ipv6 wifi multiarch usrmerge ptest
+
+.. note::
+
+    Distribution based on CoreOS must extend the CoreOS distro by having the
+    following line at the beginning of the distro configuration file::
+
+        require conf/distro/belden-coreos.conf
+
+    Example for ``conf/distro/custom-distro.conf``::
+
+        require conf/distro/belden-coreos.conf
+        DISTRO = "custom-distro"
+        DISTRO_NAME = "CustomDistro OS (Based on Belden CoreOS)"
+        MAINTAINER = "CustomDistro OS Team"
+
+    .. warning::
+
+        The ``belden-coreos`` distro define a sane set of default policies.
+        Distribution based on CoreOS can only be supported by the CoreOS team if
+        theses default policies and choices are not changed.

documentation/ref-manual/features.rst

@@ -0,0 +1,44 @@
+********
+Features
+********
+
+This chapter document the machine, distro and image feature that are specific
+to Belden CoreOS. 
+
+.. index:: MACHINE_FEATURES
+    
+Machine Features
+================
+
+CoreOS doesn't define any custom machine feature for now, but the 
+:external:ref:`MACHINE_FEATURES <ref-features-machine>` of OpenEmbedded-Core
+can be used.
+
+.. index:: DISTRO_FEATURES
+
+Distro Features
+===============
+
+CoreOS doesn't define any custom distro feature for now, but the 
+:external:ref:`DISTRO_FEATURES <ref-features-distro>` of OpenEmbedded-Core
+can be used.
+
+.. index:: IMAGE_FEATURES
+
+Image Features
+==============
+
+Some image features are available when you inherit the
+:ref:`coreos-image <ref-classes-coreos-image>` class. The current list of
+these features is as follows:
+
+-  *hwcodecs:* Installs hardware acceleration codecs.
+-  *tools-debug:* Installs debugging tools such as ``strace`` and ``gdb``.
+-  *tools-profile:* Installs profiling tools such as ``valgrind`` and ``perf``.
+-  *ssh-server:* Installs the Dropbear minimal SSH server.
+
+:external:ref:`IMAGE_FEATURES <ref-features-image>` defined in OpenEmbedded-Core
+are also available, but note that the
+:ref:`coreos-image <ref-classes-coreos-image>` class don't inherit from the
+:external:ref:`core-image <ref-classes-core-image>` class, thus `core-image`
+specific features are not available.

documentation/ref-manual/images.rst

@@ -0,0 +1,38 @@
+******
+Images
+******
+
+The CoreOS build system provides several examples image:
+
+.. index:: coreos-image-full-cmdline
+
+``coreos-image-full-cmdline``
+=============================
+
+ A console-only image with more full-featured Linux system functionality installed.
+
+.. index:: coreos-image-minimal
+
+``coreos-image-minimal``
+========================
+
+A small image just capable of allowing a device to boot.
+
+
+.. index:: coreos-image-minimal-dev
+
+``coreos-image-minimal-dev``
+============================
+
+A ``coreos-image-minimal`` image suitable for development work using the host.
+The image includes headers and libraries you can use in a host development
+environment.
+
+.. note::
+
+   :external:ref:`ref-manual/images:images` defined in OpenEmbedded-Core are also
+   available, but are not based on the :ref:`coreos-image
+   <ref-classes-coreos-image>` classes.
+
+   Custom image based on the :ref:`coreos-image <ref-classes-coreos-image>` classes
+   can be made in an application layers.

documentation/ref-manual/index.rst

@@ -0,0 +1,15 @@
+
+==============================
+Belden CoreOS Reference Manual
+==============================
+
+|
+
+.. toctree::
+   :caption: Table of Contents
+   :numbered:
+
+   classes
+   distro
+   images
+   features