clearlinux/clear-linux-documentation
2
0
Fork 0
mirror of https://github.com/clearlinux/clear-linux-documentation.git synced 2026-09-05 13:21:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update autospec guide

Browse Source 
- Apply guide template
- Update examples per latest

Signed-off-by: Kristal Dale <kristal.dale@intel.com>
This commit is contained in:
Kristal Dale
2019-02-12 11:13:14 -08:00
parent a7c82b0477
commit 32a703810b
1 changed files with 134 additions and 124 deletions
Download Patch File Download Diff File Expand all files Collapse all files
source/clear-linux/guides/maintenance/autospec.rst
+134 -124
View File
@@ -1,36 +1,91 @@
.. _autospec:
Build RPMs with autospec
########################
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 |CL-ATTR|.
autospec is a tool to assist in the automated creation and maintenance of RPM
packaging in |CL-ATTR|. Where a standard RPM build process using rpmbuild
requires a tarball and :file:`.spec` file to start, autospec requires only a
tarball and package name to start.
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`_ .
.. contents::
:local:
:depth: 1
.. Todo: this should be the concept content
.. 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`_ .
Description
***********
.. TODO
How to use autospec
*******************
Learn the autospec tool set up and workflow.
.. contents::
:local:
:depth: 1
Prerequisites
*************
=============
This guide requires that you:
#. **OS installed**
* Have installed |CL| on a host machine or virtual environment. For detailed
instructions on installing |CL|, visit the :ref:`get-started` section.
The |CL| must be installed to use the autospec tool.
* :ref:`install-tooling`
#. **Required bundles**
.. _install-tooling:
The autospec tool requires that the :command:`os-clr-on-clr` and bundle is
installed.
Install the |CL| tooling framework
==================================
Workflow
========
#. Install the `os-clr-on-clr` developer bundle on your host system.
First time setup
----------------
.. code-block:: bash
Before you use autospec, you will need to set up the autospec environment and
tools. This is mostly automated for you by using the provided
:file:`user_setup.sh` script.
sudo swupd bundle-add os-clr-on-clr
The `user-setup script`_ creates the :file:`clearlinux` folder, which contains
the :file:`Makefile`, :file:`packages`, and :file:`projects` subfolders. The
:file:`projects` folder contains the main tools, `autospec` and `common`, used
for making packages in |CL|.
Create a RPM
------------
autospec helps build RPMs following these basic steps:
#. Run autospec, passing in the tarball URL and package name.
#. If there are build failures or dependency issues, supply the necessary
dependency, ban, or exclusion information via control files to autospec.
View the `autospec README`_ for more information on control files.
If a binary dependency doesn't exist in |CL|, you will need to build it
before running autospec again.
#. Run autospec again.
#. Repeat steps 2-3 until all errors are resolved, resulting in a successful
build.
Examples
********
Example 1: First time setup
===========================
This example shows the basic steps for first time setup of autospec.
#. Download the :file:`user-setup.sh` script.
@@ -50,56 +105,62 @@ Install the |CL| tooling framework
./user-setup.sh
#. After the script completes, log out and log in again to complete
the setup process.
#. After the script completes, log out and log in again to complete the setup
process.
The `user-setup script`_ creates a folder called :file:`clearlinux`, which
contains the :file:`Makefile`, :file:`packages`, and :file:`projects`
subfolders.
#. Set your Git user email and username for the repos on your system
The :file:`projects` folder contains the main tools, `autospec`
and `common`, used for making packages in |CL|.
.. code-block:: bash
Create a RPM with autospec
**************************
git config --global user.email ”you@example.com"
git config --global user.name "Your Name"
Choose one of the following options to build RPMs and manage source
code:
.. TODO this last step (for GIT) - required? what is it doing?
* :ref:`build-a-new-rpm` and spec file using ``make autospecnew``.
Example 2: Build RPM with existing spec file
============================================
* :ref:`build-source-code-with-existing-spec-file` using ``make build``, without changing the
spec file.
This example shows how to build a RPM from a pre-packaged upstream package with
an existing spec file.
* :ref:`generate-a-new-spec-file` using ``make autospec``, based on changes in the control files.
#. If you do not already have them locally, clone the |CL| package definitions:
.. _build-a-new-rpm:
.. code-block:: bash
Option 1: Build a new RPM
=========================
make -j <num> clone-packages
Use this method to build a new RPM with no spec file. In this example,
we build a new helloclear RPM.
Alternately, you can clone a single package using:
#. Navigate to the autospec workspace.
.. code-block:: bash
make clone_<package-name>
#. Navigate to the ``dmidecode`` package and build it:
.. code-block:: bash
cd ~/clearlinux/packages/dmidecode/
make build
#. The resulting RPMs are in :file:`./rpms`. Logs are in :file:`./results`.
Example 3: Build a new package
==============================
This example shows how to build a new RPM with no spec file.
#. Navigate to the autospec workspace and build the helloclear RPM:
.. code-block:: bash
cd ~/clearlinux
make autospecnew URL="https://github.com/clearlinux/helloclear/archive/helloclear-v1.0.tar.gz" NAME="helloclear"
#. Enter the command:
#. The resulting RPMs are in :file:`~/clearlinux/packages/helloclear/rpms`.
Logs are in :file:`~/clearlinux/packages/helloclear/results`.
.. code-block:: bash
make autospecnew URL="https://github.com/clearlinux/helloclear/archive/helloclear-v1.0.tar.gz"
NAME="helloclear"
.. note::
For a local tarball, use this type of *URL*: \file://<absolute-path-to-tarball>
#. If build failures or dependency issues occur, continue below.
Otherwise, skip directly to `Next steps`_.
#. If build failures or dependency issues occur, provide the necessary
dependency, ban, or exclusion information via control files to autospec:
#. Navigate to the specific package.
@@ -108,10 +169,10 @@ we build a new helloclear 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.
See `autospec readme`_
issues, which may include dependencies or exclusions. See
`autospec README`_ for more information on control files.
#. Run this command:
#. Run autospec again:
.. code-block:: bash
@@ -120,59 +181,20 @@ we build a new helloclear RPM.
Repeat the last two steps above until all errors are resolved and you
complete a successful build.
**Congratulations!**
You've successfully created a RPM.
Example 4: Generate a new spec file with a pre-defined package
==============================================================
Skip to `Next steps`_.
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, change
the revision to a new number higher than the |CL| OS version, and rebuild the
package.
.. _build-source-code-with-existing-spec-file:
Option 2: Build source code with an existing spec file
======================================================
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:
.. code-block:: bash
cd ~/clearlinux/packages/dmidecode/
#. To download the tarball and build, run the command:
.. code-block:: bash
make build
**Congratulations!**
You've successfully created a RPM.
Skip to `Next steps`_.
.. _generate-a-new-spec-file:
Option 3: Generate a new spec file with a pre-defined 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:
#. Navigate to the autospec workspace and copy the ``dmidecode`` package:
.. code-block:: bash
cd ~/clearlinux
#. Copy the ``dmidecode`` package.
.. code-block:: bash
make clone_dmidecode
#. Navigate into the *dmidecode* directory:
@@ -181,9 +203,9 @@ a new number that is higher than the |CL| OS version, and rebuild the package.
cd packages/dmidecode
#. With an editor, open the :file:`excludes` file and add these lines:
#. Open the :file:`excludes` file with an editor and add these lines:
.. code-block:: bash
.. code-block:: console
/usr/bin/biosdecode
/usr/bin/ownership
@@ -197,10 +219,7 @@ a new number that is higher than the |CL| OS version, and rebuild the package.
These files aren't needed by dmidecode, so we can remove them without
any issues.
#. Save the file and exit.
#. At :file:`~/clearlinux/packages/dmidecode`, build the modified
``dmidecode`` package:
#. In the :file:`dmidecode` directory, build the modified ``dmidecode`` package:
.. code-block:: bash
@@ -209,23 +228,17 @@ a new number that is higher than the |CL| OS version, 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:
.. code-block:: bash
ls /clearlinux/packages/dmidecode/results/
**Congratulations!**
You've successfully created a RPM.
#. View the new RPM packages in :file:`/clearlinux/packages/dmidecode/results/`
Next steps
**********
Now you can create a custom bundle with your new RPM and use it with |CL|:
Create a custom bundle 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.
* 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
**************
@@ -235,11 +248,8 @@ Related topics
* :ref:`autospec <autospec-about>`
* :ref:`Bundles <bundles-about>`
.. _user-setup script: https://github.com/clearlinux/common/blob/master/user-setup.sh
.. _autospec README: https://github.com/clearlinux/autospec
.. _rpm website: http://rpm.org
.. _RPM Packaging Guide: https://rpm-packaging-guide.github.io/
.. _user-setup script: https://github.com/clearlinux/common/blob/master/user-setup.sh
.. _autospec readme: https://github.com/clearlinux/autospec