doc: document all the current feature of CoreOS

This commit is contained in:
Samuel Dolt 2022-09-30 11:36:29 +02:00
parent 614c12cdce
commit b93c75f8b8
16 changed files with 586 additions and 0 deletions

2
.gitignore vendored
View File

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

20
documentation/Makefile Normal file
View File

@ -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)

Binary file not shown.

After

Width:  |  Height:  |  Size: 20 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 36 KiB

112
documentation/conf.py Normal file
View File

@ -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"

View File

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

38
documentation/index.rst Normal file
View File

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

35
documentation/make.bat Normal file
View File

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

View File

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

View File

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

View File

@ -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.

View File

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

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

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