Autospec concept updates

- Get rid of whitespace
- Simplify intro (use training as ref)
- Remove overview heading to be consistent with other pages
- Remove list of control files in preference of existing table of common control files and ref to complete list in readme
- Add Related topics at end of article
- Remove unused overview section incl markers (no references after update to autospec guide)
- Table of example control files updated to show only files to control dependencies (a logical group of control files, rather than a mix)
- Move control files into its own section at end
- Update section How autospec works to include Note bullets in the steps to give picture of complete workflow

Signed-off-by: Kristal Dale <kristal.dale@intel.com>
This commit is contained in:
Kristal Dale
2018-10-25 12:22:04 -07:00
parent d173dbd252
commit 07514bdd3f
+90 -96
View File
@@ -1,112 +1,106 @@
.. _autospec-about:
.. _autospec-about:
Autospec
########
.. _incl-autospec-overview:
A standard RPM build process using ``rpmbuild`` requires a tarball and .spec
file to start. The .spec provides information about a package, how to
build it, as well as what should be installed and where.
Overview
********
Whereas a standard RPM build process using ``rpmbuild`` requires a tarball
and ``spec`` file to start, ``autospec`` only requires a tarball and package
name. ``autospec`` analyzes the source code and :file:`Makefile` information
in order to generate a ``spec`` file for you. Although not required, you can
influence ``autospec`` by providing control files.
.. code-block:: console
buildreq_add
buildreq__ban
pkgconfig_add
pkgconfig_ban
requires_add
requires_ban
options.conf
build_pattern
These files should be located in same directory as the resulting ``spec``
file.
.. note::
For a comprehensive list of control files, view the `autospec readme`_.
.. _incl-autospec-overview-end:
Control files are explained in Table 1.
.. list-table:: **Table 1. Control Files**
:widths: 20 80
:header-rows: 1
* - Filename
- Description
* - buildreq_add
- Each line in the file provides the name of a package to add as a
build dependency to the ``spec``.
* - buildreq_ban
- Each line in the file is a build dependency that under no
circumstance should be automatically added to the build dependencies.
This is useful to block automatic configuration routines adding
undesired functionality, or to omit any automatically discovered
dependencies during tarball scanning.
* - pkgconfig_add
- Each line in the file is assumed to be a pkgconfig() build
dependency. Add the pkg-config names here, as ``autospec`` will
automatically transform the names into their ``pkgconfig($name)``
style when generating the ``spec``.
* - pkgconfig_ban
- Each line in this file is a pkgconfig() build dependency that should
not be added automatically to the build, much the same as
`` buildreq_ban``. As with ``pkgconfig_add``, these names are
automatically transformed by ``autospec`` into their correct
``pkgconfig($name))`` style.
* - requires_add
- Each line in the file provides the name of a package to add as a
runtime dependency to the ``spec``.
* - requires_ban
- Each line in the file is a runtime dependency that under no
circumstance should be automatically added to the runtime
dependencies. This is useful to block automatic configuration
routines adding undesired functionality, or to omit any automatically
discovered dependencies during tarball scanning.
* - build_pattern
- In certain situations, the automatically detected build pattern may
not work for the given package. This one line file allows you to
override the build pattern that ``autospec`` will use.
* - options.conf
- Further control of the build can be achieved through the use of the
``options.conf`` file. If this file does not exist it is created by
autospec with default values. If certain deprecated configuration
files exists autospec will use the value indicated by those files and
remove them.
``autospec`` is a tool to assist in the automated creation and maintenance of
RPM packaging in |CL-ATTR|. Compared to ``rpmbuild``, ``autospec`` requires
only a tarball and package name to start.
How autospec works
******************
Autospec attempts to infer the requirements of the ``spec`` file. If
autospec infers correctly, the control files (Table 1) will automatically
correct the build requirements. The control files are used to influence
the ``spec`` file generation.
``autospec`` attempts to infer the requirements of the .spec file
by analyzing the source code and :file:`Makefile` information.
It will continuously run updated builds based on new information
discovered from build failures until it has a complete and valid .spec file.
You may optionally influence the behavior of ``autospec`` by providing
:ref:`control files <control-files>`.
#. The :command:`make autospec` command generates a ``spec`` file from the
control files.
#. The :command:`make autospec` command generates a .spec based on
analysis of code and control files, if present.
#. ``autospec`` creates a ``build root`` with ``mock`` config.
#. ``autospec`` attempts to build an RPM from the generated ``spec`` file.
#. ``autospec`` detects any missed declarations in the ``spec`` file.
#. ``autospec`` creates a ``build root`` with ``mock`` config.
.. note::
#. ``autospec`` attempts to build an RPM from the generated .spec.
* If there are missed declarations, ``autospec`` creates another ``mock``
``chroot`` and starts building again at Step 1.
* If a build error occurs, ``autospec`` stops for user inspection.
* If no build errors occur, RPM packages are successfully built.
#. ``autospec`` detects any missed declarations in the .spec.
``autospec`` continues to rebuild the package, based on new information
discovered from build failures until it has a valid ``spec`` file.
#. If a build error occurs, ``autospec`` stops for user inspection and
editing of control files to resolve issues.
#. After user inspection, ``autospec`` creates another ``mock`` ``chroot``
and starts building again at Step 1.
Following these steps, ``autospec`` continues to rebuild the package, based on
new information discovered from build failures until it has a valid .spec. If
no build errors occur, RPM packages are successfully built.
.. _control-files:
Control files
*************
It is possible to influence the behavior of ``autospec`` by providing control
files. These files may be used to alter the default behavior of the configure
routine, to blacklist build dependencies, etc. Control files must be located
in the same directory as the resulting .spec.
Table 1 shows control files used to control dependencies, for example.
.. list-table:: **Table 1. Control files to control dependencies**
:widths: 20 80
:header-rows: 1
* - Filename
- Description
* - buildreq_add
- Each line in the file provides the name of a package to add as a
build dependency to the .spec.
* - buildreq_ban
- Each line in the file is a build dependency that under no
circumstance should be automatically added to the build dependencies.
This is useful to block automatic configuration routines adding
undesired functionality, or to omit any automatically discovered
dependencies during tarball scanning.
* - pkgconfig_add
- Each line in the file is assumed to be a pkgconfig() build
dependency. Add the pkg-config names here, as ``autospec`` will
automatically transform the names into their ``pkgconfig($name)``
style when generating the .spec.
* - pkgconfig_ban
- Each line in this file is a pkgconfig() build dependency that should
not be added automatically to the build, much the same as
`` buildreq_ban``. As with ``pkgconfig_add``, these names are
automatically transformed by ``autospec`` into their correct
``pkgconfig($name))`` style.
* - requires_add
- Each line in the file provides the name of a package to add as a
runtime dependency to the .spec.
* - requires_ban
- Each line in the file is a runtime dependency that under no
circumstance should be automatically added to the runtime
dependencies. This is useful to block automatic configuration
routines adding undesired functionality, or to omit any automatically
discovered dependencies during tarball scanning.
Further control of the build can be achieved through the use of the
``options.conf`` file. If this file does not exist, it is created by
``autospec`` with default values. If certain deprecated configuration
files exists ``autospec`` will use the value indicated by those files and
remove them.
For a comprehensive list of control files, view the `autospec readme`_.
Related topics
**************
* :ref:`autospec`
* :ref:`mixer`
* :ref:`mixin`
.. _autospec readme: https://github.com/clearlinux/autospec