mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-11-22 03:22:45 +00:00
copy edit and language cleanup
Signed-off-by: Ecouzens <evan.couzens@intel.com>
This commit is contained in:
@@ -3,18 +3,18 @@
|
||||
Use mixer tool
|
||||
##############
|
||||
|
||||
*Mixing* refers to composing an operating system for specific use cases. While
|
||||
the default |CLOSIA| provides options to install bundles for various server
|
||||
capabilities, some developers may wish to either augment the operating system
|
||||
itself with functionality from their own packages or modify the structure of
|
||||
current bundles to cater to their particular needs.
|
||||
*Mixing* refers to composing an operating system for specific use cases.
|
||||
While the default |CLOSIA| provides options to install bundles for various
|
||||
server capabilities, some developers may wish to either augment the
|
||||
operating system itself with functionality from their own packages or modify
|
||||
the structure of current bundles to cater to their particular needs.
|
||||
|
||||
Prerequisites
|
||||
*************
|
||||
|
||||
To start working with the mixer tools, you need a recent image of |CL| with
|
||||
the `mixer` bundle installed. If the bundle is not yet installed, you can add it
|
||||
with the :command:`swupd bundle-add` command as follows:
|
||||
the `mixer` bundle installed. If the bundle is not yet installed, you can
|
||||
add it with the :command:`swupd bundle-add` command as follows:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -56,8 +56,8 @@ these workflows.
|
||||
Create a workspace
|
||||
******************
|
||||
|
||||
Create an empty directory in your |CL| image to use as a **workspace** for
|
||||
mixing with the following command:
|
||||
Use the following command to create an empty directory in your |CL| image to
|
||||
use as a **workspace** for mixing:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -74,14 +74,15 @@ In your workspace, initialize mixer with the following command:
|
||||
|
||||
sudo mixer init
|
||||
|
||||
This command initializes your workspace for you to make a mix at version 10
|
||||
This command initializes your workspace so you can make a mix at version 10
|
||||
based on the latest released upstream |CL| version. If a :file:`builder.conf`
|
||||
file is not already present in your workspace, mixer creates a default configuration
|
||||
file along with several version and tracking files and two bundle directories:
|
||||
:file:`local-bundles` and :file:`upstream-bundles`.
|
||||
file is not already present in your workspace, mixer creates a default
|
||||
configuration file, several version and tracking files, and two bundle
|
||||
directories: :file:`local-bundles` and :file:`upstream-bundles`.
|
||||
|
||||
If you wish to start with a different version of upstream |CL| or a
|
||||
different initial mix version, these options can be specified as flags, for example:
|
||||
different initial mix version, you can specify these options as flags.
|
||||
For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -89,29 +90,29 @@ different initial mix version, these options can be specified as flags, for exam
|
||||
|
||||
|
||||
Additionally, to build a mix with your own custom RPMs, use the optional
|
||||
:option:`--local-rpms` flag, for example:
|
||||
:option:`--local-rpms` flag. For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer init --local-rpms
|
||||
|
||||
This command creates the :file:`local-yum` and :file:`local-rpms` directories in your
|
||||
mix workspace and adds their paths to the generated :file:`builder.conf`. For more
|
||||
information on using these directories or setting them up manually, see
|
||||
`Create or locate RPMs for the mix`_.
|
||||
This command creates the :file:`local-yum` and :file:`local-rpms`
|
||||
directories in your mix workspace and adds their paths to the generated
|
||||
:file:`builder.conf`. For more information on using these directories or
|
||||
setting them up manually, see `Create or locate RPMs for the mix`_.
|
||||
|
||||
If all upstream |CL| bundles are part of the mix, you can easily add them all
|
||||
during initialization with the optional :option:`--all-upstream` flag, for
|
||||
during initialization with the optional :option:`--all-upstream` flag. For
|
||||
example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer init --all-upstream
|
||||
|
||||
Finally, you may want to track the contents of your mixer workspace with a Git
|
||||
repository. This is a great way to track changes to your mix's content or to
|
||||
revert to earlier versions if something goes wrong. Mixer can set this up
|
||||
automatically with the optional :option:`--git` flag, for example:
|
||||
Finally, you may want to track the contents of your mixer workspace with a
|
||||
git repository. This is a great way to track changes to your mix's content
|
||||
or to revert to earlier versions if something goes wrong. Mixer can set this
|
||||
up automatically with the optional :option:`--git` flag. For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -127,13 +128,13 @@ automatically with the optional :option:`--git` flag, for example:
|
||||
Edit builder.conf
|
||||
*****************
|
||||
|
||||
To configure the mixer tool, you must edit the :file:`builder.conf` as needed.
|
||||
To configure the mixer tool, edit the :file:`builder.conf` as needed.
|
||||
|
||||
The file :file:`builder.conf` is read automatically from the current workspace
|
||||
directory. Use the :option:`--config` flag during initialization to specify a
|
||||
alternate path to the file as needed.
|
||||
The file :file:`builder.conf` is read automatically from the current
|
||||
workspace directory. Use the :option:`--config` flag during initialization
|
||||
to specify an alternate path to the file as needed.
|
||||
|
||||
The :file:`builder.conf` file has different sections, for example:
|
||||
The :file:`builder.conf` file has different sections. For example:
|
||||
|
||||
* The `[Builder]` section provides the mixer tools with the required
|
||||
configuration options. This section defines the path where the generated
|
||||
@@ -179,17 +180,19 @@ The following variables require further explanation:
|
||||
|
||||
* The `LOCAL_BUNDLE_DIR` variable sets the path where mixer stores the local
|
||||
bundle definition files. These bundle definition files include any new,
|
||||
original bundles you create and edited versions of upstream |CL| bundles.
|
||||
original bundles you create, along with any edited versions of upstream
|
||||
|CL| bundles.
|
||||
|
||||
* The `SERVER_STATE_DIR` variable sets the path for the output of the mix
|
||||
content. Mixer automatically creates the path for you but the path can be
|
||||
content. Mixer automatically creates the path for you, but the path can be
|
||||
set to any location. In this example, we use the workspace directory.
|
||||
|
||||
* The `BUNDLE_DIR` sets the path where mixer temporarily stores the bundle
|
||||
definition files while building chroots. Only the legacy chroot-builder uses
|
||||
this path. By default, mixer does not generate this directory until needed.
|
||||
In our example, the path is set to :file:`/home/clr/mix/mix-bundles`. The
|
||||
new chroot-builder does not generate the folder at all.
|
||||
* The `BUNDLE_DIR` variable sets the path where mixer temporarily stores the
|
||||
bundle definition files while building chroots. Only the legacy
|
||||
chroot-builder uses this path. By default, mixer does not generate this
|
||||
directory until the directory is needed. In our example, the path is set to
|
||||
:file:`/home/clr/mix/mix-bundles`. The new chroot-builder does not generate
|
||||
the folder at all.
|
||||
|
||||
* The `YUM_CONF` variable sets path where mixer automatically generates the
|
||||
:file:`.yum-mix.conf` yum configuration file. The yum configuration file
|
||||
@@ -200,33 +203,32 @@ The following variables require further explanation:
|
||||
certificate file to sign the root :file:`Manifest.MoM` file to provide
|
||||
security for content verification. The value of the `CERT` variable can
|
||||
point to a different certificate. The chroot-builder inserts the
|
||||
certificate specified here in the
|
||||
certificate specified in this value into the
|
||||
:file:`/os-core-update/usr/share/clear/update-ca/` path. The software
|
||||
update client uses this certificate to
|
||||
verify the :file:`Manifest.MoM` file's signature. For now, we **strongly**
|
||||
recommend not to modify this line as the certificate `swupd` expects needs
|
||||
a very specific configuration to sign and verify properly. Mixer
|
||||
automatically generates the certificate and signs the
|
||||
:file:`Manifest.MoM` file providing security for your created update
|
||||
content.
|
||||
update client uses this certificate to verify the :file:`Manifest.MoM`
|
||||
file's signature. For now, we **strongly** recommend that you do not
|
||||
modify this line, as the certificate that `swupd` expects needs to have a
|
||||
very specific configuration to sign and verify properly. Mixer
|
||||
automatically generates the certificate and signs the :file:`Manifest.MoM`
|
||||
file to provide security for the updated content you create.
|
||||
|
||||
* The `CONTENTURL` and `VERSIONURL` variables set the domain or IP address
|
||||
where mixer serves your updated content and the corresponding version. You
|
||||
can set the `CONTENTURL` and `VERSIONURL` URL variables to the domain or IP-
|
||||
can set the `CONTENTURL` and `VERSIONURL` URL variables to the domain or IP
|
||||
address of the update server. The `SERVER_STATE_DIR` directory is hosted
|
||||
here: :file:`/home/clr/mix/update/www`. Creating a symlink to the directory
|
||||
in your server webdir is an easy way to host the content. These URLs are
|
||||
embedded in images created for your mix. The `swupd-client` looks at these
|
||||
URLs to figure out if there is a new version available and the location from
|
||||
which to download the updated content. Think of these links as the
|
||||
URLs to determine both if there is a new version available and the location
|
||||
from which to download the updated content. Think of these links as the
|
||||
equivalent to the |CL| `update page`_ but for your mix.
|
||||
|
||||
* The `FORMAT` variable relates to the format bump. To learn more about the
|
||||
`FORMAT` option, see :ref:`mixer-format` and the `format bumps wiki`_. For
|
||||
now, leave the `FORMAT` value unchanged.
|
||||
`FORMAT` option, refer to :ref:`mixer-format` and the `format bumps wiki`_.
|
||||
For now, leave the `FORMAT` value unchanged.
|
||||
|
||||
* The `VERSIONS_PATH` variable set the path for the mix version and upstream
|
||||
|CL| version two state files: :file:`mixversion` and
|
||||
* The `VERSIONS_PATH` variable sets the path for the mix version and upstream
|
||||
|CL| version's two state files: :file:`mixversion` and
|
||||
:file:`upstreamversion`. Mixer creates both files for you when you set up
|
||||
the workspace.
|
||||
|
||||
@@ -237,18 +239,18 @@ Create or locate RPMs for the mix
|
||||
*********************************
|
||||
|
||||
If you create RPMs from scratch, you can use `autospec`, `mock`, `rpmbuild`,
|
||||
or similar tools to build them. If the RPMs are not built on |CL|, ensure your
|
||||
configuration and tool-chain builds them correctly for Clear or there is no
|
||||
guarantee they will be compatible. For more information on building the RPMs
|
||||
properly visit our `build RPMs instructions`_.
|
||||
or similar tools to build them. If the RPMs are not built on |CL|, ensure
|
||||
your configuration and toolchain builds them correctly for |CL|, or else
|
||||
there is no guarantee they will be compatible. For more information on
|
||||
building the RPMs properly, refer to our `build RPMs instructions`_.
|
||||
|
||||
Import RPMs into workspace
|
||||
**************************
|
||||
|
||||
#. Create a :file:`local-rpms` directory in your workspace, for example
|
||||
#. Create a :file:`local-rpms` directory in your workspace. For example,
|
||||
:file:`/home/clr/mix/local-rpms`.
|
||||
|
||||
#. Copy the RPMs into the created directory.
|
||||
#. Copy the RPMs into the directory you created.
|
||||
|
||||
#. Add the following line to your :file:`builder.conf` file:
|
||||
|
||||
@@ -269,25 +271,27 @@ Create a local RPM repo
|
||||
|
||||
LOCAL_REPO_DIR=/home/clr/mix/local-yum
|
||||
|
||||
#. With these values configured, generate the yum repo with the following command:
|
||||
#. With these values configured, generate the yum repo with the following
|
||||
command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer add-rpms
|
||||
|
||||
After the tool exits, you should see the RPMs and a repository data directory in
|
||||
:file:`/home/clr/mix/local-yum`. If the RPMs are not all in this
|
||||
:file:`local-yum` directory, check to ensure they are valid RPM files and not
|
||||
corrupt.
|
||||
After the tool exits, you should see the RPMs and a repository data
|
||||
directory in :file:`/home/clr/mix/local-yum`. If the RPMs are not all in this
|
||||
:file:`local-yum` directory, check to ensure that the RPM files are valid
|
||||
and not corrupt.
|
||||
|
||||
List, edit, create, add, remove, or validate bundles
|
||||
****************************************************
|
||||
|
||||
The bundles in the mix are specified in the mix bundle list. Mixer stores
|
||||
this list as a flat file called :file:`mixbundles` in the path set in the
|
||||
`VERSIONS_PATH` variable of the :file:`builder.conf` file. Mixer generates
|
||||
the mix bundle list file automatically during initialization. Mixer reads
|
||||
and writes the bundle list file when you change the bundles of the mix.
|
||||
this list as a flat file called :file:`mixbundles` in the path set by the
|
||||
`VERSIONS_PATH` variable of the :file:`builder.conf` file. Mixer
|
||||
automatically generates the :file:`mixbundles` list file during
|
||||
initialization. Mixer reads and writes the bundle list file when you change
|
||||
the bundles of the mix.
|
||||
|
||||
List the bundles in the mix
|
||||
===========================
|
||||
@@ -298,54 +302,56 @@ To view the bundles already in the mix, enter the following command:
|
||||
|
||||
sudo mixer bundle list
|
||||
|
||||
The command shows a list of every bundle in the mix. Bundles can include other
|
||||
bundles and those bundles can themselves include other bundles. When listing
|
||||
the bundles with this command, mixer automatically recurses through the
|
||||
includes to show every single bundle in the mix.
|
||||
This command shows a list of every bundle in the mix. Bundles can include
|
||||
other bundles, and those nested bundles can themselves include other
|
||||
bundles. When listing bundles with this command, mixer automatically
|
||||
recurses through the includes to show every single bundle in the mix.
|
||||
|
||||
If you see an unexpected bundle in the list, the bundle probably is included
|
||||
in another bundle. Use the :option:`--tree` flag to get a better view of how a
|
||||
bundle ended up in the mix, for example:
|
||||
If you see an unexpected bundle in the list, that bundle is probably included
|
||||
in another bundle. Use the :option:`--tree` flag to get a better view of how
|
||||
a bundle ended up in the mix. For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle list --tree
|
||||
|
||||
This command prints a tree view of the mix bundle list explicitly showing each
|
||||
included bundle.
|
||||
This command prints a tree view of the mix bundle list that explicitly shows
|
||||
each included bundle.
|
||||
|
||||
Bundles fall into two categories: **upstream** and **local**.
|
||||
|
||||
Upstream bundles are those provided by |CL|.
|
||||
|
||||
Mixer automatically downloads and caches upstream bundle definition files. The
|
||||
definition files are stored in the :file:`upstream-bundles` directory in the
|
||||
workspace. Do **not** modify the files in this directory. The directory is
|
||||
simply a mirror for mixer to use.
|
||||
Mixer automatically downloads and caches upstream bundle definition files.
|
||||
These definition files are stored in the :file:`upstream-bundles` directory
|
||||
in the workspace. Do **not** modify the files in this directory. This
|
||||
directory is simply a mirror for mixer to use.
|
||||
|
||||
The mixer tool automatically caches the bundles for the |CL| version configured in the
|
||||
:file:`upstreamversion` file. Mixer also cleans up old versions once they are no
|
||||
longer needed. See the available upstream bundles with the following command:
|
||||
The mixer tool automatically caches the bundles for the |CL| version
|
||||
configured in the :file:`upstreamversion` file. Mixer also cleans up old
|
||||
versions once they are no longer needed. You can see the available upstream
|
||||
bundles with the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle list upstream
|
||||
|
||||
Local bundles are bundles you create or edited versions of upstream bundles.
|
||||
Local bundles are bundles that you create, or are edited versions of upstream
|
||||
bundles.
|
||||
|
||||
Local bundle definition files live in the :file:`local-bundles` directory.
|
||||
The `LOCAL_BUNDLE_DIR` variable sets the path of this directory in your
|
||||
:file:`builder.conf` configuration file. For this example, the path is
|
||||
:file:`/home/clr/mix/local-bundles`. See the available local bundles with the
|
||||
following command:
|
||||
:file:`/home/clr/mix/local-bundles`. You can see the available local bundles
|
||||
with the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle list local
|
||||
|
||||
Both the local or upstream :command:`bundle list` commands accept the
|
||||
:option:`--tree` flag to print a tree view explicitly showing each included
|
||||
bundle.
|
||||
Both the local and upstream :command:`bundle list` commands accept the
|
||||
:option:`--tree` flag to print a tree view that explicitly shows each
|
||||
included bundle.
|
||||
|
||||
Edit the bundles in the mix
|
||||
===========================
|
||||
@@ -353,9 +359,9 @@ Edit the bundles in the mix
|
||||
**Mixer always checks local bundles first and the upstream bundles second.**
|
||||
|
||||
Therefore, bundles in the :file:`local-bundles` directory always take
|
||||
precedence over the upstream bundles of the same name.
|
||||
precedence over any upstream bundles that have the same name.
|
||||
|
||||
This precedence enables the editing of upstream bundles. The local, edited
|
||||
This precedence enables you to edit upstream bundles. The local, edited
|
||||
version of the bundle overrides the bundle version found upstream.
|
||||
|
||||
For example, to edit the `bundle1` definition file, we use the following
|
||||
@@ -365,9 +371,10 @@ command:
|
||||
|
||||
sudo mixer bundle edit bundle1
|
||||
|
||||
If `bundle1` is found in your local bundles, mixer edits the bundle definition
|
||||
file. If instead `bundle1` is only found upstream, mixer copies the bundle
|
||||
definition file from upstream into your :file:`local-bundles` directory first.
|
||||
If `bundle1` is found in your local bundles, mixer edits the bundle
|
||||
definition file. If instead `bundle1` is only found upstream, mixer copies
|
||||
the bundle definition file from upstream into your :file:`local-bundles`
|
||||
directory first.
|
||||
|
||||
In both cases, mixer launches your default editor to edit the file. When the
|
||||
editor closes, mixer automatically validates the edited bundle file and
|
||||
@@ -386,7 +393,7 @@ Create bundles for the mix
|
||||
==========================
|
||||
|
||||
To create a totally **new bundle**, the bundle name you specify cannot exist
|
||||
upstream. If that is the case, create a `new-bundle` with the following
|
||||
upstream. If that is the case, create a :file:`new-bundle` with the following
|
||||
command:
|
||||
|
||||
.. code-block:: bash
|
||||
@@ -394,14 +401,15 @@ command:
|
||||
sudo mixer bundle edit new-bundle
|
||||
|
||||
This command generates a blank template in :file:`local-bundles` with the
|
||||
:file:`new-bundle` filename. Mixer launches the editor for you to fill out the
|
||||
bundle and performs validation on exiting. Add your package or packages in the
|
||||
bundle definition file to define the packages to install as part of the bundle.
|
||||
:file:`new-bundle` filename. Mixer launches the editor for you to fill out
|
||||
the bundle and performs validation when you exit the editor. Add your package
|
||||
or packages to the bundle definition file to define the packages to install
|
||||
as part of the bundle.
|
||||
|
||||
.. note::
|
||||
|
||||
The :command:`mixer bundle edit` accepts multiple bundles at once. Thus,
|
||||
you can create multiple new bundles in a single command, for example:
|
||||
you can create multiple new bundles in a single command. For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -410,19 +418,19 @@ bundle definition file to define the packages to install as part of the bundle.
|
||||
Add bundles to the mix
|
||||
======================
|
||||
|
||||
Add `bundle1` to your mix easily with the following command:
|
||||
You can add `bundle1` to your mix with the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle add bundle1
|
||||
|
||||
This command adds the bundles you specify to your mix bundles list stored in
|
||||
the :file:`mixbundles` file. For each bundle you add, mixer checks your local
|
||||
and upstream bundles to ensure the added bundle actually exists. If mixer
|
||||
cannot find the bundle, it reports back an error. Additionally, when mixer
|
||||
adds a bundle, it tells you whether the bundle is local or upstream.
|
||||
This command adds the specified bundles to the mix bundles list stored in
|
||||
your :file:`mixbundles` file. For each bundle you add, mixer checks your
|
||||
local and upstream bundles to ensure the added bundles actually exist. If
|
||||
mixer cannot find the bundle, it reports back an error. Additionally, when
|
||||
mixer adds a bundle, it tells you whether the bundle is local or upstream.
|
||||
Alternatively, you can learn this information with the
|
||||
:command:`mixer bundle list` command, see `List the bundles in the mix`_.
|
||||
:command:`mixer bundle list` command. Refer to `List the bundles in the mix`_.
|
||||
|
||||
To add multiple bundles at once, use the following command:
|
||||
|
||||
@@ -439,31 +447,31 @@ Remove `bundle1` from your mix with the following command:
|
||||
|
||||
sudo mixer bundle remove bundle1
|
||||
|
||||
This command remove the `bundle1` from the mix bundle list stored in the
|
||||
:file:`mixbundles` file. By default, the command does not remove the bundle
|
||||
This command removes `bundle1` from the mix bundle list stored in your
|
||||
:file:`mixbundles` file. By default, this command does not remove the bundle
|
||||
definition file from your local bundles. To completely remove a bundle,
|
||||
including its local bundle definition file, use the following command with the
|
||||
:option:`--local` flag:
|
||||
including its local bundle definition file, use the following command with
|
||||
the :option:`--local` flag:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle remove --local bundle1
|
||||
|
||||
By default, removing a local bundle file with this command removes the bundle
|
||||
from the mix as well. To only remove the local bundle definition file, use the
|
||||
following command with the :option:`--mix=false` flag:
|
||||
from the mix as well. To only remove the local bundle definition file, use
|
||||
the following command with the :option:`--mix=false` flag:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle remove --local --mix=false bundle1
|
||||
|
||||
If you remove a local edited version of an upstream bundle and keep the bundle
|
||||
in the mix, the mix then references the original upstream version of the
|
||||
bundle.
|
||||
If you remove a local, edited version of an upstream bundle and keep the
|
||||
bundle in the mix, the mix then references the original upstream version of
|
||||
the bundle.
|
||||
|
||||
On the other hand, if you remove a bundle only found locally but keep the
|
||||
bundle in the mix bundles list, mixer will no longer find a valid bundle
|
||||
definition file and will produce an error.
|
||||
On the other hand, if you remove a bundle that is only found locally but
|
||||
keep the bundle in the mix bundles list, mixer will not find a valid
|
||||
bundle definition file and will produce an error.
|
||||
|
||||
Validate the bundles in the mix
|
||||
===============================
|
||||
@@ -472,17 +480,18 @@ Mixer performs basic **validation** on all bundles when used
|
||||
throughout the system.
|
||||
|
||||
Mixer checks the validity of the bundle's syntax and name. Mixer also ensures
|
||||
the bundle can be parsed. Run this validation manually on bundle1 with the
|
||||
the bundle can be parsed. Run this validation manually on `bundle1` with the
|
||||
following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle validate bundle1
|
||||
|
||||
With the optional :option:`--strict` flag, the command additionally
|
||||
checks if the rest of the bundle header fields can be parsed, if they are
|
||||
non-empty, and if the bundle header ``Title`` field and the bundle filename
|
||||
match. Perform a strict validation of `bundle1` with the following command:
|
||||
If you use the optional :option:`--strict` flag, the command additionally
|
||||
checks if the rest of the bundle header fields can be parsed, if the bundle
|
||||
header fields are non-empty, and if the bundle header ``Title`` field and
|
||||
the bundle filename match. Perform a strict validation of `bundle1` with the
|
||||
following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -497,13 +506,14 @@ Validate multiple bundles with the following command:
|
||||
Managing bundles with Git
|
||||
=========================
|
||||
|
||||
If you initialized your workspace to be tracked as a Git repository
|
||||
with the :command:`mixer init --git` command, it might be useful to apply a git
|
||||
commit after modifying the mix bundle list or editing a bundle definition file.
|
||||
If you initialized your workspace to be tracked as a git repository
|
||||
with the :command:`mixer init --git` command, it might be useful to apply a
|
||||
git commit after you modify the mix bundle list or edit a bundle definition
|
||||
file.
|
||||
|
||||
All the :command:`mixer bundle` commands on the previous sections support an
|
||||
optional :option:`--git` flag. The flag automatically applies a git commit
|
||||
when the command completes, for example:
|
||||
All the :command:`mixer bundle` commands in the previous sections support an
|
||||
optional :option:`--git` flag. This flag automatically applies a git commit
|
||||
when the command completes. For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -525,20 +535,21 @@ By default, mixer uses the legacy chroot-builder. In this mode, mixer
|
||||
automatically gathers the bundle definition files for the bundles in the mix
|
||||
into a :file:`mix-bundles` directory. The directory's path is set in the
|
||||
`BUNDLE_DIR` variable in the :file:`builder.conf`. **Do not edit these
|
||||
files.** Mixer automatically clears out any contents in this directory before
|
||||
populating it on-the-fly as mixer builds the chroots.
|
||||
files.** Mixer automatically deletes the contents of the :file:`mix-bundles`
|
||||
directory before repopulating the directory on-the-fly as mixer builds the
|
||||
chroots.
|
||||
|
||||
We have build a new chroot-builder into the mixer tool itself. While this is
|
||||
currently an experimental feature, you should use the new chroot-builder. To use
|
||||
the new chroot-builder, use the following command with the
|
||||
We have built a new chroot-builder into the mixer tool itself. While this is
|
||||
currently an experimental feature, you should use the new chroot-builder. To
|
||||
use the new chroot-builder, use the following command with the
|
||||
:option:`--new-chroots` flag:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer build chroots --new-chroots
|
||||
|
||||
We will soon deprecate the legacy chroot-builder and mixer will use the new version
|
||||
automatically.
|
||||
We will soon deprecate the legacy chroot-builder. When we do, mixer will use
|
||||
the new version automatically.
|
||||
|
||||
Create an update
|
||||
****************
|
||||
@@ -552,28 +563,28 @@ Create an update with the following command:
|
||||
When the build completes, you can find the mix update content under
|
||||
:file:`/home/clr/mix/update/www/VER`. In our example, the update content is
|
||||
found in :file:`/home/clr/mix/update/www/{<MIXVERSION>}`. `<MIXVERSION>`
|
||||
is the mix version defined, 10 by default.
|
||||
is the defined mix version, which is 10 by default.
|
||||
|
||||
By default, mixer uses the legacy `swupd-server` to generate the update
|
||||
content. We have built a new implementation into the mixer tool itself. While
|
||||
this is currently an experimental feature, you should use the new swupd-
|
||||
server. To use the the new swupd-server, use the following command with the
|
||||
:option:`--new-swupd` flag:
|
||||
content. However, we have built a new implementation into the mixer tool
|
||||
itself. While this is currently an experimental feature, you should use the
|
||||
new `swupd-server`. To use the the new `swupd-server`, use the following
|
||||
command with the :option:`--new-swupd` flag:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer build update --new-swupd
|
||||
|
||||
We will soon deprecate the legacy swupd-server and mixer will use the new version
|
||||
automatically.
|
||||
We will soon deprecate the legacy `swupd-server`. When we do, mixer will use
|
||||
the new version automatically.
|
||||
|
||||
Mixer creates all the content needed to make a fully usable mix with this
|
||||
step. However, only *zero packs* are automatically generated. Zero packs are
|
||||
the content needed to go from nothing to the mix version for which you just
|
||||
built the content.
|
||||
|
||||
Create optional *delta packs*, which allow the transition from one mix version
|
||||
to another, with the following command:
|
||||
You can create optional *delta packs*, which allow the transition from one
|
||||
mix version to another, with the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -581,20 +592,20 @@ to another, with the following command:
|
||||
|
||||
The pack-maker generates all delta packs for the bundles changed from
|
||||
`PAST_VERSION` to `MIX_VERSION`. If your `STATE_DIR` is in a different
|
||||
location, specify the location with the :option:`-S` flag. Mixer cannot create
|
||||
delta packs for the first build because the update is from version 0. Version
|
||||
0 implicitly has no content, thus, mixer can generate no deltas.
|
||||
location, specify the location with the :option:`-S` flag. Mixer cannot
|
||||
create delta packs for the first build because the update is from version 0.
|
||||
Version 0 implicitly has no content. Thus, mixer can generate no deltas.
|
||||
|
||||
For subsequent builds, you can run :file:`mixer-pack-maker.sh` to generate
|
||||
delta content between them, for example: 10 to 20.
|
||||
For subsequent builds, you can run :file:`mixer-pack-maker.sh` to generate
|
||||
delta content between them. For example: 10 to 20.
|
||||
|
||||
Create an image
|
||||
*****************
|
||||
|
||||
Since mixer uses the `ister` tool to create a bootable image from your updated
|
||||
content, we must first configure the `ister` tool. To configure the image
|
||||
`ister` creates, we need the `ister` configuration file. Obtain a copy with
|
||||
the default values from the `ister` package with the following command:
|
||||
Since mixer uses the `ister` tool to create a bootable image from your
|
||||
updated content, we must first configure the `ister` tool. To configure the
|
||||
image `ister` creates, we need the `ister` configuration file. Obtain a copy
|
||||
with the default values from the `ister` package with the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -604,8 +615,8 @@ For reference, you can inspect the `Clear Linux ister configuration file`_
|
||||
used for releases.
|
||||
|
||||
Edit the configuration file to include all bundles you want *preinstalled* in
|
||||
the image. Users can install the bundles in the mix not included in the
|
||||
configuration file with the following command:
|
||||
the image. Users can install the bundles in the mix that are not included in
|
||||
the configuration file with the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -618,23 +629,23 @@ smaller image size. For the minimal base image, the list is:
|
||||
|
||||
"Bundles": ["os-core", "os-core-update", "kernel-native"]
|
||||
|
||||
Next, set the `Version` field to the mix version content mixer should use to
|
||||
build image. `ister` allows you to build an image from any mix version you
|
||||
have built, not just the current one. In our example so far, `Version` is set
|
||||
to 10.
|
||||
Next, set the `Version` field to the mix version that you want the content
|
||||
mixer to use to build the image. `ister` allows you to build an image from
|
||||
any mix version that you have built, not just from the current version. In
|
||||
our example so far, `Version` is set to 10.
|
||||
|
||||
With the `ister` tool configured, build the image with with the following command:
|
||||
With the `ister` tool configured, build the image with the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer build image --format 1
|
||||
|
||||
This command outputs an image bootable as a virtual machine and which can be
|
||||
installed on bare metal.
|
||||
This command outputs an image that is bootable as a virtual machine and
|
||||
that can be installed on bare metal.
|
||||
|
||||
Mixer automatically looks for the :file:`release-image-config.json` file but
|
||||
Mixer automatically looks for the :file:`release-image-config.json` file, but
|
||||
you can freely choose the filename. To use a different name, simply pass the
|
||||
:option:`--template` flag when creating your image, for example:
|
||||
:option:`--template` flag when creating your image. For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -659,30 +670,31 @@ Increment the mix version number for the next mix with the following command:
|
||||
sudo mixer versions update
|
||||
|
||||
This command automatically updates the mix version stored in the
|
||||
:file:`mixversion` file incrementing it by 10. To increment by a different
|
||||
amount, use the :option:`--increment` flag, for example:
|
||||
:file:`mixversion` file, incrementing it by 10. To increment by a different
|
||||
amount, use the :option:`--increment` flag. For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer versions update --increment 100
|
||||
|
||||
Alternatively, to set the mix version to a specific value, use the
|
||||
:option:`--mix-version` flag, for example:
|
||||
:option:`--mix-version` flag. For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer versions update --mix-version 200
|
||||
|
||||
The :command:`mixer versions update` command does not allow you to set the mix
|
||||
version to a value lower than its current value. The mix version is expected
|
||||
to always increase, even if the new mix is undoing an earlier change.
|
||||
The :command:`mixer versions update` command does not allow you to set the
|
||||
mix version to a value less than its current value. The mix version is
|
||||
expected to always increase, even if the new mix is undoing an earlier
|
||||
change.
|
||||
|
||||
If you have been tracking your workspace with Git, you can restore the mix to
|
||||
an earlier state but be careful of "rewriting history" if you are publishing
|
||||
the mix content to users already.
|
||||
If you have been tracking your workspace with git, you can restore the mix to
|
||||
an earlier state. However, be careful when "rewriting history" if you have
|
||||
published the mix content to users already.
|
||||
|
||||
Update the upstream version of |CL| used as a base for the mix, with the
|
||||
following command using the :option:`--upstream-version` flag:
|
||||
Use the following command with the the :option:`--upstream-version` flag to
|
||||
update the upstream version of |CL| used as a base for the mix:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -696,12 +708,12 @@ This command also accepts the keyword "latest":
|
||||
|
||||
This command sets the upstream version to the latest released version of
|
||||
upstream |CL| within the same format version. The :command:`mixer
|
||||
versions update` command does not allow to set an upstream version to a
|
||||
value crossing an upstream format boundary. Such values require a
|
||||
"format bump" build, which is currently a manual process. See :ref:`mixer-format`
|
||||
for more information.
|
||||
versions update` command does not allow you to set an upstream version to a
|
||||
value that crosses an upstream format boundary. Such values require a
|
||||
"format bump" build, which is currently a manual process. Refer to
|
||||
:ref:`mixer-format` for more information.
|
||||
|
||||
Learn which mix version or upstream version you currently are on with the
|
||||
Learn which mix version or upstream version you are currently using with the
|
||||
following command:
|
||||
|
||||
.. code-block:: bash
|
||||
@@ -724,7 +736,7 @@ modifications as needed. For example:
|
||||
|
||||
sudo mixer build update
|
||||
|
||||
#. Optionally,create delta packs with:
|
||||
#. Optionally, you can create delta packs with:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -735,24 +747,25 @@ modifications as needed. For example:
|
||||
Format version
|
||||
**************
|
||||
|
||||
The `Format` variable set in the :file:`builder.conf` can be more precisely
|
||||
referred to as an OS *compatibility epoch*. Versions of the OS within a given
|
||||
epoch are fully compatible and can update to any version in that epoch. Across
|
||||
the `Format` boundary, the OS has changed in such a way, that updating from
|
||||
build M in format X, to build N in format Y will not work. Generally, this
|
||||
scenario occurs when the software updater or manifests change in a way no
|
||||
longer compatible with the previous update scheme.
|
||||
The `Format` variable set in the :file:`builder.conf` file can be more
|
||||
precisely referred to as an OS *compatibility epoch*. Versions of the OS
|
||||
within a given epoch are fully compatible and can update to any other
|
||||
version within that epoch. Across the `Format` boundary, the OS has changed
|
||||
in such a way that updating from build M in format X, to build N in format Y
|
||||
will not work. Generally, this scenario occurs when the software updater or
|
||||
software manifests change in a way that they are no longer compatible with
|
||||
the previous update scheme.
|
||||
|
||||
Using a format increment, we insure pre- and co-requisite changes flow out
|
||||
with proper ordering. The updated client only ever updates to the latest
|
||||
release in its respective format version, unless overridden by command line
|
||||
flags. Thus, we can guarantee all clients update to the final version in their
|
||||
given format. The given format *must* contain all the changes needed to
|
||||
understand the content built in the subsequent format. Only after reaching the
|
||||
final release in the old format, can a client continue to update to releases
|
||||
in the new format.
|
||||
flags. Thus, we can guarantee that all clients update to the final version
|
||||
in their given format. The given format *must* contain all the changes
|
||||
needed to understand the content built in the subsequent format. Only after
|
||||
reaching the final release in the old format can a client continue to update
|
||||
to releases in the new format.
|
||||
|
||||
When creating a custom mix, the format version should start at '1' or some
|
||||
When creating a custom mix, the format version should start at `1` or some
|
||||
known number. The format version should increment only when a compatibility
|
||||
breakage is introduced. Normal updates, like updating a software package for
|
||||
example, do not require a format increment.
|
||||
|
||||
Reference in New Issue
Block a user