mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-08-22 23:36:58 +00:00
alexjch
678 lines
42 KiB
HTML
678 lines
42 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html lang="en" data-content_root="../../">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||
|
||
<title>autospec — Documentation for Clear Linux* project</title>
|
||
<link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=fa44fd50" />
|
||
<link rel="stylesheet" type="text/css" href="../../_static/bizstyle.css?v=5283bb3d" />
|
||
<link rel="stylesheet" type="text/css" href="../../_static/copybutton.css?v=76b2166b" />
|
||
|
||
<script src="../../_static/documentation_options.js?v=5929fcd5"></script>
|
||
<script src="../../_static/doctools.js?v=9bcbadda"></script>
|
||
<script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
|
||
<script src="../../_static/clipboard.min.js?v=a7894cd8"></script>
|
||
<script src="../../_static/copybutton.js?v=a56c686a"></script>
|
||
<script src="../../_static/bizstyle.js"></script>
|
||
<link rel="canonical" href="https://clearlinux.github.io/clear-linux-documentation/guides/clear/autospec.html" />
|
||
<link rel="icon" href="../../_static/favicon.ico"/>
|
||
<link rel="author" title="About these documents" href="../../about.html" />
|
||
<link rel="index" title="Index" href="../../genindex.html" />
|
||
<link rel="search" title="Search" href="../../search.html" />
|
||
<link rel="next" title="Bundles" href="bundles.html" />
|
||
<link rel="prev" title="Autoproxy" href="autoproxy.html" />
|
||
<meta name="viewport" content="width=device-width,initial-scale=1.0" />
|
||
<!--[if lt IE 9]>
|
||
<script src="_static/css3-mediaqueries.js"></script>
|
||
<![endif]-->
|
||
</head><body>
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="bundles.html" title="Bundles"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="autoproxy.html" title="Autoproxy"
|
||
accesskey="P">previous</a> |</li>
|
||
<li class="nav-item nav-item-0"><a href="../../index.html">Documentation for Clear Linux* project</a> »</li>
|
||
<li class="nav-item nav-item-1"><a href="../index.html" accesskey="U">Guides</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href="">autospec</a></li>
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section id="autospec">
|
||
<span id="id1"></span><h1>autospec<a class="headerlink" href="#autospec" title="Link to this heading">¶</a></h1>
|
||
<p><strong>autospec</strong> is a tool used to assist with the automated creation and
|
||
maintenance of RPM packaging in Clear Linux* OS. Where a standard
|
||
<abbr title="RPM Package Manager">RPM</abbr> build process using <strong class="command">rpmbuild</strong>
|
||
requires a tarball and <code class="file docutils literal notranslate"><span class="pre">.spec</span></code> file to start, autospec requires only a
|
||
tarball and package name to start.</p>
|
||
<nav class="contents local" id="contents">
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="#description" id="id4">Description</a></p></li>
|
||
<li><p><a class="reference internal" href="#how-it-works" id="id5">How it works</a></p></li>
|
||
<li><p><a class="reference internal" href="#examples" id="id6">Examples</a></p></li>
|
||
<li><p><a class="reference internal" href="#test-packaged-software" id="id7">Test packaged software</a></p></li>
|
||
<li><p><a class="reference internal" href="#references" id="id8">References</a></p></li>
|
||
<li><p><a class="reference internal" href="#related-topics" id="id9">Related topics</a></p></li>
|
||
</ul>
|
||
</nav>
|
||
<section id="description">
|
||
<h2><a class="toc-backref" href="#id4" role="doc-backlink">Description</a><a class="headerlink" href="#description" title="Link to this heading">¶</a></h2>
|
||
<p>The autospec tool attempts to infer the requirements of the <code class="file docutils literal notranslate"><span class="pre">.spec</span></code>
|
||
file by analyzing the source code and <code class="file docutils literal notranslate"><span class="pre">Makefile</span></code> information. It
|
||
continuously runs updated builds based on new information discovered from
|
||
build failures until it has a complete and valid <code class="file docutils literal notranslate"><span class="pre">.spec</span></code> file. If
|
||
needed, you can influence the behavior of autospec and customize the build by providing optional <a class="reference external" href="https://github.com/clearlinux/autospec#control-files">control files</a> to the autospec tool.</p>
|
||
<p>autospec uses <strong>mock</strong> as a sandbox to run the builds. Visit the <a class="reference external" href="https://github.com/rpm-software-management/mock/wiki">mock wiki</a>
|
||
for additional information on using mock.</p>
|
||
<p>For a general understanding of how an RPM works, visit
|
||
the <a class="reference external" href="http://rpm.org">rpm website</a> or the <a class="reference external" href="https://rpm-packaging-guide.github.io/">RPM Packaging Guide</a>.</p>
|
||
<iframe width="560" height="315" src="https://www.youtube.com/embed/qrUpt1D1YAw" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen style="padding:10px; background-color: #fff;"></iframe></section>
|
||
<section id="how-it-works">
|
||
<h2><a class="toc-backref" href="#id5" role="doc-backlink">How it works</a><a class="headerlink" href="#how-it-works" title="Link to this heading">¶</a></h2>
|
||
<p>Learn the autospec tool set up and process.</p>
|
||
<nav class="contents local" id="id2">
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="#prerequisites" id="id10">Prerequisites</a></p></li>
|
||
<li><p><a class="reference internal" href="#create-an-rpm" id="id11">Create an RPM</a></p></li>
|
||
</ul>
|
||
</nav>
|
||
<section id="prerequisites">
|
||
<h3><a class="toc-backref" href="#id10" role="doc-backlink">Prerequisites</a><a class="headerlink" href="#prerequisites" title="Link to this heading">¶</a></h3>
|
||
<p>The setup for building source in Clear Linux OS must be completed before using the
|
||
autospec tool.</p>
|
||
<p>Refer to <a class="reference internal" href="#setup-environment-to-build-source">Setup environment to build source</a> for instructions on completing
|
||
the setup.</p>
|
||
</section>
|
||
<section id="create-an-rpm">
|
||
<h3><a class="toc-backref" href="#id11" role="doc-backlink">Create an RPM</a><a class="headerlink" href="#create-an-rpm" title="Link to this heading">¶</a></h3>
|
||
<p>The basic autospec process is described in the following steps:</p>
|
||
<ol class="arabic">
|
||
<li><p>The <strong class="command">make autospec</strong> command generates a <code class="file docutils literal notranslate"><span class="pre">.spec</span></code> file based
|
||
on the analysis of code and existing control files.</p>
|
||
<p>Any control files should be located in the same directory as the resulting
|
||
<code class="file docutils literal notranslate"><span class="pre">.spec</span></code> file. View the <a class="reference external" href="https://github.com/clearlinux/autospec">autospec README</a> for more information on <a class="reference external" href="https://github.com/clearlinux/autospec#control-files">control files</a>.</p>
|
||
</li>
|
||
<li><p>autospec creates a build root with mock config.</p></li>
|
||
<li><p>autospec attempts to build an RPM from the generated <code class="file docutils literal notranslate"><span class="pre">.spec</span></code>.</p></li>
|
||
<li><p>autospec detects any missed declarations in the <code class="file docutils literal notranslate"><span class="pre">.spec</span></code>.</p></li>
|
||
<li><p>If build errors occur, autospec scans the build log to try to detect
|
||
the root cause.</p></li>
|
||
<li><p>If autospec detects the root cause and knows how to continue, it restarts
|
||
the build automatically at step 1 with updated build instructions.</p></li>
|
||
<li><p>Otherwise, autospec stops the build for user inspection to resolve the
|
||
errors. Respond to the build process output by fixing source code issues
|
||
and/or editing control files to resolve issues, which may include
|
||
dependencies or exclusions. See <a class="reference external" href="https://github.com/clearlinux/autospec">autospec README</a> for more information on
|
||
control files.</p>
|
||
<p>The user resumes the process at step 1 after errors are resolved.</p>
|
||
<p>If a binary dependency doesn’t exist in Clear Linux OS, you must build it
|
||
before running autospec again.</p>
|
||
</li>
|
||
</ol>
|
||
<p>Following these steps, autospec continues to rebuild the package, based on
|
||
new information discovered from build failures, until it has a valid
|
||
<code class="file docutils literal notranslate"><span class="pre">.spec</span></code>. If no build errors occur, RPM packages are successfully built.</p>
|
||
</section>
|
||
</section>
|
||
<section id="examples">
|
||
<h2><a class="toc-backref" href="#id6" role="doc-backlink">Examples</a><a class="headerlink" href="#examples" title="Link to this heading">¶</a></h2>
|
||
<p>Complete <a class="reference internal" href="#setup-environment-to-build-source">Setup environment to build source</a> before using these examples.</p>
|
||
<nav class="contents local" id="id3">
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="#example-1-build-rpm-with-an-existing-spec-file" id="id12">Example 1: Build RPM with an existing spec file</a></p></li>
|
||
<li><p><a class="reference internal" href="#example-2-build-a-new-rpm" id="id13">Example 2: Build a new RPM</a></p></li>
|
||
<li><p><a class="reference internal" href="#example-3-generate-a-new-spec-file-with-a-pre-defined-package" id="id14">Example 3: Generate a new spec file with a pre-defined package</a></p></li>
|
||
<li><p><a class="reference internal" href="#example-4-provide-control-files-to-autospec" id="id15">Example 4: Provide control files to autospec</a></p></li>
|
||
<li><p><a class="reference internal" href="#example-5-update-an-existing-package" id="id16">Example 5: Update an existing package</a></p></li>
|
||
</ul>
|
||
</nav>
|
||
<section id="example-1-build-rpm-with-an-existing-spec-file">
|
||
<h3><a class="toc-backref" href="#id12" role="doc-backlink">Example 1: Build RPM with an existing spec file</a><a class="headerlink" href="#example-1-build-rpm-with-an-existing-spec-file" title="Link to this heading">¶</a></h3>
|
||
<p>This example shows how to build a RPM from a pre-packaged upstream package
|
||
with an existing spec file. The example uses the <code class="docutils literal notranslate"><span class="pre">dmidecode</span></code> package.</p>
|
||
<ol class="arabic">
|
||
<li><p>Navigate to the autospec workspace and clone the <code class="docutils literal notranslate"><span class="pre">dmidecode</span></code> package:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span><span class="w"> </span>~/clearlinux
|
||
make<span class="w"> </span>clone_dmidecode
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>You can clone all package repos at once using the following command:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>make<span class="w"> </span><span class="o">[</span>-j<span class="w"> </span>NUM<span class="o">]</span><span class="w"> </span>clone-packages
|
||
</pre></div>
|
||
</div>
|
||
<p>The optional NUM is the number of threads to use.</p>
|
||
<p>For a list of available packages, view the
|
||
<code class="file docutils literal notranslate"><span class="pre">~/clearlinux/projects/common/packages</span></code> file.</p>
|
||
</div>
|
||
</li>
|
||
<li><p>Navigate to the local copy of the <code class="docutils literal notranslate"><span class="pre">dmidecode</span></code> package and build it:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span><span class="w"> </span>~/clearlinux/packages/dmidecode/
|
||
make<span class="w"> </span>build
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>The resulting RPMs are in <code class="file docutils literal notranslate"><span class="pre">./rpms</span></code>. Build logs and additional RPMs
|
||
are in <code class="file docutils literal notranslate"><span class="pre">./results</span></code>.</p></li>
|
||
</ol>
|
||
</section>
|
||
<section id="example-2-build-a-new-rpm">
|
||
<h3><a class="toc-backref" href="#id13" role="doc-backlink">Example 2: Build a new RPM</a><a class="headerlink" href="#example-2-build-a-new-rpm" title="Link to this heading">¶</a></h3>
|
||
<p>This example shows how to build a new RPM with no spec file. The example will
|
||
create a simple helloclear RPM.</p>
|
||
<ol class="arabic">
|
||
<li><p>Navigate to the autospec workspace and build the helloclear RPM. The
|
||
<code class="file docutils literal notranslate"><span class="pre">Makefile</span></code> provides a <strong class="command">make autospecnew</strong> 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:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span><span class="w"> </span>~/clearlinux
|
||
make<span class="w"> </span>autospecnew<span class="w"> </span><span class="nv">URL</span><span class="o">=</span><span class="s2">"https://github.com/clearlinux/helloclear/archive/helloclear-v1.0.tar.gz"</span><span class="w"> </span><span class="nv">NAME</span><span class="o">=</span><span class="s2">"helloclear"</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The resulting RPMs are in <code class="file docutils literal notranslate"><span class="pre">./packages/helloclear/rpms</span></code>. Build logs and additional RPMs are in <code class="file docutils literal notranslate"><span class="pre">./packages/helloclear/results</span></code>.</p>
|
||
</li>
|
||
</ol>
|
||
</section>
|
||
<section id="example-3-generate-a-new-spec-file-with-a-pre-defined-package">
|
||
<h3><a class="toc-backref" href="#id14" role="doc-backlink">Example 3: Generate a new spec file with a pre-defined package</a><a class="headerlink" href="#example-3-generate-a-new-spec-file-with-a-pre-defined-package" title="Link to this heading">¶</a></h3>
|
||
<p>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 <code class="docutils literal notranslate"><span class="pre">dmidecode</span></code> package
|
||
and rebuild the package.</p>
|
||
<ol class="arabic">
|
||
<li><p>Navigate to the autospec workspace and clone the <code class="docutils literal notranslate"><span class="pre">dmidecode</span></code> package:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span><span class="w"> </span>~/clearlinux
|
||
make<span class="w"> </span>clone_dmidecode
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Navigate into the <em>dmidecode</em> directory:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span><span class="w"> </span>packages/dmidecode
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Open the <code class="file docutils literal notranslate"><span class="pre">excludes</span></code> file with an editor and add these lines:</p>
|
||
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">/usr/bin/biosdecode</span>
|
||
<span class="go">/usr/bin/ownership</span>
|
||
<span class="go">/usr/bin/vpddecode</span>
|
||
<span class="go">/usr/share/man/man8/biosdecode.8</span>
|
||
<span class="go">/usr/share/man/man8/ownership.8</span>
|
||
<span class="go">/usr/share/man/man8/vpddecode.8</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>These files aren’t needed by dmidecode, so we can remove them without
|
||
any issues.</p>
|
||
</div>
|
||
</li>
|
||
<li><p>In the <code class="file docutils literal notranslate"><span class="pre">dmidecode</span></code> directory, build the modified <code class="docutils literal notranslate"><span class="pre">dmidecode</span></code>
|
||
package:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>make<span class="w"> </span>autospec
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>The resulting RPMs are in <code class="file docutils literal notranslate"><span class="pre">./rpms</span></code>. Logs are in <code class="file docutils literal notranslate"><span class="pre">./results</span></code>.</p></li>
|
||
</ol>
|
||
</section>
|
||
<section id="example-4-provide-control-files-to-autospec">
|
||
<h3><a class="toc-backref" href="#id15" role="doc-backlink">Example 4: Provide control files to autospec</a><a class="headerlink" href="#example-4-provide-control-files-to-autospec" title="Link to this heading">¶</a></h3>
|
||
<p>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.</p>
|
||
<ol class="arabic">
|
||
<li><p>Navigate to the autospec workspace:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span><span class="w"> </span>~/clearlinux
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>If you have not already, clone all upstream package repos:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>make<span class="w"> </span><span class="o">[</span>-j<span class="w"> </span>NUM<span class="o">]</span><span class="w"> </span>clone-packages
|
||
</pre></div>
|
||
</div>
|
||
<p>The optional NUM is the number of threads to use.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>In a later step of this example, we will search the cloned package
|
||
repos for a missing dependency.</p>
|
||
</div>
|
||
</li>
|
||
<li><p>Build the opae-sdk RPM:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>make<span class="w"> </span>autospecnew<span class="w"> </span><span class="nv">URL</span><span class="o">=</span><span class="s2">"https://github.com/OPAE/opae-sdk/archive/0.13.0.tar.gz"</span><span class="w"> </span><span class="nv">NAME</span><span class="o">=</span><span class="s2">"opae-sdk"</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This results in an error for a missing license file:</p>
|
||
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">[FATAL] Cannot find any license or opae-sdk.license file!</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Navigate to the package with build failures:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span><span class="w"> </span>packages/opae-sdk
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Add one or more valid license identifiers from the
|
||
<a class="reference external" href="https://spdx.org/licenses/">SPDX License List</a>.
|
||
In the example below, two different licenses are appropriate based on the
|
||
opae-sdk project licensing:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">echo</span><span class="w"> </span><span class="s2">"BSD-3-Clause MIT"</span><span class="w"> </span>><span class="w"> </span>opae-sdk.license
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Run autospec again:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>make<span class="w"> </span>autospec
|
||
</pre></div>
|
||
</div>
|
||
<p>This results in a generic error:</p>
|
||
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">[FATAL] Build failed, aborting</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Open the build log to view the error details:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>cat<span class="w"> </span>./results/build.log
|
||
</pre></div>
|
||
</div>
|
||
<p>The build log contains details for the specific failures. In this
|
||
instance, there are missing dependencies:</p>
|
||
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">CMake Error: The following variables are used in this project, but</span>
|
||
<span class="go">they are set to NOTFOUND. Please set them or make sure they are set and tested correctly in the CMake files:</span>
|
||
|
||
<span class="go">CJSON_LIBRARY</span>
|
||
<span class="go"> linked by target "opae-c++-utils" in directory /builddir/build/BUILD/opae-sdk-0.13.0/tools/c++utilslib</span>
|
||
<span class="go">json-c_LIBRARIES</span>
|
||
<span class="go"> linked by target "opae-c" in directory /builddir/build/BUILD/opae-sdk-0.13.0/libopae</span>
|
||
<span class="go">libuuid_LIBRARIES</span>
|
||
<span class="go"> linked by target "opae-c" in directory /builddir/build/BUILD/opae-sdk-0.13.0/libopae</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Search the spec files of upstream Clear Linux OS 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:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>grep<span class="w"> </span><span class="s1">'json-c\.so$'</span><span class="w"> </span>~/clearlinux/packages/*/*.spec
|
||
<span class="nb">echo</span><span class="w"> </span><span class="s2">"json-c-dev"</span><span class="w"> </span>>><span class="w"> </span>buildreq_add
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>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.</p>
|
||
</div>
|
||
</li>
|
||
<li><p>Search the spec files of upstream Clear Linux OS 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:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>grep<span class="w"> </span><span class="s1">'libuuid\.so$'</span><span class="w"> </span>~/clearlinux/packages/*/*.spec
|
||
<span class="nb">echo</span><span class="w"> </span><span class="s2">"util-linux-dev"</span><span class="w"> </span>>><span class="w"> </span>buildreq_add
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Run autospec again and find the successfully-generated RPMs in the
|
||
<code class="file docutils literal notranslate"><span class="pre">rpms</span></code> directory:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>make<span class="w"> </span>autospec
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>If you need a dependency that does not exist in the Clear Linux OS repo, you must first build it manually (see <a class="reference internal" href="#example-2-build-a-new-rpm">Example 2: Build a new RPM</a>), then add the repo so that autospec knows the package exists. For example:</p>
|
||
</div>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span><span class="w"> </span>~/clearlinux/packages/<package-name>
|
||
make<span class="w"> </span>repoadd
|
||
make<span class="w"> </span>repostatus
|
||
</pre></div>
|
||
</div>
|
||
<p>You only need to add the dependency to the <code class="file docutils literal notranslate"><span class="pre">buildreq_add</span></code> control
|
||
file if autospec is not able to automatically find the correct dependency
|
||
on its own.</p>
|
||
</li>
|
||
</ol>
|
||
</section>
|
||
<section id="example-5-update-an-existing-package">
|
||
<h3><a class="toc-backref" href="#id16" role="doc-backlink">Example 5: Update an existing package</a><a class="headerlink" href="#example-5-update-an-existing-package" title="Link to this heading">¶</a></h3>
|
||
<p>The Clear Linux OS team prefers to carry no patches and seeks to make the latest
|
||
releases work. If we do need patches, we use <strong class="command">autospec</strong> to add,
|
||
remove, or manage patches. The <strong class="command">autospec</strong> control files are
|
||
integral to the patch management process. Developers can expect a more
|
||
streamlined approach to managing a large collection of packages with
|
||
<strong class="command">autospec</strong>.</p>
|
||
<section id="adding-and-submitting-patches">
|
||
<h4>Adding and submitting patches<a class="headerlink" href="#adding-and-submitting-patches" title="Link to this heading">¶</a></h4>
|
||
<ul class="simple">
|
||
<li><p>To add patches to Clear Linux OS upstream, follow <a class="reference external" href="https://github.com/clearlinux/distribution/blob/master/contributing.md#patching-source-code">patching source code</a>.</p></li>
|
||
<li><p>To submit a patch to upstream, follow
|
||
<a class="reference external" href="https://github.com/clearlinux/distribution/blob/master/contributing.md#contributing-to-an-existing-software-package">contributing to an existing software package</a>.</p></li>
|
||
</ul>
|
||
<p>If you maintain a downstream derivative of Clear Linux OS and you want to integrate
|
||
new or patched packages into your mix, follow the process in <a class="reference internal" href="mixer.html#mixer"><span class="std std-ref">mixer</span></a>.</p>
|
||
<p>Assuming you have followed the above process, <strong class="command">autospec</strong> has
|
||
generated a new spec file.</p>
|
||
</section>
|
||
<section id="refresh-a-package-and-inspect">
|
||
<h4>Refresh a package and inspect<a class="headerlink" href="#refresh-a-package-and-inspect" title="Link to this heading">¶</a></h4>
|
||
<p>In this example, we use autospec to refresh the <strong class="command">m4</strong> package and
|
||
recreate RPM files.</p>
|
||
<ol class="arabic">
|
||
<li><p>Navigate to the top-level directory of the workspace</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span><span class="w"> </span>clearlinux
|
||
</pre></div>
|
||
</div>
|
||
<ul class="simple">
|
||
<li><p>where <strong class="command">clearlinux</strong> is the top level of the tooling workspace</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p>Run the make_clone command and then navigate to the package.</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>make<span class="w"> </span>clone_m4
|
||
|
||
<span class="nb">cd</span><span class="w"> </span>packages/m4
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Make desired changes to the package, its control files, or
|
||
other files.</p></li>
|
||
<li><p>Finally, run:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>make<span class="w"> </span>autospec
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>To view spec file changes, run:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>show<span class="w"> </span>m4.spec
|
||
</pre></div>
|
||
</div>
|
||
<p>The output shows:</p>
|
||
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">m4: Autospec creation for version 1.4.18</span>
|
||
|
||
<span class="go">diff --git a/m4.spec b/m4.spec</span>
|
||
<span class="go">index f76c78d..97b846a 100644</span>
|
||
<span class="go">--- a/m4.spec</span>
|
||
<span class="go">+++ b/m4.spec</span>
|
||
<span class="go">@@ -6,15 +6,14 @@</span>
|
||
<span class="gp">#</span>
|
||
<span class="go">Name : m4</span>
|
||
<span class="go">Version : 1.4.18</span>
|
||
<span class="go">-Release : 88</span>
|
||
<span class="go">+Release : 89</span>
|
||
<span class="go">URL : http://mirrors.kernel.org/gnu/m4/m4-1.4.18.tar.xz</span>
|
||
<span class="go">Source0 : http://mirrors.kernel.org/gnu/m4/m4-1.4.18.tar.xz</span>
|
||
<span class="go">-Source99 : http://mirrors.kernel.org/gnu/m4/m4-1.4.18.tar.xz.sig</span>
|
||
<span class="go">+Source1 : http://mirrors.kernel.org/gnu/m4/m4-1.4.18.tar.xz.sig</span>
|
||
<span class="go">Summary : No detailed summary available</span>
|
||
<span class="go">Group : Development/Tools</span>
|
||
<span class="go">...</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>The following commands provide a more complete view of the changes.</p>
|
||
<ul class="simple">
|
||
<li><p><strong class="command">git log -p</strong></p></li>
|
||
<li><p><strong class="command">gitk</strong></p></li>
|
||
</ul>
|
||
</li>
|
||
</ol>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
<section id="test-packaged-software">
|
||
<h2><a class="toc-backref" href="#id7" role="doc-backlink">Test packaged software</a><a class="headerlink" href="#test-packaged-software" title="Link to this heading">¶</a></h2>
|
||
<p>After software has been packaged with autospec, the resulting RPMs can be
|
||
tested for functionality before being integrated and deployed into a Clear Linux OS
|
||
image with the <a class="reference internal" href="mixer.html#mixer"><span class="std std-ref">Mixer tool</span></a>.</p>
|
||
<p>The Clear Linux OS development tooling offers two ways to quickly test autospec
|
||
generated RPMs.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The methods outlined below should only be used for temporary testing on
|
||
development systems.</p>
|
||
</div>
|
||
<section id="test-in-a-cl-virtual-machine">
|
||
<h3>Test in a Clear Linux OS virtual machine<a class="headerlink" href="#test-in-a-cl-virtual-machine" title="Link to this heading">¶</a></h3>
|
||
<p>The Clear Linux OS development tooling includes a method to install RPMs into a Clear Linux OS
|
||
virtual machine running on the KVM hypervisor. Using a <abbr title="Virtual Machine">VM</abbr> allows testing in a completely isolated environment.</p>
|
||
<p>To test an autospec-created package inside a VM:</p>
|
||
<ol class="arabic">
|
||
<li><p>Download the Clear Linux OS KVM image into the <code class="file docutils literal notranslate"><span class="pre">~/clearlinux</span></code> directory as
|
||
<code class="file docutils literal notranslate"><span class="pre">clear.img</span></code>. The location and name <code class="file docutils literal notranslate"><span class="pre">clear.img.xz</span></code> is important
|
||
for the tooling to work:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span><span class="w"> </span>~/clearlinux
|
||
curl<span class="w"> </span>-o<span class="w"> </span>clear.img.xz<span class="w"> </span>https://download.clearlinux.org/image/<span class="k">$(</span>curl<span class="w"> </span>https://download.clearlinux.org/image/latest-images<span class="w"> </span><span class="p">|</span><span class="w"> </span>grep<span class="w"> </span><span class="s1">'[0-9]'</span>-kvm<span class="k">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Extract the downloaded Clear Linux OS KVM image:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>unxz<span class="w"> </span>-v<span class="w"> </span>clear.img.xz
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Copy the QEMU start script and virtual firmware needed for KVM into the
|
||
<code class="file docutils literal notranslate"><span class="pre">~/clearlinux</span></code> directory:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>cp<span class="w"> </span>~/clearlinux/projects/common/start_qemu.sh<span class="w"> </span>.
|
||
cp<span class="w"> </span>/usr/share/qemu/OVMF.fd<span class="w"> </span>.
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Run <strong class="command">make install</strong> from the package’s autospec directory. The
|
||
<strong class="command">make install</strong> command mounts the downloaded Clear Linux OS KVM image and
|
||
installs the autospec-created RPM into it:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span><span class="w"> </span>~/clearlinux/packages/<package-name>
|
||
make<span class="w"> </span>install
|
||
</pre></div>
|
||
</div>
|
||
<p>The code that makes this possible can be viewed by searching for the
|
||
<em>install:</em> target in the <a class="reference external" href="https://github.com/clearlinux/common/blob/master/Makefile.common">Makefile.common</a> file on GitHub.</p>
|
||
</li>
|
||
<li><p>Return to the <code class="file docutils literal notranslate"><span class="pre">~/clearlinux</span></code> directory and start the Clear Linux OS VM:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span><span class="w"> </span>~/clearlinux/
|
||
sudo<span class="w"> </span>./start_qemu.sh<span class="w"> </span>clear.img
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>A new Clear Linux OS VM will launch in the console. Log into the VM as <em>root</em> and set
|
||
a new password for the VM.</p></li>
|
||
<li><p>Check that the software is installed in the Clear Linux OS VM as expected and perform
|
||
any relevant tests.</p></li>
|
||
<li><p>After testing has been completed, the Clear Linux OS VM can be powered off and
|
||
deleted:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>poweroff
|
||
rm<span class="w"> </span>clear.img
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ol>
|
||
</section>
|
||
<section id="test-directly-on-a-development-machine">
|
||
<h3>Test directly on a development machine<a class="headerlink" href="#test-directly-on-a-development-machine" title="Link to this heading">¶</a></h3>
|
||
<p>The Clear Linux OS development tooling also includes a method to extract
|
||
autospec-created RPMs locally onto a Clear Linux OS development system for testing.
|
||
Extracting an RPM directly onto a system offers quicker testing; however
|
||
conflicts may occur and responsibility to remove the software after testing is
|
||
up to the developer.</p>
|
||
<p>To test an autospec created package directly on the Clear Linux OS development system:</p>
|
||
<ol class="arabic">
|
||
<li><p>Run <strong class="command">make install-local</strong> from the package’s autospec directory.
|
||
The <strong class="command">make install-local</strong> command extracts the RPM directly onto
|
||
the filesystem of the running Clear Linux OS system:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span><span class="w"> </span>~/clearlinux/packages/<package-name>
|
||
make<span class="w"> </span>install-local
|
||
</pre></div>
|
||
</div>
|
||
<p>The code that makes this possible can be viewed by searching for the
|
||
<em>install-local:</em> target in the <a class="reference external" href="https://github.com/clearlinux/common/blob/master/Makefile.common">Makefile.common</a> file on GitHub.</p>
|
||
</li>
|
||
<li><p>Check that the software is installed as expected and perform any relevant
|
||
tests.</p></li>
|
||
<li><p>After testing has been completed, the software and any related files must
|
||
be identified and deleted. The <strong class="command">swupd repair --picky</strong>
|
||
command can help restore the state of the <code class="file docutils literal notranslate"><span class="pre">/usr</span></code> directory (see
|
||
<a class="reference internal" href="swupd.html#swupd-guide"><span class="std std-ref">swupd</span></a>) however any other files must be cleaned up
|
||
manually.</p></li>
|
||
</ol>
|
||
</section>
|
||
</section>
|
||
<section id="references">
|
||
<h2><a class="toc-backref" href="#id8" role="doc-backlink">References</a><a class="headerlink" href="#references" title="Link to this heading">¶</a></h2>
|
||
<p>Reference the <a class="reference external" href="https://github.com/clearlinux/autospec">autospec README</a> for details regarding <cite>autospec</cite> commands and options.</p>
|
||
<section id="setup-environment-to-build-source">
|
||
<h3>Setup environment to build source<a class="headerlink" href="#setup-environment-to-build-source" title="Link to this heading">¶</a></h3>
|
||
<p id="install-tooling-after-header">Setup of the workspace and tooling used for building source in Clear Linux OS is mostly
|
||
automated for you with a setup script. It uses tools from the
|
||
<strong class="command">os-clr-on-clr</strong> bundle.</p>
|
||
<p>The setup script creates a workspace in the <code class="file docutils literal notranslate"><span class="pre">clearlinux</span></code> folder, with the
|
||
subfolders <code class="file docutils literal notranslate"><span class="pre">Makefile</span></code>, <code class="file docutils literal notranslate"><span class="pre">packages</span></code>, and <code class="file docutils literal notranslate"><span class="pre">projects</span></code>. The
|
||
<code class="file docutils literal notranslate"><span class="pre">projects</span></code> folder contains the main tools used for making packages in
|
||
Clear Linux OS <code class="file docutils literal notranslate"><span class="pre">autospec</span></code> and <code class="file docutils literal notranslate"><span class="pre">common</span></code>.</p>
|
||
<p>Follow these steps to setup the workspace and tooling for building source:</p>
|
||
<ol class="arabic">
|
||
<li><p>Install the <strong class="command">os-clr-on-clr</strong> bundle:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>swupd<span class="w"> </span>bundle-add<span class="w"> </span>os-clr-on-clr
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Download the <code class="file docutils literal notranslate"><span class="pre">user-setup.sh</span></code> script:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>curl<span class="w"> </span>-O<span class="w"> </span>https://raw.githubusercontent.com/clearlinux/common/master/user-setup.sh
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Make <code class="file docutils literal notranslate"><span class="pre">user-setup.sh</span></code> executable:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>chmod<span class="w"> </span>+x<span class="w"> </span>user-setup.sh
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Run the script as an unprivileged user:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>./user-setup.sh
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>After the script completes, log out and log in again to complete the setup
|
||
process.</p></li>
|
||
<li><p>Set your Git user email and username for the repos on your system:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>config<span class="w"> </span>--global<span class="w"> </span>user.email<span class="w"> </span><span class="s2">"you@example.com"</span>
|
||
git<span class="w"> </span>config<span class="w"> </span>--global<span class="w"> </span>user.name<span class="w"> </span><span class="s2">"Your Name"</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This global setting is used by Clear Linux OS tools that make use of Git.</p>
|
||
</li>
|
||
</ol>
|
||
</section>
|
||
</section>
|
||
<section id="related-topics">
|
||
<span id="install-tooling-end"></span><h2><a class="toc-backref" href="#id9" role="doc-backlink">Related topics</a><a class="headerlink" href="#related-topics" title="Link to this heading">¶</a></h2>
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="mixer.html#mixer"><span class="std std-ref">Mixer tool</span></a></p></li>
|
||
<li><p><a class="reference internal" href="../network/proxy.html#proxy"><span class="std std-ref">Proxy Configuration</span></a></p></li>
|
||
</ul>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
<div class="clearer"></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="Main">
|
||
<div class="sphinxsidebarwrapper">
|
||
<p class="logo"><a href="../../index.html">
|
||
<img class="logo" src="../../_static/clearlinux.png" alt="Logo of Clear Linux* Project Docs"/>
|
||
</a></p>
|
||
<div>
|
||
<h3><a href="../../index.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">autospec</a><ul>
|
||
<li><a class="reference internal" href="#description">Description</a></li>
|
||
<li><a class="reference internal" href="#how-it-works">How it works</a><ul>
|
||
<li><a class="reference internal" href="#prerequisites">Prerequisites</a></li>
|
||
<li><a class="reference internal" href="#create-an-rpm">Create an RPM</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#examples">Examples</a><ul>
|
||
<li><a class="reference internal" href="#example-1-build-rpm-with-an-existing-spec-file">Example 1: Build RPM with an existing spec file</a></li>
|
||
<li><a class="reference internal" href="#example-2-build-a-new-rpm">Example 2: Build a new RPM</a></li>
|
||
<li><a class="reference internal" href="#example-3-generate-a-new-spec-file-with-a-pre-defined-package">Example 3: Generate a new spec file with a pre-defined package</a></li>
|
||
<li><a class="reference internal" href="#example-4-provide-control-files-to-autospec">Example 4: Provide control files to autospec</a></li>
|
||
<li><a class="reference internal" href="#example-5-update-an-existing-package">Example 5: Update an existing package</a><ul>
|
||
<li><a class="reference internal" href="#adding-and-submitting-patches">Adding and submitting patches</a></li>
|
||
<li><a class="reference internal" href="#refresh-a-package-and-inspect">Refresh a package and inspect</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#test-packaged-software">Test packaged software</a><ul>
|
||
<li><a class="reference internal" href="#test-in-a-cl-virtual-machine">Test in a Clear Linux OS virtual machine</a></li>
|
||
<li><a class="reference internal" href="#test-directly-on-a-development-machine">Test directly on a development machine</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#references">References</a><ul>
|
||
<li><a class="reference internal" href="#setup-environment-to-build-source">Setup environment to build source</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#related-topics">Related topics</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="autoproxy.html"
|
||
title="previous chapter">Autoproxy</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="bundles.html"
|
||
title="next chapter">Bundles</a></p>
|
||
</div>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../../_sources/guides/clear/autospec.rst.txt"
|
||
rel="nofollow">Show Source</a></li>
|
||
</ul>
|
||
</div>
|
||
<search id="searchbox" style="display: none" role="search">
|
||
<h3 id="searchlabel">Quick search</h3>
|
||
<div class="searchformwrapper">
|
||
<form class="search" action="../../search.html" method="get">
|
||
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
</search>
|
||
<script>document.getElementById('searchbox').style.display = "block"</script>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="bundles.html" title="Bundles"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="autoproxy.html" title="Autoproxy"
|
||
>previous</a> |</li>
|
||
<li class="nav-item nav-item-0"><a href="../../index.html">Documentation for Clear Linux* project</a> »</li>
|
||
<li class="nav-item nav-item-1"><a href="../index.html" >Guides</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href="">autospec</a></li>
|
||
</ul>
|
||
</div>
|
||
<div class="footer" role="contentinfo">
|
||
© Copyright 2022 Intel Corporation. All Rights Reserved..
|
||
Last updated on Nov 04, 2024.
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.1.3.
|
||
</div>
|
||
</body>
|
||
</html> |