From f78db69a1e11eefd519804aafe5aa2bc830403b6 Mon Sep 17 00:00:00 2001 From: michael vincerra <37549381+mvincerx@users.noreply.github.com> Date: Fri, 27 Sep 2019 14:48:05 -0700 Subject: [PATCH] Revert "Add Example 5 for updating an existing package in autospec. (#827)" This reverts commit 7861c356db70c313674db78b18309bff09691e3d. --- source/guides/clear/autospec.rst | 202 +++++++++---------------------- 1 file changed, 54 insertions(+), 148 deletions(-) diff --git a/source/guides/clear/autospec.rst b/source/guides/clear/autospec.rst index 3e725bb4..7dabfd58 100644 --- a/source/guides/clear/autospec.rst +++ b/source/guides/clear/autospec.rst @@ -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 `_. - 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 ` -.. _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