Similar to rd.break for dracut this allows a user to specify:
- --break or --break=*
- to get a shell before each stage is run
- --break=stage.name
- to get a shell each time the stage with that name is run
- example: --break=org.osbuild.copy
- --break=stage.id
- to get a shell each time the stage with that ID is run
- get the ID for the stages for your manifest by running
osbuild on the manifest with --inspect
- example: --break=dc6e3a66fef3ebe7c815eb24d348215b9e5e2ed0cd808c15ebbe85fc73181a86
and get a bash shell where they can inspect the environment to debug
and develop OSBuild stages.
The existing man-page is a bit misleading as it claims that the
command in the example will generate an image. Because osbuild
generates what is requested this is not actually true. This
commit tweaks the examples a bit to make them more useful. It
also fixes a numbering bug (we had two "Example 1").
It also tweaks the description of `fedora-boot.json` as it is no
longer fedora 34 but 38.
The file `./samples/base-qcow2.json` used in the osbuild.1.rst
man-page does no longer exists. It was removed in e92b409 and
`samples` is now a symlink into the test data. The closest in
the test data to the original `base-qcow2.json` seems to be
the `fedora-boot.json` so this is now used in the examples
section.
This removes the references to `./samples/base-rpm-qcow2.json`
which was remove in fe95d93. Here `fedora-boot.json` is also
used.
Integrate the recently added file system cache `FsCache` into our
object store `ObjectStore`. NB: This changes the semantics of it:
previously a call to `ObjectStore.commit` resulted in the object
being in the cache (i/o errors aside). But `FsCache.store`, which
is now the backing store for objects, will only commit objects if
there is enough space left. Thus we cannot rely that objects are
present for reading after a call to `FsCache.store`. To cope with
this we now always copy the object into the cache, even for cases
where we previously moved it: for the case where commit is called
with `object_id` matching `Object.id`, which is the case for when
`commit` is called for last stage in the pipeline. We could keep
this optimization but then we would have to special case it and
not call `commit` for these cases but only after we exported all
objects; or in other words, after we are sure we will never read
from any committed object again. The extra complexity seems not
worth it for the little gain of the optimization.
Convert all the tests for the new semantic and also remove a lot
of them that make no sense under this new paradigm.
Add a new command line option `--cache-max-size` which will set
the maximum size of the cache, if specified.
Update osbuild(1) to reflect changes of the last year. In particular,
we want to document behavior of the v2-manifest and only silently
continue to support v1-manifests.
Lets also introduce new chapters on output control, caching support,
and monitoring.
Signed-off-by: David Rheinsberg <david.rheinsberg@gmail.com>
The `--inspect` option is documented in the osbuild usage, but not in
the man page. This makes it harder for new users to find it and use it
for figuring out stage IDs necessary for checkpoints.
Signed-off-by: Tomas Hozza <thozza@redhat.com>
This was deprecated in favor of always having the source in the
manifest. Remove the command line option and the corresponding
code that would override the sources definitions.
Update the docs accordingly.
Drop the --build-env command-line argument. It is not used by anything.
Furthermore, our manifests now allow embedding build-environments, so
there is little reason to continue supporting this.
Add a new output-directory argument which specifies where to store
result objects. For now, this is purely optional and simply copies from
the old `output_id` into the specified directory. This allows a
backwards compatible transition towards removing any external access to
the osbuild cache.
Note that this has still lots of room for improvements:
* We only support assembler-output for now, but we could also easily
support entire trees as output, in case no assembler was selected.
Alternatively, we could introduce a "copy" assembler, that just
outputs the input tree.
* This parameter is optional, but should really be mandatory. There
is little reason to have the default behavior just dropping any
generated content. This would be a breaking change, though.
* We could move data out of a temporary object-store entry, rather
than copy it. But again, for backwards-compatibility, we leave the
latest store-object intact and do not move things out of it.
* We could now transition towards never committing anything to the
store, not even output IDs, unless explicitly checkpointed.
The used format of `-X, --long=VALUE` is not a valid option-list entry,
even though it is very commonly used all over the linux man-pages. Use
the supported format of `-X VALUE, --long=VALUE`, which will format
correctly in the man-page and html outputs.
For reference, these formats are valid in RST option-lists:
-a Short option
-c arg Short option with arg.
--long Long option.
-2, --two Aliases on a single line.
-f FILE, --file=FILE Aliases with arguments.
/V VMS/DOS-style option.
This rips out the `PIPELINE` section from osbuild(1) and instead adds a
new osbuild-manifest(5) man-page. This new man-page contains a rather
formal definition of the manifest, with a separate section for each
part of a manifest.
The man-page is exhaustive, in that it describes all available options.
However, it does *NOT* document the available stages, runners, and
assemblers. It does document the available (and supported) sources.
This should serve as an example how to document available stages and
assemblers in the future.
Note that it is not clear whether we should document these right now.
Once we decided to support the available stages for a reasonable
time-frame, we can start on documenting them as well.
This extends the EXAMPLES section with more examples, reduces their
complexity, and also restructures the layout to make it nicer to read
in the resulting TROFF file.
This adds a man-page `osbuild(1)` which documents the `osbuild`
executable. We use the python-native doc-utils and rely on
reStructuredText as documentation language.
While it is common with python libraries to use sphinx for documenting
the project, this commit explicitly does not import a full sphinx
documentation. Instead, it only adds the `rst` sources for man-pages.
These can be built by distributions via a simple:
rst2man docs/<manpage>.rst docs/<output-file>
