=======
osbuild
=======

----------------------------------------------
Build-Pipelines for Operating System Artifacts
----------------------------------------------

:Manual section: 1
:Manual group: User Commands

SYNOPSIS
========

| ``osbuild`` [ OPTIONS ] MANIFEST
| ``osbuild`` [ OPTIONS ] -
| ``osbuild`` ``--help``
| ``osbuild`` ``--version``

DESCRIPTION
===========

**osbuild** is a build-system for operating system artifacts. It takes an input
manifest describing the build pipelines and produces file-system trees, images,
or other artifacts as output. Its pipeline description gives comprehensive
control over the individual steps to execute as part of a pipeline. **osbuild**
provides isolation from the host system as well as caching capabilities, and
thus ensures that pipeline builds will be deterministic and efficient.

OPTIONS
=======

**osbuild** reads the pipeline description from the file passed on the
command-line. To make **osbuild** read the pipeline description from standard
input, pass ``-``.

The following command-line options are supported. If an option is passed, which
is not listed here, **osbuild** will deny startup and exit with an error.

-h, --help                      print usage information and exit immediately
--version                       print version information and exit immediately
--store=DIR                     directory where intermediary file system trees
                                are stored
-l DIR, --libdir=DIR            directory containing stages, assemblers, and
                                the osbuild library
--cache-max-size=SIZE           maximum size of the cache (bytes) or 'unlimited'
                                for no restriction (size may include an optional
                                unit suffix, like kB, kiB, MB, MiB and so on)
--checkpoint=CHECKPOINT         stage to commit to the object store during
                                build (can be passed multiple times)
--export=OBJECT                 object to export (can be passed multiple times)
--json                          output results in JSON format
--output-directory=DIR          directory where result objects are stored
--inspect                       return the manifest in JSON format including
                                all the ids
--monitor=TYPE                  name of the monitor to be used
--monitor-fd=NUM                file-descriptor to be used for the monitor
--stage-timeout                 set the maximal time (in seconds) each stage is
                                allowed to run
--break, --break=ID             open debug shell when executing stages; accepts
                                stage name or id (from --inspect) or * (for all)

NB: If neither ``--output-directory`` nor ``--checkpoint`` is specified, no
attempt to build the manifest will be made.

MANIFEST
========

The input to **osbuild** is a description of the pipelines to execute, as well
as required parameters to each pipeline stage. This data must be *JSON*
encoded. It is read from the file specified on the command-line, or, if ``-``
is passed, from standard input.

The format of the manifest is described in ``osbuild-manifest``\(5). The formal
schema of the manifest is available online as the OSBuild JSON Schema [#]_.

MONITOR
=======

Live activity of the pipeline execution can be monitored via a built-in set
of different monitors. The ``--monitor=TYPE`` option selects the type of
monitor that is used. Valid types are:

``NullMonitor``
        No live coverage is reported and all monitoring features are disabled.
        This is the default monitor if ``--json`` was specified on the
        command-line.
``LogMonitor``
        A human-readable live monitor of the pipeline execution. This monitor
        prints pipeline names, stage names, and relevant options of each stage
        as it is executed. Additionally, timing information is provided for
        each stage. The output is not machine-readable and is interspersed
        with the individual log messages of the stages.
        This is the default monitor if ``--json`` was **not** specified.
``JSONSeqMonitor``
        A json-sequence (RFC7464) based live monitor of the pipeline execution.
	Each line contains valid json and a record-separator (0x1E) at the
	end. The json consists of a `progress` object that contains a
	`context` object describes the context of the progress and details
	about the progress. Progress can be nested and a progress object
	may contain sub-progress. In addition each progress can emit
	`message` strings that contain detailed log information from
	the stage. An example:

	| {
	|   "message": "Starting module org.osbuild.grub2.inst",
	|   "context": {
	|     "origin": "osbuild.monitor",
	|     "pipeline": {
	|       "name": "image",
	|       "id": "b3e63a8ef3cd30be244ffe1749af05783014bf2c61b2e45f09bb6df0ef122ad8",
	|       "stage": {
	|         "name": "org.osbuild.grub2.inst",
	|         "id": "b3e63a8ef3cd30be244ffe1749af05783014bf2c61b2e45f09bb6df0ef122ad8"
	|       }
	|     },
	|     "id": "747c04fa9265e7de79ac5efae43c62375f4b6bb778cb24abd7963dc181139176"
	|   },
	|   "progress": {
	|     "name": "pipelines/sources",
	|     "total": 4,
	|     "done": 3,
	|     "progress": {
	|       "name": "stages",
	|       "total": 7,
	|       "done": 6
	|     }
	|   },
	|   "timestamp": 1710318022.3872378
	| }

Monitor output is written to the file-descriptor provided via
``--monitor-fd=NUM``. If none was specified, standard output is used.

OUTPUT
======

OSBuild only ever builds the requested artifacts, rather than all artifacts
defined in a manifest. Each stage and pipeline has an associated ID (which can
be acquired by passing ``--inspect``). To export an artifact after a stage or
pipeline finished, pass its ID via ``--export=ID``. A sub-directory will be
created in the output-directory with the ID as the name. The contents of the
artifact are then stored in that sub-directory.

Additionally, any completed pipeline or stage can be cached to avoid rebuilding
them in subsequent invocations. Use ``--checkpoint=ID`` to request caching of a
specific stage or pipeline.

EXAMPLES
========

The following sub-sections contain examples on running **osbuild**. Generally,
**osbuild** must be run with superuser privileges, since this is required to
create file-system images.

Example 1: Run an empty pipeline
--------------------------------

To verify your **osbuild** setup, you can run it on an empty pipeline which
produces no output:

    |
    | # echo {} | osbuild -
    |

Example 2: See pipeline IDs of a Fedora qcow2 image
---------------------------------------------------

To inspect a basic qcow2 image of Fedora, use:

    |
    | # osbuild ./samples/fedora-boot.json
    |

The pipeline definition ``./samples/fedora-boot.json`` is provided in the
upstream source repository of **osbuild**.

This will print out the pipeline IDs of the provided manifest but will
not actually build anything because no artifact was requested. The pipeline
IDs can then be passed to ``--export=`` to actually get the requested
artifacts.


Example 3: Build a Fedora qcow2 image
-------------------------------------

To build a basic qcow2 image of Fedora, use:

    |
    | # osbuild --output-dir ./out --export image ./samples/fedora-boot.json
    |

Note that the command requires to be run as root. It will create an out/image
directory and put the generated "disk.img" there.

Example 4: Run from a local checkout
------------------------------------

To run **osbuild** from a local checkout, use:

    |
    | # python3 -m osbuild --libdir . --output-dir ./out --export image samples/fedora-boot.json
    |

This will make sure to execute the **osbuild** module from the current
directory, as well as use it to search for stages, assemblers, and more.

SEE ALSO
========

``osbuild-manifest``\(5), ``osbuild-composer``\(1)

NOTES
=====

.. [#] OSBuild JSON Schema v2:
       https://osbuild.org/schemas/osbuild2.json
