copy edit and language cleanup

Signed-off-by: Ecouzens <evan.couzens@intel.com>
This commit is contained in:
Ecouzens
2018-03-06 13:33:21 -08:00
parent 888cf2ff27
commit c2902ec1a5
+207 -194
View File
@@ -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.