Commit 94e4b0b6 authored by Paul Barker's avatar Paul Barker

Merge branch 'pbarker/ci' into 'master'

CI improvements, layer updates & import of documentation

See merge request !5
parents d0954b88 035545e7
Pipeline #51170677 (#109) passed with stage
in 10 minutes and 3 seconds
......@@ -7,6 +7,7 @@
/build/pub
/build/buildhistory
/ci/report.xml
/docs/_build
/.vscode
__pycache__
*.log
variables:
GIT_SUBMODULE_STRATEGY: recursive
stages:
- build
before_script:
- ./patches/apply.sh
qemux86:
stage: build
script:
- ./ci/run.py ${CI_BUILD_REF_SLUG}_$(date -I) qemux86
artifacts:
paths:
- build/pub
expire_in: 1 week
raspberrypi3:
stage: build
script:
- ./ci/run.py ${CI_BUILD_REF_SLUG}_$(date -I) raspberrypi3
artifacts:
paths:
- build/pub
expire_in: 1 week
raspberrypi3-64:
stage: build
script:
- ./ci/run.py ${CI_BUILD_REF_SLUG}_$(date -I) raspberrypi3-64
artifacts:
paths:
- build/pub
expire_in: 1 week
beaglebone-yocto:
stage: build
script:
- ./ci/run.py ${CI_BUILD_REF_SLUG}_$(date -I) beaglebone-yocto
artifacts:
paths:
- build/pub
expire_in: 1 week
docs-html:
stage: build
script:
- cd docs
- make html
artifacts:
paths:
- docs/_build/html
expire_in: 1 week
docs-pdf:
stage: build
script:
- cd docs
- make latexpdf
artifacts:
paths:
- docs/_build/latex/*.pdf
expire_in: 1 week
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " applehelp to make an Apple Help Book"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
@echo " coverage to run coverage check of the documentation (if enabled)"
.PHONY: clean
clean:
rm -rf $(BUILDDIR)/*
.PHONY: html
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
.PHONY: dirhtml
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
.PHONY: singlehtml
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
.PHONY: pickle
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
.PHONY: json
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
.PHONY: htmlhelp
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
.PHONY: qthelp
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/OryxLinux.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/OryxLinux.qhc"
.PHONY: applehelp
applehelp:
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
@echo
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
@echo "N.B. You won't be able to view it unless you put it in" \
"~/Library/Documentation/Help or install it in your application" \
"bundle."
.PHONY: devhelp
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/OryxLinux"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/OryxLinux"
@echo "# devhelp"
.PHONY: epub
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
.PHONY: latex
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
.PHONY: latexpdf
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
.PHONY: latexpdfja
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
.PHONY: text
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
.PHONY: man
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
.PHONY: texinfo
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
.PHONY: info
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
.PHONY: gettext
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
.PHONY: changes
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
.PHONY: linkcheck
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
.PHONY: doctest
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
.PHONY: coverage
coverage:
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
@echo "Testing of coverage in the sources finished, look at the " \
"results in $(BUILDDIR)/coverage/python.txt."
.PHONY: xml
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
.PHONY: pseudoxml
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
This diff is collapsed.
This diff is collapsed.
==================================
Oryx Linux |version| documentation
==================================
.. toctree::
:maxdepth: 2
intro
release-history
using-oryx-linux
oryx-apps
building-images
.. only:: html
Indices and tables
==================
* :ref:`search`
============
Introduction
============
Summary
=======
This documentation covers the |version| version of Oryx Linux.
Oryx Linux is a Linux® distribution targeted at embedded applications and based
on the work of `The Yocto Project <https://www.yoctoproject.org/>`_ and
`OpenEmbedded <https://www.openembedded.org/>`_.
Motivation
==========
The Oryx Linux project is primarily motivated by a desire to incorporate a
lightweight Linux container implementation into the OpenEmbedded build system
whilst maintaining the benefits of both systems. The key word here is
‘lightweight’: we’re avoiding fully-integrated systems such as Docker which are
targeted at cloud computing deployments rather than embedded deployments.
Instead we’re using ``runc``, the lightweight container runtime which sits at
the heart of Docker, without any of the surrounding tools such as
``containerd`` and ``docker`` itself. This gives us the flexibility to address
the needs of the embedded use-case.
One of the main aims of this project is to provide a developer workflow which
is familiar to existing OpenEmbedded users. You should not be required to learn
a new build system or method of creating images (such as Docker and its
corresponding Dockerfile syntax) in order to incorporate the benefits of
containers into an embedded Linux product. Keeping the focus on the
OpenEmbedded workflow ensures that we retain all the benefits of this system,
such as the excellent license compliance tooling, the extensible SDK and a
proper cross-compilation environment. Other methods of creating container-based
Linux systems are typically targeted at cloud computing deployments and don’t
address these issues that crop up when shipping an embedded Linux product.
The benefits of Linux containers have been discussed at length elsewhere so we
won’t cover the general benefits here. However, it’s worth mentioning the
additional benefits that we get in the embedded world:
* The ability to isolate applications requiring access to specialised hardware
from those which just use ‘normal’ Linux interfaces such as the network and
filesystems.
* The ability to mix legacy software which is dependent on specific older
versions of system libraries with an up-to-date and secure base system. This
is especially relevant in the embedded space where legacy applications abound.
* The ability to update and restart a full application stack cleanly and
quickly by restarting a container guest instead of rebooting the whole device.
For devices with long startup times there can be significant benefit here.
Support
=======
For support requests, bug reports or other feedback please open an issue in the
`Togán Labs bug tracker <https://bugs.toganlabs.com/>`_ or contact us at
`support@toganlabs.com <support@toganlabs.com>`_.
Notation
========
The following notation is used for arguments:
* ``ARGUMENT``: A required argument.
* ``[ARGUMENT]``: An optional argument.
* ``ARGUMENTS...``: One or more required arguments which are not parsed
further by ``oryxcmd``. This is typically used for arguments which are
passed through to another application.
Copyright and Trademark notices
===============================
.. image:: cc_by.png
:alt: Creative Commons Attribution 4.0 International License
:align: center
This work is licensed under a `Creative Commons Attribution 4.0 International
License <https://creativecommons.org/licenses/by/4.0/>`_.
Linux® is the registered trademark of Linus Torvalds in the U.S. and other
countries.
=========
oryx-apps
=========
oryx-apps is a collection of applications which implement the core functionality
of the Oryx Linux distro. However, oryx-apps is also available independently of
Oryx Linux and so these applications may be re-used and integrated into other
Linux distros if desired.
.. _oryxcmd:
oryxcmd
=======
``oryxcmd`` is the core of the "host" application profile within Oryx Linux. It
is responsible for the management of guest containers and the sources from which
container images may be obtained. As a command-line application it has both an
interactive mode and a non-interactive mode.
Interactive Mode
----------------
In the interactive mode, ``oryxcmd`` is started without specifying a command::
$ oryxcmd
Welcome to oryxcmd (oryx-apps v0.2.4)
oryxcmd>
At the ``oryxcmd`` prompt, any of the supported `Commands`_ may be executed. For
example::
oryxcmd> list_sources
oryx
To leave interactive mode, use the ``exit`` command::
oryxcmd> exit
Non-interactive Mode
--------------------
In the non-interactive mode, ``oryxcmd`` is executed with a command specified as
an argument. The specified command will be executed and then ``oryxcmd`` will
exit. For example::
$ oryxcmd list_sources
oryx
Any of the supported `Commands`_ may be executed in this way.
Command Line Arguments
----------------------
The following command line arguments are supported by ``oryxcmd``:
* ``-v``, ``--verbose``: Print verbose debug messages during operation. This
argument is usable for both interactive and non-interactive mode.
* ``-h``, ``--help``: Print help messages and exit.
* ``-V``, ``--version``: Print version string and exit.
Commands
--------
add_source
++++++++++
Register a new source from which images may be fetched.
Usage::
add_source NAME URL
Arguments:
* ``NAME``: An identifier which may be used to reference this source in future
commands.
* ``URL``: The root URL under which image archives may be found.
Example::
oryxcmd> add_source oryx http://downloads.toganlabs.com/oryx/distro/0.4.0/raspberrypi3
Added source "oryx" with URL "http://downloads.toganlabs.com/oryx/distro/0.4.0/raspberrypi3"
remove_source
+++++++++++++
Remove a previously registered source.
Usage::
remove_source NAME
Arguments:
* ``NAME``: The identifier of the source to remove.
Example::
oryxcmd> remove_source oryx
Removed source "oryx"
list_sources
++++++++++++
List all currently registered sources.
Usage::
list_sources
This command has no arguments.
Example::
oryxcmd> list_sources
oryx
show_source
+++++++++++
Show details of a previously registered source in JSON format.
Usage::
show_source NAME
Arguments:
* ``NAME``: The identifier of the source to show.
Example::
oryxcmd> show_source oryx
{
"url": "http://downloads.toganlabs.com/oryx/distro/0.4.0/raspberrypi3"
}
add_guest
+++++++++
Create a new guest container from an image.
Usage::
add_guest NAME IMAGE
Arguments:
* ``NAME``: An identifier which may be used to reference this source in future
commands.
* ``IMAGE``: A fully-qualified reference to an image which is available from one
of the sources which has been configured. The format of this reference is
``<source>:<image_name>``:
- ``source``: The identifier of a registered source.
- ``image_name``: The name of an image which is available within the
identified source. The image name typically matches the name of an
:ref:`Application Profile<application_profiles>` which has been built for
the system on which ``oryxcmd`` is running.
Example::
oryxcmd> add_guest test oryx:minimal
Added guest "test" from image "oryx:minimal"
remove_guest
++++++++++++
Delete an existing guest container.
Usage::
remove_guest NAME
Arguments:
* ``NAME``: The identifier of the guest container to remove.
Example::
oryxcmd> remove_guest test
Removed guest "test"
list_guests
+++++++++++
List all currently registered guests.
Usage::
list_guests
This command has no arguments.
Example::
oryxcmd> list_guests
test
show_guest
++++++++++
Show details of a previously registered guest in JSON format.
Usage::
show_guest NAME
Arguments:
* ``NAME``: The identifier of the guest to show.
Example::
oryxcmd> show_guest test
{
"autostart_enabled": 0,
"image": {
"APPLICATION_PROFILE": "minimal",
"COMMAND": "/bin/sh",
"DISTRO": "oryx",
"MACHINE": "raspberrypi3",
"ROOTFS": "oryx-guest-minimal-raspberrypi3.tar.xz",
"SYSTEM_PROFILE": "guest",
"VERSION": "0.4.0"
},
"image_name": "minimal",
"path": "/var/lib/oryx-guests/test",
"source": {
"url": "http://downloads.toganlabs.com/oryx/distro/0.4.0/raspberrypi3"
},
"source_name": "oryx"
}
enable_guest
++++++++++++
Enable auto-start of a previously registered guest during system boot.
Usage::
enable_guest NAME
Arguments:
* ``NAME``: The identifier of the guest to enable.
Example::
oryxcmd> enable_guest test
Enabled guest "test"
disable_guest
+++++++++++++
Disable auto-start of a previously registered guest during system boot.
Usage::
disable_guest NAME
Arguments:
* ``NAME``: The identifier of the guest to disable.
Example::
oryxcmd> disable_guest test
Disabled guest "test"
start_guest
+++++++++++
Start an existing guest container. The container is launched in the background,
without access to the terminal where start_guest was executed.
Usage::
start_guest NAME
Arguments:
* ``NAME``: The identifier of the guest container to start.
Example::
oryxcmd> start_guest test
Started guest "test"
stop_guest
++++++++++
Stop a running guest container. SIGTERM is sent to the container so that it can
shutdown cleanly. After 10 seconds, the container is halted.
Usage::
stop_guest NAME
Arguments:
* ``NAME``: The identifier of the guest container to stop.
Example::
oryxcmd> stop_guest test
Stopped guest "test"
autostart_all
+++++++++++++
Start all containers which have autostart enabled.
Usage::
autostart_all
This command has no arguments.
Example::
oryxcmd> autostart_all
Started guest "test"
Autostart all enabled guests complete
autostop_all
++++++++++++
Stop all currently running containers.
Usage::
autostop_all
This command has no arguments.
Example::
oryxcmd> autostop_all
Stopped guest "test"
Autostop all running guests complete
runc
++++
Execute ``runc`` for an existing guest container. See the documentation of
``runc`` for further details.
Usage::
runc NAME ARGS...
Arguments:
* ``NAME``: The identifier of the guest container for which 'runc' will be
executed.
* ``ARGS...``: Command line arguments passed through to the 'runc' application.
help
++++
List available commands with "help" or detailed help with "help cmd".
Usage::
help [CMD]
Arguments:
* ``CMD``: The name of a supported command. If this argument is given, detailed
help for the chosen command is printed.
Example::