mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-08-24 08:48:15 +00:00
Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 michael vincerra
|
f78db69a1e |
@@ -16,16 +16,17 @@ 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
|
||||
@@ -51,11 +52,13 @@ 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.
|
||||
|
||||
@@ -96,8 +99,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:
|
||||
|
||||
@@ -126,8 +129,8 @@ with 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
|
||||
==========================
|
||||
@@ -137,23 +140,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:
|
||||
|
||||
@@ -184,8 +187,7 @@ and 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
|
||||
|
||||
@@ -197,8 +199,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:
|
||||
|
||||
@@ -216,8 +218,8 @@ license 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:
|
||||
|
||||
@@ -239,7 +241,7 @@ license and dependencies so autospec can complete a successful build.
|
||||
|
||||
#. Add one or more valid license identifiers from the
|
||||
`SPDX License List <https://spdx.org/licenses/>`_.
|
||||
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
|
||||
@@ -269,9 +271,7 @@ license 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,8 +279,9 @@ license 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
|
||||
|
||||
@@ -289,26 +290,31 @@ license 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
|
||||
|
||||
@@ -316,102 +322,9 @@ license 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.
|
||||
|
||||
.. 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`
|
||||
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.
|
||||
|
||||
Test packaged software
|
||||
**********************
|
||||
@@ -425,7 +338,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
|
||||
@@ -433,7 +346,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:
|
||||
|
||||
@@ -489,8 +402,8 @@ To test an autospec-created package inside a VM:
|
||||
deleted:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
poweroff
|
||||
|
||||
poweroff
|
||||
rm clear.img
|
||||
|
||||
|
||||
@@ -591,16 +504,9 @@ Related topics
|
||||
|
||||
* :ref:`Mixer tool <mixer>`
|
||||
|
||||
.. _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
|
||||
Reference in New Issue
Block a user