diff options
| author |   André Erdmann <dywi@mailerd.de> | 2013-08-07 17:56:18 +0200 |
|---|---|---|
| committer | André Erdmann <dywi@mailerd.de> | 2013-08-07 17:56:18 +0200 |
| commit | 5a515917f750a1ffe7e64dce2bf569a306b149f7 (patch) | |
| tree | a9c9ef1c655ea09bc0f2eb54b46f1f03d330abe3 /doc | |
| parent | doc/rst: license map syntax, using roverlay's API (diff) | |
| download | R_overlay-5a515917f750a1ffe7e64dce2bf569a306b149f7.tar.gz R_overlay-5a515917f750a1ffe7e64dce2bf569a306b149f7.tar.bz2 R_overlay-5a515917f750a1ffe7e64dce2bf569a306b149f7.zip | |
update doc/html/usage.html (generated file)
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/html/usage.html | 194 |
1 files changed, 148 insertions, 46 deletions
diff --git a/doc/html/usage.html b/doc/html/usage.html index 39d7e63..55ad457 100644 --- a/doc/html/usage.html +++ b/doc/html/usage.html @@ -424,53 +424,54 @@ ul.auto-toc { </li> <li><a class="reference internal" href="#id3" id="id65">11 Other config files</a><ul class="auto-toc"> <li><a class="reference internal" href="#use-expand-flag-rename-file" id="id66">11.1 USE_EXPAND flag rename file</a></li> -<li><a class="reference internal" href="#field-definition-config" id="id67">11.2 Field Definition Config</a><ul class="auto-toc"> -<li><a class="reference internal" href="#example-the-default-field-definition-file" id="id68">11.2.1 Example: The default field definition file</a></li> +<li><a class="reference internal" href="#license-map-file" id="id67">11.2 License Map File</a></li> +<li><a class="reference internal" href="#field-definition-config" id="id68">11.3 Field Definition Config</a><ul class="auto-toc"> +<li><a class="reference internal" href="#example-the-default-field-definition-file" id="id69">11.3.1 Example: The default field definition file</a></li> </ul> </li> </ul> </li> -<li><a class="reference internal" href="#id5" id="id69">12 Roverlay Console</a><ul class="auto-toc"> -<li><a class="reference internal" href="#dependency-resolution-console" id="id70">12.1 Dependency Resolution Console</a></li> +<li><a class="reference internal" href="#id5" id="id70">12 Roverlay Console</a><ul class="auto-toc"> +<li><a class="reference internal" href="#dependency-resolution-console" id="id71">12.1 Dependency Resolution Console</a></li> </ul> </li> -<li><a class="reference internal" href="#roverlay-interface" id="id71">13 Roverlay Interface</a><ul class="auto-toc"> -<li><a class="reference internal" href="#depres-interface" id="id72">13.1 DepRes Interface</a></li> -<li><a class="reference internal" href="#remote-interface" id="id73">13.2 Remote Interface</a></li> +<li><a class="reference internal" href="#roverlay-interface" id="id72">13 Roverlay Interface</a><ul class="auto-toc"> +<li><a class="reference internal" href="#depres-interface" id="id73">13.1 DepRes Interface</a></li> +<li><a class="reference internal" href="#remote-interface" id="id74">13.2 Remote Interface</a></li> </ul> </li> -<li><a class="reference internal" href="#implementation-overview" id="id74">14 Implementation Overview</a><ul class="auto-toc"> -<li><a class="reference internal" href="#packageinfo" id="id75">14.1 PackageInfo</a></li> -<li><a class="reference internal" href="#repository-management" id="id76">14.2 Repository Management</a><ul class="auto-toc"> -<li><a class="reference internal" href="#repository" id="id77">14.2.1 Repository</a><ul class="auto-toc"> -<li><a class="reference internal" href="#adding-new-repository-types" id="id78">14.2.1.1 Adding new repository types</a></li> +<li><a class="reference internal" href="#implementation-overview" id="id75">14 Implementation Overview</a><ul class="auto-toc"> +<li><a class="reference internal" href="#packageinfo" id="id76">14.1 PackageInfo</a></li> +<li><a class="reference internal" href="#repository-management" id="id77">14.2 Repository Management</a><ul class="auto-toc"> +<li><a class="reference internal" href="#repository" id="id78">14.2.1 Repository</a><ul class="auto-toc"> +<li><a class="reference internal" href="#adding-new-repository-types" id="id79">14.2.1.1 Adding new repository types</a></li> </ul> </li> </ul> </li> -<li><a class="reference internal" href="#overlay" id="id79">14.3 Overlay</a><ul class="auto-toc"> -<li><a class="reference internal" href="#metadata-creation" id="id80">14.3.1 Metadata Creation</a></li> -<li><a class="reference internal" href="#manifest-creation" id="id81">14.3.2 Manifest Creation</a></li> +<li><a class="reference internal" href="#overlay" id="id80">14.3 Overlay</a><ul class="auto-toc"> +<li><a class="reference internal" href="#metadata-creation" id="id81">14.3.1 Metadata Creation</a></li> +<li><a class="reference internal" href="#manifest-creation" id="id82">14.3.2 Manifest Creation</a></li> </ul> </li> -<li><a class="reference internal" href="#ebuild-creation" id="id82">14.4 Ebuild Creation</a><ul class="auto-toc"> -<li><a class="reference internal" href="#ebuild-variables" id="id83">14.4.1 Ebuild Variables</a></li> +<li><a class="reference internal" href="#ebuild-creation" id="id83">14.4 Ebuild Creation</a><ul class="auto-toc"> +<li><a class="reference internal" href="#ebuild-variables" id="id84">14.4.1 Ebuild Variables</a></li> </ul> </li> -<li><a class="reference internal" href="#overlay-creation" id="id84">14.5 Overlay Creation</a><ul class="auto-toc"> -<li><a class="reference internal" href="#selfdep-validation" id="id85">14.5.1 Selfdep Validation</a></li> +<li><a class="reference internal" href="#overlay-creation" id="id85">14.5 Overlay Creation</a><ul class="auto-toc"> +<li><a class="reference internal" href="#selfdep-validation" id="id86">14.5.1 Selfdep Validation</a></li> </ul> </li> -<li><a class="reference internal" href="#dependency-resolution" id="id86">14.6 Dependency Resolution</a><ul class="auto-toc"> -<li><a class="reference internal" href="#dependency-types" id="id87">14.6.1 Dependency types</a><ul class="auto-toc"> -<li><a class="reference internal" href="#description-file-dependency-fields" id="id88">14.6.1.1 DESCRIPTION file dependency fields</a></li> +<li><a class="reference internal" href="#dependency-resolution" id="id87">14.6 Dependency Resolution</a><ul class="auto-toc"> +<li><a class="reference internal" href="#dependency-types" id="id88">14.6.1 Dependency types</a><ul class="auto-toc"> +<li><a class="reference internal" href="#description-file-dependency-fields" id="id89">14.6.1.1 DESCRIPTION file dependency fields</a></li> </ul> </li> -<li><a class="reference internal" href="#dependency-environments" id="id89">14.6.2 Dependency Environments</a></li> -<li><a class="reference internal" href="#ebuildjob-channel" id="id90">14.6.3 EbuildJob Channel</a></li> -<li><a class="reference internal" href="#dependency-rule-pools" id="id91">14.6.4 Dependency Rule Pools</a></li> -<li><a class="reference internal" href="#dependency-resolver-modules" id="id92">14.6.5 Dependency Resolver Modules</a></li> -<li><a class="reference internal" href="#dependency-resolver" id="id93">14.6.6 Dependency Resolver</a></li> +<li><a class="reference internal" href="#dependency-environments" id="id90">14.6.2 Dependency Environments</a></li> +<li><a class="reference internal" href="#ebuildjob-channel" id="id91">14.6.3 EbuildJob Channel</a></li> +<li><a class="reference internal" href="#dependency-rule-pools" id="id92">14.6.4 Dependency Rule Pools</a></li> +<li><a class="reference internal" href="#dependency-resolver-modules" id="id93">14.6.5 Dependency Resolver Modules</a></li> +<li><a class="reference internal" href="#dependency-resolver" id="id94">14.6.6 Dependency Resolver</a></li> </ul> </li> </ul> @@ -503,18 +504,23 @@ does and what to expect from the generated overlay.</p> </li> <li><p class="first"><em>roverlay</em> maintainers who <strong>control and test overlay creation</strong>, e.g. configure which R packages will be part of the generated overlay</p> -<p>Depending on what you want to configure, chapters 5-10 are relevant, +<p>Depending on what you want to configure, chapters 5-11 are relevant, namely <a class="reference internal" href="#repositories-getting-packages">Repositories / Getting Packages</a>, <cite>Additions Directory</cite>, <a class="reference internal" href="#dependency-rules">Dependency Rules</a>, <a class="reference internal" href="#package-rules">Package Rules</a>, <a class="reference internal" href="#configuration-reference">Configuration Reference</a> and <a class="reference internal" href="#field-definition-config">Field Definition Config</a>.</p> <p>There is another chapter that is only interesting for testing, the -<a class="reference internal" href="#dependency-resolution-console">Dependency Resolution Console</a> (11), which can be used to interactively -test dependency rules.</p> +<a class="reference internal" href="#dependency-resolution-console">Dependency Resolution Console</a> (12.1), which can be used to +interactively test dependency rules.</p> </li> <li><p class="first"><em>roverlay</em> code maintainers who want to know <strong>how roverlay works</strong> for code improvements etc.</p> -<p>The most important chapter is <a class="reference internal" href="#implementation-overview">Implementation Overview</a> (12) which has -references to other chapters (4-10) where required.</p> +<p>The most important chapter is <a class="reference internal" href="#implementation-overview">Implementation Overview</a> (14) which has +references to other chapters (4-13) where required.</p> +</li> +<li><p class="first">developers who intend to <strong>use roverlay's functionality outside of roverlay</strong></p> +<p>The most important chapter is <a class="reference internal" href="#roverlay-interface">Roverlay Interface</a>, which gives an +overview of <em>roverlay's</em> API. +Reading the other chapters (4-14) is recommended.</p> </li> </ul> </blockquote> @@ -639,17 +645,15 @@ as the <em>R Overlay src directory</em> from now on.</p> <div class="section" id="required-configuration-steps"> <h2><a class="toc-backref" href="#contents">3.1 Required configuration steps</a></h2> <p><em>roverlay</em> needs a configuration file to run. -If roverlay has been installed with <em>emerge</em>, it will look for the config file in -that order:</p> +If roverlay has been installed with <em>emerge</em>, +it will look for the config file in that order:</p> <ol class="arabic simple"> -<li><em><current directory>/R-overlay.conf</em></li> <li><em>~/roverlay/R-overlay.conf</em></li> <li><em>/etc/roverlay/R-overlay.conf</em>, which is part of the installation but has to be modified.</li> </ol> -<p>Otherwise, <em>roverlay</em> will only look for <em>R-overlay.conf</em> in the current -directory. An example config file is available in the -<em>R Overlay src directory</em>.</p> +<p>Otherwise, <em>roverlay</em> uses <em>R-overlay.conf</em> in the current directory. +An example config file is available in the <em>R Overlay src directory</em>.</p> <p>The config file is a text file with '<option> = <value>' syntax. Some options accept multiple values (e.g. <option> = file1, file2), in which case the values have to be enclosed with quotes (-> <tt class="docutils literal"><option> = "file1 file2"</tt>).</p> @@ -846,6 +850,10 @@ to know in detail what <em>roverlay</em> does before running it.</p> <kbd><span class="option">--nosync</span>, <span class="option">--no-sync</span></kbd></td> </tr> <tr><td> </td><td>Disable downloading of R packages.</td></tr> +<tr><td class="option-group"> +<kbd><span class="option">--strict</span></kbd></td> +<td>Enable strict behavior. +For example, this causes <em>roverlay</em> to exit if any repo cannot be synced.</td></tr> <tr><td class="option-group" colspan="2"> <kbd><span class="option">--distmap-verify</span></kbd></td> </tr> @@ -1086,6 +1094,7 @@ eclass file are used, the result should look like:</p> <overlay root>/ <overlay root>/eclass <overlay root>/eclass/R-packages.eclass +<overlay root>/metadata/layout.conf <overlay root>/profiles <overlay root>/profiles/categories <overlay root>/profiles/repo_name @@ -3428,7 +3437,7 @@ on <em>roverlay</em> exit. Primarily useful for creating new rules.</p> sound = audio snd </pre> <p>Each flag is renamed at most once, so the following example renames 'sound' -to media, but 'audio' to 'sound':;</p> +to media, but 'audio' to 'sound':</p> <pre class="code text literal-block"> sound = audio snd media = sound video @@ -3439,8 +3448,56 @@ media = sound video unpredictable results.</p> </div> </div> +<div class="section" id="license-map-file"> +<h2><a class="toc-backref" href="#contents">11.2 License Map File</a></h2> +<p>The license map file is a file with dictionary-like entries that is used +to translate <em>license strings</em> (read from the package's DESCRIPTION) into +licenses accepted by portage, e.g. <tt class="docutils literal"><span class="pre">GPL-3</span></tt> or <tt class="docutils literal">|| ( <span class="pre">GPL-3+</span> BSD )</tt>. +Its syntax is similar to the dependency rule file syntax:</p> +<pre class="code text literal-block"> +# this is a comment line + +# 1,1 mapping +portage_license :: license_str + +# 1,n mapping (n>=0) +portage_license { + license_str_0 + license_str_1 + ... + license_str_n +} + +# 0,1 mapping (ignore license_str) +! :: license_str + +# 0,n mapping (ignore several license_str) +! { + license_str_0 + license_str_1 + ... + license_str_n +} +</pre> +<p>Example (excerpt from <em>roverlay's</em> license map file):</p> +<pre class="code text literal-block"> +# freestyle text +! { + foo + freeforresearchpurpose. + whatlicenseisitunder? +} + +BSD :: freebsd + +|| ( GPL-2+ BSD ) { + gpl>2|bsd + gpl>2|freebsd +} +</pre> +</div> <div class="section" id="field-definition-config"> -<span id="id4"></span><h2><a class="toc-backref" href="#contents">11.2 Field Definition Config</a></h2> +<span id="id4"></span><h2><a class="toc-backref" href="#contents">11.3 Field Definition Config</a></h2> <p>The field definition file uses <a class="reference external" href="http://docs.python.org/library/configparser.html">ConfigParser</a> syntax and defines how an R package's DESCRIPTION file is read. See the next section, <a class="reference internal" href="#default-field-definition-file">default field definition file</a>, for an example.</p> @@ -3528,7 +3585,7 @@ such a field is found.</dd> <p class="last">It is not checked whether a flag is known or not.</p> </div> <div class="section" id="example-the-default-field-definition-file"> -<span id="default-field-definition-file"></span><h3><a class="toc-backref" href="#contents">11.2.1 Example: The default field definition file</a></h3> +<span id="default-field-definition-file"></span><h3><a class="toc-backref" href="#contents">11.3.1 Example: The default field definition file</a></h3> <p>This is the default field definition file (without any ignored fields):</p> <pre class="code ini literal-block"> <span class="keyword">[Description]</span> @@ -3572,7 +3629,8 @@ such a field is found.</dd> <span id="roverlay-console"></span><h1><a class="toc-backref" href="#contents">12 Roverlay Console</a></h1> <p>roverlay provides an interactive console for accessing certain subsystems, e.g. dependency resolution. Its features include tab completion for filesystem -paths and a command history that supports navigation with the arrow keys.</p> +paths and a command history that supports navigation with the arrow keys. +Line continuation with a backslash character <tt class="docutils literal">\</tt> is supported, too.</p> <p>The console also implements a subset of typical tools like <tt class="docutils literal">cat</tt>, which behave similar but not identical to their counterparts.</p> <p>See the following sections for how to run specific consoles.</p> @@ -3683,7 +3741,7 @@ It is an interactive console with the following features:</p> <li>save rules to a file</li> </ul> <p>Rules are managed in a set. These so-called <em>rule pools</em> are organized in -a <em>first-in-first-out</em> data structure that allows to create or remove +a <em>last-in-first-out</em> data structure that allows to create or remove them easily at runtime.</p> <p>Running <tt class="docutils literal">roverlay depres_console</tt> prints a short welcome message and starts the console.</p> @@ -3874,6 +3932,42 @@ initialization</td> </table> <p>For extending the API, roverlay provides the abstract <em>RoverlayInterface</em> and <em>RoverlaySubInterface</em> classes.</p> +<p>The following code snippet gives an idea on how to include roverlay's API in +your code:</p> +<pre class="code python literal-block"> +<span class="comment">#!/usr/bin/python</span> +<span class="comment">#</span> +<span class="comment"># Initializes logging and roverlay's interfaces</span> +<span class="comment">#</span> + +<span class="keyword namespace">import</span> <span class="name namespace">logging</span> + +<span class="keyword namespace">import</span> <span class="name namespace">roverlay.core</span> +<span class="keyword namespace">import</span> <span class="name namespace">roverlay.interface.main</span> + +<span class="keyword">def</span> <span class="name function">main</span><span class="punctuation">():</span> + <span class="comment"># log everything to console</span> + <span class="name">roverlay</span><span class="operator">.</span><span class="name">core</span><span class="operator">.</span><span class="name">force_console_logging</span> <span class="punctuation">(</span> <span class="name">log_level</span><span class="operator">=</span><span class="name">logging</span><span class="operator">.</span><span class="name">INFO</span> <span class="punctuation">)</span> + + <span class="comment"># load roverlay's config</span> + <span class="name">config</span> <span class="operator">=</span> <span class="name">roverlay</span><span class="operator">.</span><span class="name">core</span><span class="operator">.</span><span class="name">load_locate_config_file</span> <span class="punctuation">(</span> + <span class="name">ROVERLAY_INSTALLED</span><span class="operator">=</span><span class="name builtin pseudo">False</span><span class="punctuation">,</span> <span class="name">setup_logger</span><span class="operator">=</span><span class="name builtin pseudo">False</span> + <span class="punctuation">)</span> + + <span class="comment"># create the main interface</span> + <span class="name">main_interface</span> <span class="operator">=</span> <span class="name">roverlay</span><span class="operator">.</span><span class="name">interface</span><span class="operator">.</span><span class="name">main</span><span class="operator">.</span><span class="name">MainInterface</span> <span class="punctuation">(</span> <span class="name">config</span><span class="operator">=</span><span class="name">config</span> <span class="punctuation">)</span> + + <span class="comment"># create subinterfaces, as needed</span> + <span class="name">depres_interface</span> <span class="operator">=</span> <span class="name">main_interface</span><span class="operator">.</span><span class="name">spawn_interface</span> <span class="punctuation">(</span> <span class="literal string">"depres"</span> <span class="punctuation">)</span> + <span class="name">remote_interface</span> <span class="operator">=</span> <span class="name">main_interface</span><span class="operator">.</span><span class="name">spawn_interface</span> <span class="punctuation">(</span> <span class="literal string">"remote"</span> <span class="punctuation">)</span> + + <span class="comment"># use them</span> + <span class="keyword">pass</span> +<span class="comment"># --- end of main (...) ---</span> + +<span class="keyword">if</span> <span class="name">__name__</span> <span class="operator">==</span> <span class="literal string">'__main__'</span><span class="punctuation">:</span> + <span class="name">main</span><span class="punctuation">()</span> +</pre> <div class="section" id="depres-interface"> <h2><a class="toc-backref" href="#contents">13.1 DepRes Interface</a></h2> <p>The <em>DepResInterface</em> offers the following functionality:</p> @@ -4097,8 +4191,8 @@ is not.</p> <li><p class="first">Write the overlay to its filesystem location</p> <blockquote> <ul class="simple"> -<li>initialize the overlay (write the <em>profiles/</em> directory, -import eclass files)</li> +<li>initialize the overlay (write the <em>profiles/</em> directory and +<em>metadata</em>/layout.conf, import eclass files)</li> <li>Write ebuilds; all <em>PackageInfo</em> instances with an ebuild will be written</li> <li>Generate and write metadata</li> <li>Write Manifest files</li> @@ -4165,6 +4259,14 @@ as <em>ebuild successfully created</em></li> class. An <em>EbuildVar</em> defines its position in the ebuild and how its text output should look like. Ebuild text is created by adding ebuild variables to an <em>Ebuilder</em> that automatically sorts them and creates the ebuild.</p> +<p>Most ebuild variables, e.g. all variables that contain text from a package's +DESCRIPTION data, have basic protection against code injection:</p> +<ul class="simple"> +<li>only ASCII characters are allowed</li> +<li>the following chars are always removed: <tt class="docutils literal">"</tt>, <tt class="docutils literal">'</tt>, <tt class="docutils literal">`</tt> and <tt class="docutils literal">;</tt></li> +<li>backslash chars <tt class="docutils literal">\</tt> at the end of the variable's value are removed</li> +<li>any char sequence starting with <tt class="docutils literal">$(</tt> is completely dropped</li> +</ul> </div> </div> <div class="section" id="overlay-creation"> @@ -4564,7 +4666,7 @@ becomes "loop until resolver closes".</p> </div> <div class="footer"> <hr class="footer" /> -Generated on: 2013-08-06. +Generated on: 2013-08-07. </div> </body> |