Update Autospec guide for clarity

- Remove custom mix prereq
- Remove note re install, in favor of more standard prepreq text
- Remove whitespace
- Add related topics
- Add summary end sentence directing user to next possible steps
- Remove include of overview of autospec concept. Move 'for detailed explanation...' to intro (this includes link to concept).
- Remove mixer section and skip to links to mixer section.
- Add Option 1, 2, 3 to the 3 options to build RPMs (to clarify where option starts/ends)
- Replace 'run this' and 'install this' with specifics in tooling instructions
- Minor edits to intro for each build option

Signed-off-by: Kristal Dale <kristal.dale@intel.com>
This commit is contained in:
Kristal Dale
2018-10-25 13:46:38 -07:00
parent d173dbd252
commit d762d27cb8
@@ -3,45 +3,41 @@
Build RPMs with autospec
########################
This guide shows you how to create RPMs with :ref:`autospec <autospec-about>`
, a tool that assists in automated creation and maintenance of RPM packaging
on |CLOSIA|. Additionally, you learn how to use these RPMs to create bundles
with :ref:`mixer <mixer>`.
This guide shows you how to create RPMs with :ref:`autospec <autospec-about>`,
a tool that assists in automated creation and maintenance of RPM packaging
on |CL-ATTR|.
See our :ref:`autospec concept page <autospec-about>` for a detailed explaination
of how ``autospec`` works on |CL|. For a general understanding of how RPMs work,
we recommend visiting the `rpm website`_ or the `RPM Packaging Guide`_ .
Prerequisites
*************
This guide assumes that you have:
* Created :ref:`a custom mix <mixer>` of |CL| and deployed it to a
to a target device
This guide requires that you:
* |CL| running on a host machine or virtual environment
.. note::
* Have installed |CL| on a host machine or virtual environment. For detailed
instructions on installing |CL|, visit the :ref:`get-started` section.
To install |CL|, see:
* :ref:`install-tooling`
* :ref:`bare-metal-install`
* :ref:`virtual-machine-install`
Install Clear Linux tooling framework
=====================================
.. _install-tooling:
Our GitHub\* repository provides you with the resources you need
to create and maintain packages.
Install the |CL| tooling framework
==================================
#. Install the `os-clr-on-clr` developer bundle on your host system.
#. On your host system, install this developer bundle.
.. code-block:: bash
sudo swupd bundle-add os-clr-on-clr
#. Run this command to download the :file:`user-setup.sh` script.
#. Download the :file:`user-setup.sh` script.
.. code-block:: bash
curl -O https://raw.githubusercontent.com/clearlinux/common/master/user-setup.sh
#. Make :file:`user-setup.sh` executable.
.. code-block:: bash
@@ -49,7 +45,7 @@ to create and maintain packages.
chmod +x user-setup.sh
#. Run the script as an unprivileged user.
.. code-block:: bash
./user-setup.sh
@@ -59,41 +55,31 @@ to create and maintain packages.
The `user-setup script`_ creates a folder called :file:`clearlinux`, which
contains the :file:`Makefile`, :file:`packages`, and :file:`projects`
subfolders.
subfolders.
The :file:`projects` folder contains the main tools, `autospec`
and `common`, used for making packages in |CL|.
The :file:`projects` folder contains the main tools, `autospec`
and `common`, used for making packages in |CL|.
Create a RPM with autospec
**************************
.. include:: ../../concepts/autospec-about.rst
:start-after: incl-autospec-overview:
:end-before: incl-autospec-overview-end:
For a detailed explanation of how ``autospec`` works on |CL|, visit our
:ref:`autospec-about` about page. For a general understanding of how RPMs
work, we recommend visiting the `rpm website`_ or the
`RPM Packaging Guide`_ .
Building RPMs
=============
Choose one of the following options to build RPMs and manage source
code:
code:
* :ref:`build-a-new-rpm` and spec file using ``make autospecnew``.
* :ref:`build-a-new-rpm` and spec file using ``make autospecnew``.
* :ref:`build-source-code-with-existing-spec-file` (without changing the
spec file) using ``make build``.
* :ref:`build-source-code-with-existing-spec-file` using ``make build``, without changing the
spec file.
* :ref:`generate-a-new-spec-file` based on changes in the control files with
``make autospec``.
* :ref:`generate-a-new-spec-file` using ``make autospec``, based on changes in the control files.
.. _build-a-new-rpm:
Build a new RPM
===============
Option 1: Build a new RPM
=========================
Use this method to build a new RPM with no spec file. In this example,
we build a new helloclear RPM.
#. Navigate to the autospec workspace.
@@ -101,21 +87,21 @@ Build a new RPM
cd ~/clearlinux
#. Enter the command:
#. Enter the command:
.. code-block:: bash
make autospecnew URL="https://github.com/clearlinux/helloclear/archive/helloclear-v1.0.tar.gz"
make autospecnew URL="https://github.com/clearlinux/helloclear/archive/helloclear-v1.0.tar.gz"
NAME="helloclear"
.. note::
.. note::
For a local tarball, use for the *URL*:
For a local tarball, use for the *URL*:
file://<absolute-path-to-tarball>
#. If build failures or dependency issues occur, continue below.
Otherwise, skip directly to `copy-rpm-packages-to-mixer`_.
Otherwise, skip directly to `Use your RPM`_.
#. Navigate to the specific package.
.. code-block:: bash
@@ -123,52 +109,60 @@ Build a new RPM
cd ~/clearlinux/packages/[package-name]
#. Respond to the build process output by editing control files to resolve
issues, which may include dependencies or exclusions.
issues, which may include dependencies or exclusions.
See `autospec readme`_
#. Run this command:
#. Run this command:
.. code-block:: bash
make autospec
Repeat the last two steps above until all errors are resolved and you
complete a successful build.
Skip to `copy-rpm-packages-to-mixer`_ to add the new RPM to your mix.
Repeat the last two steps above until all errors are resolved and you
complete a successful build.
**Congratulations!**
You've successfully created a RPM.
Skip to `Use your RPM`_ for next steps.
.. _build-source-code-with-existing-spec-file:
Build source code with an existing spec file
============================================
Option 2: Build source code with an existing spec file
======================================================
If you only want to build the RPM using the spec file, use this method. This
method assumes that a spec file already exists. In this example, we run a
``make build`` on the ``dmidecode`` package.
Use this method if you only want to build the RPM using the spec file. This
method assumes that a spec file already exists. In this example, we run a
``make build`` on the ``dmidecode`` package.
#. Navigate to the ``dmidecode`` package in clearlinux:
#. Navigate to the ``dmidecode`` package in clearlinux:
.. code-block:: bash
cd ~/clearlinux/packages/dmidecode/
cd ~/clearlinux/packages/dmidecode/
#. To download the tarball and build, run the command:
#. To download the tarball and build, run the command:
.. code-block:: bash
.. code-block:: bash
make build
Skip to `copy-rpm-packages-to-mixer`_ to add the new RPM to your mix.
**Congratulations!**
You've successfully created a RPM.
Skip to `Use your RPM`_ for next steps.
.. _generate-a-new-spec-file:
Generate a new spec file with a pre-defined package
===================================================
Option 3: Generate a new spec file with a pre-defined package
=============================================================
In this method, you will modify an existing |CL| package called ``dmidecode``
to create a custom RPM. You will make a simple change to this package,
change the revision to a new number that is higher than the |CL| OS version,
and rebuild the package.
Use this method to modify an existing package. In this example, you will
modify an existing |CL| package called ``dmidecode`` to create a custom
RPM. You will make a simple change to this package, change the revision to
a new number that is higher than the |CL| OS version, and rebuild the package.
#. Navigate to clearlinux:
@@ -182,7 +176,7 @@ and rebuild the package.
make clone_dmidecode
#. Navigate into the *dmidecode* directory:
#. Navigate into the *dmidecode* directory:
.. code-block:: bash
@@ -199,15 +193,15 @@ and rebuild the package.
/usr/share/man/man8/ownership.8
/usr/share/man/man8/vpddecode.8
.. note::
.. note::
These files aren't needed by dmidecode, so we can remove them without
any issues.
#. Save the file and exit.
#. Save the file and exit.
#. At :file:`~/clearlinux/packages/dmidecode`, build the modified
``dmidecode`` package:
#. At :file:`~/clearlinux/packages/dmidecode`, build the modified
``dmidecode`` package:
.. code-block:: bash
@@ -216,98 +210,31 @@ and rebuild the package.
When the process completes, you will see new RPM packages in the
:file:`results/` folder.
#. To view the new RPM packages, enter:
#. To view the new RPM packages, enter:
.. code-block:: bash
ls /clearlinux/packages/dmidecode/results/
ls /clearlinux/packages/dmidecode/results/
Add a custom RPM to a mix and deploy to target
**********************************************
We need a RPM repository to store our custom RPMs. This repository also
includes some metadata that allows programs such as ``yum`` and ``dnf`` to
follow and include any specified dependencies. This architecture enables us
to test custom RPMs before we integrate them in a mix.
.. note::
Assure that you followed the :ref:`mixer` instruction and created
a location for **local RPM packages** using the *--local-rpms* flag
with the command: :command:`mixer init --local-rpms`. If you skipped
this step, return and complete it in :ref:`mixer` before proceeding.
.. _copy-rpm-packages-to-mixer:
Copy RPM packages to mixer and build bundle
============================================
Transfer the newly generated RPM packages to the ``mixer`` folder so
that it can include them as needed.
.. note::
This guide assumes that you have a web server that hosts ``swupd`` update
content.
#. Change directory into the mix workspace:
.. code-block:: bash
cd ~/mix
#. Copy the contents from the results folder in the RPM packages to the
:file:`local-rpms` folder in the :file:`mix` folder:
.. code-block:: bash
cp ~/clearlinux/packages/dmidecode/results/*x86_64*rpm ~/mix/local-rpms/
#. Remove the debuginfo:
.. code-block:: bash
rm ~/mix/local-rpms/*debuginfo*x86_64*
#. Generate the yum repo:
.. code-block:: bash
sudo mixer add-rpms
#. Create a local bundle definition file to include the newly generated RPM
package in your mix. In our example, the ``[bundle-name]`` is
either ``dmidecode`` or ``helloclear``.
.. code-block:: bash
mixer bundle edit [bundle-name]
#. Then add the new bundle to the mix.
.. code-block:: bash
mixer bundle add [bundle-name]
#. Build the bundle and update content.
.. code-block:: bash
sudo mixer build all
#. Log into the target device.
#. On the target device, update and install the new bundle.
.. code-block:: bash
sudo swupd update
sudo swupd bundle-add [bundle-name]
**Congratulations!**
You successfully built a RPM and created a mix with it.
You've successfully created a RPM.
Use your RPM
************
Now you can create a custom bundle with your new RPM and use it with |CL|:
* Use the :ref:`Mixer tool <mixer>` to add a new bundle to your derivative of |CL|
* Use the :ref:`Mixin tool <mixin>` to customize your upstream |CL| installation with a new bundle
Related topics
**************
* :ref:`Mixer tool <mixer>`
* :ref:`Mixin tool <mixin>`
* :ref:`autospec <autospec-about>`
.. _rpm website: http://rpm.org