mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-10-03 15:39:59 +00:00
Fix technical inaccuracies introduced by rewording.
Additionally, all the unnecessary sudo commands have been removed. Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>
This commit is contained in:
Rodrigo Caballero
@@ -40,7 +40,7 @@ The following workflow applies if the mix includes your own
|
||||
#. `Create an image`_
|
||||
|
||||
Alternatively, the following workflow applies if the mix only uses |CL|
|
||||
bundles.
|
||||
content.
|
||||
|
||||
#. `Create a workspace`_
|
||||
#. `Generate the starting point for your mix`_
|
||||
@@ -72,13 +72,14 @@ In your workspace, initialize mixer with the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer init
|
||||
mixer init
|
||||
|
||||
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, several version and tracking files, and two bundle
|
||||
directories: :file:`local-bundles` and :file:`upstream-bundles`.
|
||||
configuration file. Additionally, mixer creates 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, you can specify these options as flags.
|
||||
@@ -86,44 +87,45 @@ For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer init --clear-version 21060 --mix-version 100
|
||||
mixer init --clear-version 21060 --mix-version 100
|
||||
|
||||
|
||||
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
|
||||
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
|
||||
:file:`builder.conf`. If the configuration file already exists, you must add
|
||||
the paths manually. 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
|
||||
If all upstream |CL| bundles will be part of the mix, you can easily add them all
|
||||
during initialization with the optional :option:`--all-upstream` flag. For
|
||||
example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer init --all-upstream
|
||||
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:
|
||||
up automatically with the optional :option:`--git` flag, for example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer init --git
|
||||
mixer init --git
|
||||
|
||||
.. note::
|
||||
You can use any or all of the above optional flags at the same time, for example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer init --clear-version 21060 --mix-version 100 --local-rpms --all-upstream --git
|
||||
mixer init --clear-version 21060 --mix-version 100 --local-rpms --all-upstream --git
|
||||
|
||||
Edit builder.conf
|
||||
*****************
|
||||
@@ -134,7 +136,7 @@ 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
|
||||
@@ -148,7 +150,7 @@ Edit the configuration file according to your needs with the command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo vim /etc/bundle-chroot-builder/builder.conf
|
||||
vim /home/clr/mix/builder.conf
|
||||
|
||||
Your version of the :file:`builder.conf` file should resemble the
|
||||
following example:
|
||||
@@ -194,8 +196,8 @@ The following variables require further explanation:
|
||||
: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
|
||||
* The `YUM_CONF` variable sets the path where mixer automatically generates
|
||||
the :file:`.yum-mix.conf` yum configuration file. The yum configuration file
|
||||
points the chroot-builder to the path where the RPMs are stored.
|
||||
|
||||
* The `CERT` variable sets the path where mixer stores the
|
||||
@@ -204,26 +206,31 @@ The following variables require further explanation:
|
||||
security for content verification. The value of the `CERT` variable can
|
||||
point to a different certificate. The chroot-builder inserts 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 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:`/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 that you do not modify
|
||||
this line, as the certificate that :abbr:`swupd (Software Updater)`
|
||||
expects needs to have a very specific configuration to sign and verify
|
||||
properly. Mixer automatically generates the certificate, if you do not
|
||||
provide the path to an existing one, 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
|
||||
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 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.
|
||||
where swupd looks for your update content and the corresponding version. You
|
||||
must set these variables to the domain or IP-address of the server hosting the
|
||||
update content. You can use any web server to host your update content. To learn
|
||||
how to install and configure web server using |CL|, visit
|
||||
:ref:`web-server-install`. For our example, the web update content within
|
||||
the `SERVER_STATE_DIR` directory is located here:
|
||||
:file:`/home/clr/mix/update/www`. If the web server is on same machine as
|
||||
this directory, you can create a symlink to the directory in your web
|
||||
server's document root to easily host the content. These URLs are
|
||||
embedded in images created for your mix. The `swupd-client` looks at
|
||||
these URLs to determine if a new version is available and the location
|
||||
from where to download the updated content. These links are equivalent
|
||||
to the |CL| `update page`_ but for the mix.
|
||||
|
||||
* The `FORMAT` variable relates to the format bump. To learn more about the
|
||||
* The `FORMAT` variable relates to format bumps. To learn more about the
|
||||
`FORMAT` option, refer to :ref:`mixer-format` and the `format bumps wiki`_.
|
||||
For now, leave the `FORMAT` value unchanged.
|
||||
|
||||
@@ -247,7 +254,7 @@ 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 directory you created.
|
||||
@@ -300,23 +307,23 @@ To view the bundles already in the mix, enter the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle list
|
||||
mixer bundle list
|
||||
|
||||
This command shows a list of every bundle in the mix. Bundles can include
|
||||
other bundles, and those nested bundles can themselves include other
|
||||
other bundles. 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, 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:
|
||||
a bundle ended up in the mix, for example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle list --tree
|
||||
mixer bundle list --tree
|
||||
|
||||
This command prints a tree view of the mix bundle list that explicitly shows
|
||||
each included bundle.
|
||||
This command shows a visual representation of the inclusion relationships
|
||||
between the bundles in the mix.
|
||||
|
||||
Bundles fall into two categories: **upstream** and **local**.
|
||||
|
||||
@@ -334,7 +341,7 @@ bundles with the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle list upstream
|
||||
mixer bundle list upstream
|
||||
|
||||
Local bundles are bundles that you create, or are edited versions of upstream
|
||||
bundles.
|
||||
@@ -347,11 +354,11 @@ with the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle list local
|
||||
mixer bundle list local
|
||||
|
||||
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.
|
||||
:option:`--tree` flag to show a visual representation of the inclusion relationships
|
||||
between the bundles in the mix.
|
||||
|
||||
Edit the bundles in the mix
|
||||
===========================
|
||||
@@ -369,17 +376,17 @@ command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle edit bundle1
|
||||
mixer bundle edit bundle1
|
||||
|
||||
If `bundle1` is found in your local bundles, mixer edits the bundle
|
||||
If `bundle1` is found in your local bundles, mixer edits this 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
|
||||
reports any errors found. If mixer finds an error, you can edit the file as-
|
||||
is, revert and edit, or skip and move on to the next bundle. If you skip a
|
||||
reports any errors found. If mixer finds an error, you can edit the file
|
||||
as-is, revert and edit, or skip and move on to the next bundle. If you skip a
|
||||
file, mixer saves a backup of the original file with the ``.orig`` suffix.
|
||||
Because mixer always checks your local bundles first, edited copies of an
|
||||
upstream bundle always take precedence over their upstream counterpart. You
|
||||
@@ -387,7 +394,7 @@ can edit multiple bundles with the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle edit bundle1 bundle2 [bundle3 ...]
|
||||
mixer bundle edit bundle1 bundle2 [bundle3 ...]
|
||||
|
||||
Create bundles for the mix
|
||||
==========================
|
||||
@@ -398,7 +405,7 @@ command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle edit new-bundle
|
||||
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
|
||||
@@ -408,21 +415,21 @@ 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:
|
||||
The :command:`mixer bundle edit` command accepts multiple bundles at once.
|
||||
Thus, you can create multiple new bundles in a single command, for example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle edit new-bundle1 new-bundle2 [new-bundle3 ...]
|
||||
mixer bundle edit new-bundle1 new-bundle2 [new-bundle3 ...]
|
||||
|
||||
Add bundles to the mix
|
||||
======================
|
||||
|
||||
You can add `bundle1` to your mix with the following command:
|
||||
Add `bundle1` to your mix with the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle add bundle1
|
||||
mixer bundle add bundle1
|
||||
|
||||
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
|
||||
@@ -436,7 +443,7 @@ To add multiple bundles at once, use the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle add bundle1 bundle2 [bundle3 ...]
|
||||
mixer bundle add bundle1 bundle2 [bundle3 ...]
|
||||
|
||||
Remove bundles from the mix
|
||||
===========================
|
||||
@@ -445,7 +452,7 @@ Remove `bundle1` from your mix with the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle remove bundle1
|
||||
mixer bundle remove bundle1
|
||||
|
||||
This command removes `bundle1` from the mix bundle list stored in your
|
||||
:file:`mixbundles` file. By default, this command does not remove the bundle
|
||||
@@ -455,7 +462,7 @@ the :option:`--local` flag:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle remove --local bundle1
|
||||
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
|
||||
@@ -463,7 +470,7 @@ the following command with the :option:`--mix=false` flag:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle remove --local --mix=false bundle1
|
||||
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
|
||||
@@ -476,16 +483,18 @@ bundle definition file and will produce an error.
|
||||
Validate the bundles in the mix
|
||||
===============================
|
||||
|
||||
Mixer performs basic **validation** on all bundles when used
|
||||
throughout the system.
|
||||
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
|
||||
following command:
|
||||
Mixer checks the validity of the bundle's syntax and name. Optionally, you can
|
||||
run this validation manually on `bundle1` with the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle validate bundle1
|
||||
mixer bundle validate bundle1
|
||||
|
||||
.. note:: This command can be useful in many circumstances. One example is
|
||||
when importing already-existing local bundles from other projects.
|
||||
|
||||
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
|
||||
@@ -495,13 +504,13 @@ following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle validate --strict bundle1
|
||||
mixer bundle validate --strict bundle1
|
||||
|
||||
Validate multiple bundles with the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle validate bundle1 bundle2 [bundle3 ...]
|
||||
mixer bundle validate bundle1 bundle2 [bundle3 ...]
|
||||
|
||||
Managing bundles with Git
|
||||
=========================
|
||||
@@ -513,11 +522,11 @@ file.
|
||||
|
||||
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:
|
||||
when the command completes, for example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer bundle remove --git bundle1
|
||||
mixer bundle remove --git bundle1
|
||||
|
||||
Build the bundle chroots
|
||||
************************
|
||||
@@ -539,7 +548,7 @@ 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 built a new chroot-builder into the mixer tool itself. While this is
|
||||
We have added a new chroot-builder to 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:
|
||||
@@ -597,7 +606,7 @@ 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.
|
||||
delta content between them, for example: 10 to 20.
|
||||
|
||||
Create an image
|
||||
*****************
|
||||
@@ -620,7 +629,7 @@ the configuration file with the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd bundle add
|
||||
sudo swupd bundle-add bundle1
|
||||
|
||||
Keeping the list of bundles in the configuration file small allows for a
|
||||
smaller image size. For the minimal base image, the list is:
|
||||
@@ -640,12 +649,9 @@ With the `ister` tool configured, build the image with the following command:
|
||||
|
||||
sudo mixer build image --format 1
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
@@ -667,22 +673,22 @@ Increment the mix version number for the next mix with the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer versions update
|
||||
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:
|
||||
amount, use the :option:`--increment` flag, for example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer versions update --increment 100
|
||||
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
|
||||
mixer versions update --mix-version 200
|
||||
|
||||
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
|
||||
@@ -698,30 +704,30 @@ update the upstream version of |CL| used as a base for the mix:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer versions update --upstream-version 21070
|
||||
mixer versions update --upstream-version 21070
|
||||
|
||||
This command also accepts the keyword "latest":
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer versions update --upstream-version latest
|
||||
mixer versions update --upstream-version 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 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.
|
||||
upstream |CL| within the same format version. The
|
||||
:command:`mixer 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 are currently using with the
|
||||
following command:
|
||||
Optionally, you can learn which mix version or upstream version you are
|
||||
currently using with the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mixer versions
|
||||
mixer versions
|
||||
|
||||
At this point, you can continue to iterate through the workflows and make
|
||||
modifications as needed. For example:
|
||||
modifications as needed, for example:
|
||||
|
||||
#. Add, remove, or modify bundles.
|
||||
#. Build the chroots with:
|
||||
|
||||
Reference in New Issue
Block a user