diff --git a/.gitignore b/.gitignore index 6678c81..8fb193c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,4 @@ build/ vscode-bitbake-build/ +documentation/_build/ + diff --git a/documentation/Makefile b/documentation/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/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) diff --git a/documentation/_static/logo.png b/documentation/_static/logo.png new file mode 100644 index 0000000..2e38e20 Binary files /dev/null and b/documentation/_static/logo.png differ diff --git a/documentation/_static/logo2.png b/documentation/_static/logo2.png new file mode 100644 index 0000000..0f4c565 Binary files /dev/null and b/documentation/_static/logo2.png differ diff --git a/documentation/conf.py b/documentation/conf.py new file mode 100644 index 0000000..29b946e --- /dev/null +++ b/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" diff --git a/documentation/genindex.rst b/documentation/genindex.rst new file mode 100644 index 0000000..a4af06f --- /dev/null +++ b/documentation/genindex.rst @@ -0,0 +1,3 @@ +===== +Index +===== diff --git a/documentation/index.rst b/documentation/index.rst new file mode 100644 index 0000000..782bcfc --- /dev/null +++ b/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 ` and use the +same structures. + +| + +.. toctree:: + :maxdepth: 1 + :caption: Introduction and Overview + + Quick Build + +.. toctree:: + :maxdepth: 1 + :caption: Manuals + + Reference Manual + +.. toctree:: + :maxdepth: 1 + :caption: Indexes + :hidden: + + Releases + Glossary diff --git a/documentation/make.bat b/documentation/make.bat new file mode 100644 index 0000000..2119f51 --- /dev/null +++ b/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 diff --git a/documentation/migration-guides/index.rst b/documentation/migration-guides/index.rst new file mode 100644 index 0000000..ec8a104 --- /dev/null +++ b/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 diff --git a/documentation/migration-guides/release-master.rst b/documentation/migration-guides/release-master.rst new file mode 100644 index 0000000..f8d33ae --- /dev/null +++ b/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 ` diff --git a/documentation/quick-build.rst b/documentation/quick-build.rst new file mode 100644 index 0000000..76e957b --- /dev/null +++ b/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 `_. + +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 `_ and you can access `the core-os repository + `_. 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 `_ +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/ + +You have to replace `` by the name of your SD Card device. diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst new file mode 100644 index 0000000..a0a85d2 --- /dev/null +++ b/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 ` 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 `. + diff --git a/documentation/ref-manual/distro.rst b/documentation/ref-manual/distro.rst new file mode 100644 index 0000000..60f6ff4 --- /dev/null +++ b/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 ` 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. diff --git a/documentation/ref-manual/features.rst b/documentation/ref-manual/features.rst new file mode 100644 index 0000000..038b50f --- /dev/null +++ b/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 ` 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 ` of OpenEmbedded-Core +can be used. + +.. index:: IMAGE_FEATURES + +Image Features +============== + +Some image features are available when you inherit the +:ref:`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 ` defined in OpenEmbedded-Core +are also available, but note that the +:ref:`coreos-image ` class don't inherit from the +:external:ref:`core-image ` class, thus `core-image` +specific features are not available. diff --git a/documentation/ref-manual/images.rst b/documentation/ref-manual/images.rst new file mode 100644 index 0000000..64debb8 --- /dev/null +++ b/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 + ` classes. + + Custom image based on the :ref:`coreos-image ` classes + can be made in an application layers. diff --git a/documentation/ref-manual/index.rst b/documentation/ref-manual/index.rst new file mode 100644 index 0000000..9edf112 --- /dev/null +++ b/documentation/ref-manual/index.rst @@ -0,0 +1,15 @@ + +============================== +Belden CoreOS Reference Manual +============================== + +| + +.. toctree:: + :caption: Table of Contents + :numbered: + + classes + distro + images + features