diff --git a/source/clear-linux/guides/maintenance/autospec.rst b/source/clear-linux/guides/maintenance/autospec.rst index 257f8e2c..af8cac90 100644 --- a/source/clear-linux/guides/maintenance/autospec.rst +++ b/source/clear-linux/guides/maintenance/autospec.rst @@ -1,36 +1,91 @@ .. _autospec: -Build RPMs with autospec -######################## +autospec +######## -This guide shows you how to create RPMs with :ref:`autospec `, -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 ` 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 `, a tool that assists in automated creation and maintenance of RPM packaging on |CL-ATTR|. + +.. See our :ref:`autospec concept page ` 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 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_ + +#. 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:// - -#. 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 ` to add a new bundle to your derivative of |CL|. -* Use the :ref:`Mixin tool ` to customize your upstream |CL| installation with a new bundle. +* Use the :ref:`Mixer tool ` to add a new bundle to your derivative of + |CL|. +* Use the :ref:`Mixin tool ` to customize your upstream |CL| installation + with a new bundle. Related topics ************** @@ -235,11 +248,8 @@ Related topics * :ref:`autospec ` * :ref:`Bundles ` +.. _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