mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-08-24 00:15:57 +00:00
Formatting corrections to mixer doc for proper HTML build from RST.
This commit is contained in:
Tullis, Michael L
+41
-44
@@ -4,10 +4,10 @@ Mixer Tool
|
||||
##########
|
||||
|
||||
*Mixing* refers to composing an operating system for specific use cases.
|
||||
While the default ClearLinux provides options to install bundles for various
|
||||
server capabilities, some developers may wish to augment the operating system
|
||||
itself with functionality from their own packages, or to modify the structure of
|
||||
current bundles to cater to their particular needs.
|
||||
While the default Clear Linux* OS for Intel® Architecture provides options to install
|
||||
bundles for various server capabilities, some developers may wish to 1) augment the
|
||||
operating system itself with functionality from their own packages or 2) modify the
|
||||
structure of current bundles to cater to their particular needs.
|
||||
|
||||
|
||||
Current Workflow
|
||||
@@ -16,38 +16,37 @@ Current Workflow
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
To start working with the Mixer tools, you'll need a recent Clear Linux* image,
|
||||
and to have the following bundles installed. If you don't have them already,
|
||||
To start working with the Mixer tools, you'll need a recent image of Clear Linux OS for Intel Architecture
|
||||
with the following bundles installed. If you don't have them already,
|
||||
you can add them with the :command:`swupd bundle-add` command::
|
||||
|
||||
# swupd bundle-add mixer
|
||||
# swupd bundle-add mixer
|
||||
|
||||
To satisfy all dependencies (until further development), you'll need the
|
||||
following additional bundles::
|
||||
|
||||
# swupd bundle-add os-clr-on-clr os-core-dev
|
||||
# swupd bundle-add os-clr-on-clr os-core-dev
|
||||
|
||||
Mixing
|
||||
------
|
||||
|
||||
1. **Create a workspace**. Create an empty directory in your Clear image to
|
||||
#. **Create a workspace**. Create an empty directory in your Clear image to
|
||||
use as a "workspace" for mixing. For these steps, we assume your workspace
|
||||
location is :file:`/home/clr/mix`.
|
||||
|
||||
2. **Configure builder.conf**. Copy the template conf file:
|
||||
#. **Configure builder.conf**. Copy the template conf file::
|
||||
|
||||
``# cp /usr/share/defaults/bundle-chroot-builder/builder.conf /etc/bundle-chroot-builder/``
|
||||
# cp /usr/share/defaults/bundle-chroot-builder/builder.conf /etc/bundle-chroot-builder/`
|
||||
|
||||
Note there are different sections to the builder.conf. The [Builder] section
|
||||
provides the mixer tools with required configuration options, defining where
|
||||
generated bundles and update metadata should get published. The [swupd] section
|
||||
is used by swupd-server to create an update with the newly mixed content.
|
||||
|
||||
Edit the template configuration file according to your needs:
|
||||
Edit the template configuration file according to your needs::
|
||||
|
||||
# vim /etc/bundle-chroot-builder/builder.conf:
|
||||
|
||||
.. code-block:: console
|
||||
``# vim /etc/bundle-chroot-builder/builder.conf:``
|
||||
::
|
||||
[Builder]
|
||||
SERVER_STATE_DIR = /var/lib/update
|
||||
BUNDLE_DIR = /home/clr/mix/bundles
|
||||
@@ -62,14 +61,12 @@ Mixing
|
||||
FORMAT=1 ### Can be any number.
|
||||
# See 'OS Epoch' discussion for details
|
||||
|
||||
|
||||
|
||||
The file `builder.conf` will be read automatically from ``/etc/bundle-chroot-builder``,
|
||||
but all of the scripts accept a :option:`-c/--config` option to specify where
|
||||
the file is, should you want to store it elsewhere. The :file:`.yum-mix.conf`
|
||||
file will be auto-generated for you.
|
||||
|
||||
3. **Generate the starting point for your Mixer**. In your workspace, run::
|
||||
#. **Generate the starting point for your Mixer**. In your workspace, run::
|
||||
|
||||
# ./mixer-init-mix.sh -c /etc/bundle-chroot-builder/builder.conf
|
||||
|
||||
@@ -80,7 +77,7 @@ Mixing
|
||||
This step auto-generates that first version 10 for you, so you can focus
|
||||
on just your custom mix.
|
||||
|
||||
4. **Create/locate RPMs for mix.**. (Steps 4-6 are necessary only if you
|
||||
#. **Create/locate RPMs for mix.**. (Steps 4-6 are necessary only if you
|
||||
want to add your own RPMs to the Mix. If you are simply working with Clear
|
||||
only bundles, then skip to Step 7.)
|
||||
|
||||
@@ -88,38 +85,38 @@ Mixing
|
||||
:command:`mock`, :command:`rpmbuild`, etc. to build them. If they are not
|
||||
built on Clear, make sure your configuration builds them correctly for Clear.
|
||||
|
||||
5. **Import RPMs into workspace**. The easiest way to do this is to create a
|
||||
#. **Import RPMs into workspace**. The easiest way to do this is to create a
|
||||
``results`` directory in your workspace *ala* ``/home/clr/mix/results``,
|
||||
and to copy the RPMs you want into that directory. The mixer script will
|
||||
look here for RPMs needed to build a local RPM repo for yum to use.
|
||||
|
||||
6. **Create a local RPM repo**. Create an empty directory in your workspace
|
||||
#. **Create a local RPM repo**. Create an empty directory in your workspace
|
||||
name ``local`` and run::
|
||||
|
||||
# mixer-add-rpms.sh --rpmdir results --repodir local
|
||||
# mixer-add-rpms.sh --rpmdir results --repodir local
|
||||
|
||||
After the script exits, you should see your RPMs and a repodata directory in
|
||||
``/home/clr/mix/local``. If the RPMs are not all in the local directory, check
|
||||
to make sure that they are indeed valid RPM files and not corrupt.
|
||||
|
||||
7. **Initialize Clear/Mix version info**. In the workspace, run::
|
||||
#. **Initialize Clear/Mix version info**. In the workspace, run::
|
||||
|
||||
# mixer-init-versions.sh -m 20
|
||||
# mixer-init-versions.sh -m 20
|
||||
|
||||
This takes the Clear version from your image (or override it with
|
||||
``-c/--clear-version`` to use another Clear build's content), and uses
|
||||
"20" for the mix version.
|
||||
|
||||
8. **Download Bundles**. Download ``clr-bundles``. In the workspace,
|
||||
#. **Download Bundles**. Download ``clr-bundles``. In the workspace,
|
||||
run::
|
||||
|
||||
# mixer-update-bundles.sh
|
||||
# mixer-update-bundles.sh
|
||||
|
||||
This creates a ``.repos`` directory with git repos that are needed for
|
||||
later steps; it also creates a ``bundles/`` directory (symlink) in your
|
||||
workspace, which contains the bundle definitions for the mix.
|
||||
|
||||
9. **Update bundle definitions**. The mixer uses a local clone of the
|
||||
#. **Update bundle definitions**. The mixer uses a local clone of the
|
||||
``clr-bundles`` repo to define bundles for the mix.
|
||||
|
||||
To define your bundles:
|
||||
@@ -143,16 +140,16 @@ Mixing
|
||||
name(s) in that bundle definition file to tell it what package(s)
|
||||
must be installed as part of that bundle.
|
||||
|
||||
10. **Build the bundle chroots** To build all of the ``chroots``
|
||||
#. **Build the bundle chroots** To build all of the ``chroots``
|
||||
that are based on the bundles you defined, in your workspace run::
|
||||
|
||||
# mixer-build-chroots.sh
|
||||
# mixer-build-chroots.sh
|
||||
|
||||
If you have many bundles defined for your mix, this step may take some time.
|
||||
|
||||
11. **Create update**. In the workspace, run::
|
||||
#. **Create update**. In the workspace, run::
|
||||
|
||||
# mixer-create-update.sh
|
||||
# mixer-create-update.sh
|
||||
|
||||
When the script completes, you'll find your mix update content under
|
||||
``/var/lib/update/www/VER``, in this example, it will be located in
|
||||
@@ -162,18 +159,18 @@ Mixing
|
||||
OS Epoch or Format version
|
||||
--------------------------
|
||||
|
||||
The "format" used in builder.conf might be more precisely referred to as an
|
||||
OS "compatibility epoch". Versions of the OS within a given epoch are fully
|
||||
compatible with themselves. Across the epoch boundary _something_ has
|
||||
changed in the OS. This change is impactful enough that release where the
|
||||
change has taken place must be visited, to ensure operations occur in the
|
||||
correct order. A format increment is the way we insure pre- and co-requisite
|
||||
changes flow out with proper ordering.
|
||||
The "format" used in builder.conf might be more precisely referred to as an
|
||||
OS "compatibility epoch". Versions of the OS within a given epoch are fully
|
||||
compatible with themselves. Across the epoch boundary _something_ has
|
||||
changed in the OS. This change is impactful enough that release where the
|
||||
change has taken place must be visited, to ensure operations occur in the
|
||||
correct order. A format increment is the way we insure pre- and co-requisite
|
||||
changes flow out with proper ordering.
|
||||
|
||||
From an update perspective, the format, or compatibility epoch, limits the
|
||||
extent to which the client can be updated in a single step.
|
||||
From an update perspective, the format, or compatibility epoch, limits the
|
||||
extent to which the client can be updated in a single step.
|
||||
|
||||
For the creation of a custom mix, the format version should start at '1',
|
||||
or some known number, and increment only when a compatibility breakage is
|
||||
introduced. Normal updates, updating a software package for example,
|
||||
do not require a format increment.
|
||||
For the creation of a custom mix, the format version should start at '1',
|
||||
or some known number, and increment only when a compatibility breakage is
|
||||
introduced. Normal updates, updating a software package for example,
|
||||
do not require a format increment.
|
||||
Reference in New Issue
Block a user