diff --git a/source/guides/clear/autospec.rst b/source/guides/clear/autospec.rst
index 7dabfd58..3e725bb4 100644
--- a/source/guides/clear/autospec.rst
+++ b/source/guides/clear/autospec.rst
@@ -16,17 +16,16 @@ tarball and package name to start.
Description
***********
-The autospec tool attempts to infer the requirements of the :file:`.spec` file
-by analyzing the source code and :file:`Makefile` information. It
-continuously runs updated builds based on new information discovered from build
-failures until it has a complete and valid :file:`.spec` file. If needed, you
-can influence the behavior of autospec and customize the build by providing
-optional `control files`_ to the autospec tool.
+The autospec tool attempts to infer the requirements of the :file:`.spec`
+file by analyzing the source code and :file:`Makefile` information. It
+continuously runs updated builds based on new information discovered from
+build failures until it has a complete and valid :file:`.spec` file. If
+needed, you can influence the behavior of autospec and customize the build by providing optional `control files`_ to the autospec tool.
-autospec uses **mock** as a sandbox to run the builds. Visit the `mock wiki`_ for
-additional information on using mock.
+autospec uses **mock** as a sandbox to run the builds. Visit the `mock wiki`_
+for additional information on using mock.
-For a general understanding of how an RPM works, visit
+For a general understanding of how an RPM works, visit
the `rpm website`_ or the `RPM Packaging Guide`_.
How it works
@@ -52,13 +51,11 @@ Create an RPM
The basic autospec process is described in the following steps:
-#. The :command:`make autospec` command generates a :file:`.spec` file based on
- the analysis of code and existing control files.
+#. The :command:`make autospec` command generates a :file:`.spec` file based
+ on the analysis of code and existing control files.
Any control files should be located in the same directory as the resulting
- :file:`.spec` file.
-
- View the `autospec README`_ for more information on `control files`_.
+ :file:`.spec` file. View the `autospec README`_ for more information on `control files`_.
#. autospec creates a build root with mock config.
@@ -99,8 +96,8 @@ Complete `Setup environment to build source`_ before using these examples.
Example 1: Build RPM with an existing spec file
===============================================
-This example shows how to build a RPM from a pre-packaged upstream package with
-an existing spec file. The example uses the ``dmidecode`` package.
+This example shows how to build a RPM from a pre-packaged upstream package
+with an existing spec file. The example uses the ``dmidecode`` package.
#. Navigate to the autospec workspace and clone the ``dmidecode`` package:
@@ -129,8 +126,8 @@ an existing spec file. The example uses the ``dmidecode`` package.
cd ~/clearlinux/packages/dmidecode/
make build
-#. The resulting RPMs are in :file:`./rpms`. Build logs and additional RPMs are
- in :file:`./results`.
+#. The resulting RPMs are in :file:`./rpms`. Build logs and additional RPMs
+ are in :file:`./results`.
Example 2: Build a new RPM
==========================
@@ -140,23 +137,23 @@ create a simple helloclear RPM.
#. Navigate to the autospec workspace and build the helloclear RPM. The
:file:`Makefile` provides a :command:`make autospecnew` that can
- automatically generate an RPM package using the autospec tool. You must pass
- the URL to the source tarball and the NAME of the RPM you wish to create:
+ automatically generate an RPM package using the autospec tool. You must
+ pass the URL to the source tarball and the NAME of the RPM you wish to
+ create:
.. code-block:: bash
cd ~/clearlinux
make autospecnew URL="https://github.com/clearlinux/helloclear/archive/helloclear-v1.0.tar.gz" NAME="helloclear"
- The resulting RPMs are in :file:`./packages/helloclear/rpms`. Build logs and
- additional RPMs are in :file:`./packages/helloclear/results`.
+ The resulting RPMs are in :file:`./packages/helloclear/rpms`. Build logs and additional RPMs are in :file:`./packages/helloclear/results`.
Example 3: Generate a new spec file with a pre-defined package
==============================================================
-This example shows how to modify an existing package to create a custom RPM. In
-this example you will make a simple change to the ``dmidecode`` package and
-rebuild the package.
+This example shows how to modify an existing package to create a custom RPM.
+In this example you will make a simple change to the ``dmidecode`` package
+and rebuild the package.
#. Navigate to the autospec workspace and clone the ``dmidecode`` package:
@@ -187,7 +184,8 @@ rebuild the package.
These files aren't needed by dmidecode, so we can remove them without
any issues.
-#. In the :file:`dmidecode` directory, build the modified ``dmidecode`` package:
+#. In the :file:`dmidecode` directory, build the modified ``dmidecode``
+ package:
.. code-block:: bash
@@ -199,8 +197,8 @@ Example 4: Provide control files to autospec
============================================
This example shows how to modify control files to correct build failures that
-autospec is unable to resolve. In this example, you will add a missing license
-and dependencies so autospec can complete a successful build.
+autospec is unable to resolve. In this example, you will add a missing
+license and dependencies so autospec can complete a successful build.
#. Navigate to the autospec workspace:
@@ -218,8 +216,8 @@ and dependencies so autospec can complete a successful build.
.. note::
- In a later step of this example, we will search the cloned package repos
- for a missing dependency.
+ In a later step of this example, we will search the cloned package
+ repos for a missing dependency.
#. Build the opae-sdk RPM:
@@ -241,7 +239,7 @@ and dependencies so autospec can complete a successful build.
#. Add one or more valid license identifiers from the
`SPDX License List `_.
- In the example below, two different licenses are appropriate based on the
+ In the example below, two different licenses are appropriate based on the
opae-sdk project licensing:
.. code-block:: bash
@@ -271,7 +269,9 @@ and dependencies so autospec can complete a successful build.
.. code-block:: console
- CMake Error: The following variables are used in this project, but they are set to NOTFOUND. Please set them or make sure they are set and tested correctly in the CMake files:
+ CMake Error: The following variables are used in this project, but
+ they are set to NOTFOUND. Please set them or make sure they are set and tested correctly in the CMake files:
+
CJSON_LIBRARY
linked by target "opae-c++-utils" in directory /builddir/build/BUILD/opae-sdk-0.13.0/tools/c++utilslib
json-c_LIBRARIES
@@ -279,9 +279,8 @@ and dependencies so autospec can complete a successful build.
libuuid_LIBRARIES
linked by target "opae-c" in directory /builddir/build/BUILD/opae-sdk-0.13.0/libopae
-#. Search the spec files of upstream |CL| packages to see if the json-c library
- is available. In this case, it does exist and we'll add the json-c 'dev'
- package into the buildreq_add:
+#. Search the spec files of upstream |CL| packages to see if the json-c
+ library is available. In this case, it does exist and we'll add the json-c 'dev' package into the buildreq_add:
.. code-block:: bash
@@ -290,31 +289,26 @@ and dependencies so autospec can complete a successful build.
.. note::
- This search step works only if the user cloned all of the upstream package
- repos. In this example, upstream package repos were cloned in a previous
- step.
+ This search step works only if the user cloned all of the upstream package repos. In this example, upstream package repos were cloned in a previous step.
-#. Search the spec files of upstream |CL| packages to see if the libuuid library
- is available. In this case, it exists in the util-linux package, so we'll add
- util-linux-dev package into the buildreq_add:
+#. Search the spec files of upstream |CL| packages to see if the libuuid
+ library is available. In this case, it exists in the util-linux package, so we'll add util-linux-dev package into the buildreq_add:
.. code-block:: bash
grep 'libuuid\.so$' ~/clearlinux/packages/*/*.spec
echo "util-linux-dev" >> buildreq_add
-#. Run autospec again and find the successfully-generated RPMs in the :file:`rpms`
- directory:
+#. Run autospec again and find the successfully-generated RPMs in the
+ :file:`rpms` directory:
.. code-block:: bash
make autospec
-.. note::
+ .. note::
- If you need a dependency that does not exist in the |CL| repo, you must first
- build it manually (see `Example 2: Build a new RPM`_), then add the repo so
- that autospec knows the package exists. For example:
+ If you need a dependency that does not exist in the |CL| repo, you must first build it manually (see `Example 2: Build a new RPM`_), then add the repo so that autospec knows the package exists. For example:
.. code-block:: bash
@@ -322,9 +316,102 @@ and dependencies so autospec can complete a successful build.
make repoadd
make repostatus
- You only need to add the dependency to the :file:`buildreq_add` control file
- if autospec is not able to automatically find the correct dependency on its
- own.
+ You only need to add the dependency to the :file:`buildreq_add` control
+ file if autospec is not able to automatically find the correct dependency
+ on its own.
+
+.. TODO: Document how to set up a license server for use with autospec.
+.. TODO: Demonstrate control file management. Establish specific use cases.
+
+Example 5: Update an existing package
+=====================================
+
+The |CL| team prefers to carry no patches and seeks to make the latest
+releases work. If we do need patches, we use :command:`autospec` to add,
+remove, or manage patches. The :command:`autospec` control files are
+integral to the patch management process. Developers can expect a more
+streamlined approach to managing a large collection of packages with
+:command:`autospec`.
+
+Adding and submitting patches
+-----------------------------
+
+* To add patches to |CL| upstream, follow `patching source code`_.
+
+* To submit a patch to upstream, follow
+ `contributing to an existing software package`_.
+
+If you maintain a downstream derivative of |CL| and you want to integrate
+new or patched packages into your mix, follow the process in :ref:`mixer`.
+
+Assuming you have followed the above process, :command:`autospec` has
+generated a new spec file.
+
+Refresh a package and inspect
+-----------------------------
+
+In this example, we use autospec to refresh the :command:`m4` package and
+recreate RPM files.
+
+#. Navigate to the top-level directory of the workspace
+
+ .. code-block:: bash
+
+ cd clearlinux
+
+ - where :command:`clearlinux` is the top level of the tooling workspace
+
+#. Run the make_clone command and then navigate to the package.
+
+ .. code-block:: bash
+
+ make clone_m4
+
+ cd packages/m4
+
+#. Make desired changes to the package, its control files, or
+ other files.
+
+#. Finally, run:
+
+ .. code-block:: bash
+
+ make autospec
+
+#. To view spec file changes, run:
+
+ .. code-block:: bash
+
+ git show m4.spec
+
+ The output shows:
+
+ .. code-block:: console
+
+ m4: Autospec creation for version 1.4.18
+
+ diff --git a/m4.spec b/m4.spec
+ index f76c78d..97b846a 100644
+ --- a/m4.spec
+ +++ b/m4.spec
+ @@ -6,15 +6,14 @@
+ #
+ Name : m4
+ Version : 1.4.18
+ -Release : 88
+ +Release : 89
+ URL : http://mirrors.kernel.org/gnu/m4/m4-1.4.18.tar.xz
+ Source0 : http://mirrors.kernel.org/gnu/m4/m4-1.4.18.tar.xz
+ -Source99 : http://mirrors.kernel.org/gnu/m4/m4-1.4.18.tar.xz.sig
+ +Source1 : http://mirrors.kernel.org/gnu/m4/m4-1.4.18.tar.xz.sig
+ Summary : No detailed summary available
+ Group : Development/Tools
+ ...
+
+#. The following commands provide a more complete view of the changes.
+
+ * :command:`git log -p`
+ * :command:`gitk`
Test packaged software
**********************
@@ -338,7 +425,7 @@ generated RPMs.
.. note::
The methods outlined below should only be used for temporary testing on
- development systems.
+ development systems.
Test in a |CL| virtual machine
@@ -346,7 +433,7 @@ Test in a |CL| virtual machine
The |CL| development tooling includes a method to install RPMs into a |CL|
virtual machine running on the KVM hypervisor. Using a :abbr:`VM (Virtual
-Machine)` allows testing in a completely isolated environment.
+Machine)` allows testing in a completely isolated environment.
To test an autospec-created package inside a VM:
@@ -402,8 +489,8 @@ To test an autospec-created package inside a VM:
deleted:
.. code-block:: bash
-
- poweroff
+
+ poweroff
rm clear.img
@@ -504,9 +591,16 @@ Related topics
* :ref:`Mixer tool `
+.. _contributing to an existing software package: https://github.com/clearlinux/distribution/blob/master/contributing.md#contributing-to-an-existing-software-package
+
+.. _patching source code: https://github.com/clearlinux/distribution/blob/master/contributing.md#patching-source-code
+
.. _`Makefile.common`: https://github.com/clearlinux/common/blob/master/Makefile.common
.. _autospec README: https://github.com/clearlinux/autospec
.. _control files: https://github.com/clearlinux/autospec#control-files
.. _mock wiki: https://github.com/rpm-software-management/mock/wiki
.. _rpm website: http://rpm.org
.. _RPM Packaging Guide: https://rpm-packaging-guide.github.io/
+
+
+.. TODO: Add link to how to submit a new package: https://github.com/clearlinux/distribution/blob/master/contributing.md#contributing-a-new-software-package
\ No newline at end of file