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