=======
osbuild
=======
----------------------------------------------
Build-Pipelines for Operating System Artifacts
----------------------------------------------
:Manual section: 1
:Manual group: User Commands
SYNOPSIS
========
| ``osbuild`` [ OPTIONS ] PIPELINE
| ``osbuild`` [ OPTIONS ] -
| ``osbuild`` ``--help``
DESCRIPTION
===========
**osbuild** is a build-system for operating system artifacts. It takes a
pipeline description as input 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
--store=DIR directory where intermediary file system trees
are stored
--sources=PATH json file containing a dictionary of source
configuration
--secrets=PATH json file containing a dictionary of secrets
that are passed to sources
-l DIR, --libdir=DIR directory containing stages, assemblers, and
the osbuild library
--checkpoint=CHECKPOINT stage to commit to the object store during
build (can be passed multiple times)
--json output results in JSON format
--output-directory=DIR directory where result objects are stored
MANIFEST
========
The input to **osbuild** is a description of the pipeline 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 [#]_.
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 1: Build a Fedora 30 qcow2 image
----------------------------------------
To build a basic qcow2 image of Fedora 30, use:
|
| # osbuild ./samples/base-qcow2.json
|
The pipeline definition ``./samples/base-rpm-qcow2.json`` is provided in the
upstream source repository of **osbuild**.
Example 2: Run from a local checkout
------------------------------------
To run **osbuild** from a local checkout, use:
|
| # python3 -m osbuild --libdir . samples/base-rpm-qcow2.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:
https://osbuild.org/schemas/osbuild1.json