Contents of /xml/htdocs/proj/en/glep/glep-0062.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.1 - (hide annotations) (download) (as text)
Wed Jul 11 20:58:28 2012 UTC (6 years, 3 months ago) by mgorny
Branch: MAIN
File MIME type: text/html
Add rendered version of IUSE_RUNTIME GLEP.

1 mgorny 1.1 <?xml version="1.0" encoding="utf-8" ?>
2     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3     <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
5     <head>
6     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
7     <meta name="generator" content="Docutils 0.9: http://docutils.sourceforge.net/" />
8     <title>GLEP 62 -- Optional runtime dependencies via runtime-switchable USE flags</title>
9     <link rel="stylesheet" href="tools/glep.css" type="text/css" /></head>
10     <body bgcolor="white">
11     <table class="navigation" cellpadding="0" cellspacing="0"
12     width="100%" border="0">
13     <tr><td class="navicon" width="150" height="35">
14     <a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
15     <img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
16     border="0" width="150" height="35" /></a></td>
17     <td class="textlinks" align="left">
18     [<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
19     [<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>]
20     [<b><a href="http://www.gentoo.org/proj/en/glep/glep-0062.txt">GLEP Source</a></b>]
21     </td></tr></table>
22     <table class="rfc2822 docutils field-list" frame="void" rules="none">
23     <col class="field-name" />
24     <col class="field-body" />
25     <tbody valign="top">
26     <tr class="field"><th class="field-name">GLEP:</th><td class="field-body">62</td>
27     </tr>
28     <tr class="field"><th class="field-name">Title:</th><td class="field-body">Optional runtime dependencies via runtime-switchable USE flags</td>
29     </tr>
30     <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.2</td>
31     </tr>
32     <tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference external" href="http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/glep/glep-0062.txt?cvsroot=gentoo">2012/07/11 20:24:37</a></td>
33     </tr>
34     <tr class="field"><th class="field-name">Author:</th><td class="field-body">Michał Górny &lt;mgorny&#32;&#97;t&#32;gentoo.org&gt;</td>
35     </tr>
36     <tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
37     </tr>
38     <tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
39     </tr>
40     <tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference external" href="glep-0002.html">text/x-rst</a></td>
41     </tr>
42     <tr class="field"><th class="field-name">Created:</th><td class="field-body">17 Jun 2012</td>
43     </tr>
44     <tr class="field"><th class="field-name">Post-History:</th><td class="field-body">11 Jul 2012</td>
45     </tr>
46     </tbody>
47     </table>
48     <hr />
49     <div class="contents topic" id="contents">
50     <p class="topic-title first">Contents</p>
51     <ul class="simple">
52     <li><a class="reference internal" href="#abstract" id="id6">Abstract</a></li>
53     <li><a class="reference internal" href="#motivation" id="id7">Motivation</a></li>
54     <li><a class="reference internal" href="#specification" id="id8">Specification</a></li>
55     <li><a class="reference internal" href="#rationale" id="id9">Rationale</a></li>
56     <li><a class="reference internal" href="#reference-implementation" id="id10">Reference implementation</a></li>
57     <li><a class="reference internal" href="#backwards-compatibility" id="id11">Backwards compatibility</a></li>
58     <li><a class="reference internal" href="#copyright" id="id12">Copyright</a></li>
59     </ul>
60     </div>
61     <div class="section" id="abstract">
62     <h1><a class="toc-backref" href="#id6">Abstract</a></h1>
63     <p>This GLEP addresses the issue of referencing optional runtime
64     dependencies in Gentoo packages and ebuilds. It does introduce
65     a concept of runtime-switchable USE flags to achieve that goal.</p>
66     </div>
67     <div class="section" id="motivation">
68     <h1><a class="toc-backref" href="#id7">Motivation</a></h1>
69     <p>Optional runtime dependencies are often found in packages installing
70     various scripts (shell, python, perl). These are not strictly required
71     for the particular package to work but installing them enables
72     additional functionality.</p>
73     <p>Unlike in compiled programs, enabling or disabling those features
74     (dependencies) does not affect the files installed by the package.
75     They can be installed and uninstalled independently of the package,
76     resulting in changes of functionality without a need to rebuild
77     the package.</p>
78     <p>Currently such dependencies are usually expressed only through
79     <tt class="docutils literal">pkg_postinst()</tt> messages. This forces user to manually install
80     the necessary dependencies, and uninstall them when they are no longer
81     necessary.</p>
82     <p>Another solution is to use regular USE flags. Those flags do not strictly
83     follow the principles of USE flags because they do not affect files
84     installed by the package and are not entirely effective to the package
85     (a disabled feature will still be available if necessary dependency is
86     installed). Additionally, it requires unnecessary rebuilds
87     of the package in order to change the dependencies.</p>
88     </div>
89     <div class="section" id="specification">
90     <h1><a class="toc-backref" href="#id8">Specification</a></h1>
91     <p>The ebuilds aiming to provide features enabled through optional runtime
92     dependencies should:</p>
93     <ol class="arabic simple">
94     <li>create regular USE flags for all those features, following
95     appropriate specifications for Gentoo ebuilds, and including
96     the flags in the <tt class="docutils literal">IUSE</tt> variable;</li>
97     <li>introduce additional <tt class="docutils literal">IUSE_RUNTIME</tt> variable listing names of USE
98     flags related to optional runtime dependencies (without prefixes
99     related to IUSE defaults).</li>
100     </ol>
101     <p>Additionally, the ebuilds must obey the following rules:</p>
102     <ol class="arabic simple">
103     <li>all flags listed in <tt class="docutils literal">IUSE_RUNTIME</tt> have to be listed in <tt class="docutils literal">IUSE</tt>
104     as well,</li>
105     <li>flags listed in <tt class="docutils literal">IUSE_RUNTIME</tt> can be referenced in <tt class="docutils literal">RDEPEND</tt>,
106     <tt class="docutils literal">PDEPEND</tt> and <tt class="docutils literal">REQUIRED_USE</tt> variables,</li>
107     <li>flags listed in <tt class="docutils literal">IUSE_RUNTIME</tt> must not be referenced in phase
108     functions, <tt class="docutils literal">DEPEND</tt>, <tt class="docutils literal">LICENSE</tt> or <tt class="docutils literal">SRC_URI</tt>,</li>
109     <li>flags listed in <tt class="docutils literal">IUSE_RUNTIME</tt> can be referenced through USE
110     dependencies by other packages' <tt class="docutils literal">DEPEND</tt>, <tt class="docutils literal">RDEPEND</tt>
111     and <tt class="docutils literal">PDEPEND</tt> variables but it is unallowed to request disabling
112     those flags (only <tt class="docutils literal">[flag]</tt> and <tt class="docutils literal"><span class="pre">[flag?]</span></tt> forms are allowed),</li>
113     <li>flags listed in <tt class="docutils literal">IUSE_RUNTIME</tt> can be referenced through
114     <tt class="docutils literal">has_version</tt> and <tt class="docutils literal">best_version</tt> yet the caller must not rely
115     upon those flags being disabled.</li>
116     </ol>
117     <p>The package manager should treat flags listed in <tt class="docutils literal">IUSE_RUNTIME</tt>
118     as regular USE flags, except for the following:</p>
119     <ol class="arabic simple">
120     <li>enabling or disabling any of the flags must not involve rebuilding
121     the package,</li>
122     <li>it should be possible for a package manager to change those flags
123     on a installed package without using the original ebuild <a class="footnote-reference" href="#id3" id="id1">[1]</a>,</li>
124     <li>when queried on a installed package, the package manager must
125     consider a particular flag enabled only if its dependencies
126     are satisfied already <a class="footnote-reference" href="#id4" id="id2">[2]</a>,</li>
127     <li>the flags may be listed in the visual output in a distinct way
128     to inform the user that they affect runtime dependencies only.</li>
129     </ol>
130     <table class="docutils footnote" frame="void" id="id3" rules="none">
131     <colgroup><col class="label" /><col /></colgroup>
132     <tbody valign="top">
133     <tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>The package manager has to ensure that all relevant information
134     is stored in the installed package metadata.</td></tr>
135     </tbody>
136     </table>
137     <table class="docutils footnote" frame="void" id="id4" rules="none">
138     <colgroup><col class="label" /><col /></colgroup>
139     <tbody valign="top">
140     <tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>The result of this check can be cached when updating the metadata
141     of installed package, and it is not strictly required that
142     a package manager must ensure that the dependency graph is still
143     consistent afterwards.</td></tr>
144     </tbody>
145     </table>
146     </div>
147     <div class="section" id="rationale">
148     <h1><a class="toc-backref" href="#id9">Rationale</a></h1>
149     <p>The proposed solution tries to solve the issue of handling runtime
150     dependencies while reusing the existing infrastructure. Most
151     importantly, users will be able to reuse the existing tools
152     and configuration files to enable and disable optional runtime
153     and build-time dependencies alike.</p>
154     <p>The remaining reused features include:</p>
155     <ul class="simple">
156     <li>dependency syntax (USE-conditionals),</li>
157     <li>ability to use <tt class="docutils literal">REQUIRED_USE</tt>, USE dependencies,</li>
158     <li>ability to describe flags in <cite>metadata.xml</cite>,</li>
159     <li>global flag names (and descriptions).</li>
160     </ul>
161     <p>Alternative proposed solution involved creating additional <tt class="docutils literal">SDEPEND</tt>
162     variable. That proposition had the following disadvantages:</p>
163     <ul class="simple">
164     <li>being package-oriented rather than feature-oriented,</li>
165     <li>lack of ability to express multiple packages required by a single
166     feature,</li>
167     <li>lack of ability to express cross-feature dependencies,</li>
168     <li>lack of ability to describe features provided by enabled packages,</li>
169     <li>necessity of implementing a new user interface parts to control
170     the dependencies,</li>
171     <li>lack of backwards compatibility.</li>
172     </ul>
173     <p>Those disadvantages could be fixed by either extending dependency
174     syntax alike Exherbo (grouping, annotations) or using USE flags.
175     The latter is practically equivalent to this solution yet introduces
176     another variable unnecessarily.</p>
177     </div>
178     <div class="section" id="reference-implementation">
179     <h1><a class="toc-backref" href="#id10">Reference implementation</a></h1>
180     <p>In order to support runtime-switchable USE flag changes on installed
181     packages, a package manager should store the following information
182     in the installed package metadata:</p>
183     <ol class="arabic simple">
184     <li>a list of runtime-switchable flags (<tt class="docutils literal">IUSE_RUNTIME</tt>),</li>
185     <li>a list of runtime dependencies conditional to runtime-switchable
186     flags, not subjected to USE expansion (relevant part of <tt class="docutils literal">RDEPEND</tt>),</li>
187     <li>a list of <tt class="docutils literal">REQUIRED_USE</tt> constraints relevant to runtime-switchable
188     USE flags.</li>
189     </ol>
190     <p>The package manager should be also able to update the list of effective
191     USE flags in installed package metadata (<tt class="docutils literal">USE</tt>) without rebuilding
192     the package.</p>
193     <p>The following procedure should apply when a dependency atom is
194     considered (either as a package dependency or user-requested atom):</p>
195     <ol class="arabic simple">
196     <li>if the dependency is not satisfied with an installed package,
197     perform the dependency resolution on ebuilds as usual (in order to
198     install a new package);</li>
199     <li>if runtime-switchable USE updates are disabled, continue to
200     the next dependency (with this one satisfied);</li>
201     <li><tt class="docutils literal">current_use</tt> = installed package metadata . <tt class="docutils literal">USE</tt>;</li>
202     <li><tt class="docutils literal">effective_use</tt> = requested <tt class="docutils literal">USE</tt> for the package;</li>
203     <li><tt class="docutils literal">use_changes</tt> = <tt class="docutils literal">current_use</tt> xor <tt class="docutils literal">effective_use</tt>;</li>
204     <li>if <tt class="docutils literal">use_changes</tt> is empty, continue to the next dependency;</li>
205     <li><tt class="docutils literal">iuse_runtime</tt> = installed package metadata . <tt class="docutils literal">IUSE_RUNTIME</tt>;</li>
206     <li><tt class="docutils literal">reg_use_changes</tt> = <tt class="docutils literal">use_changes</tt> and not <tt class="docutils literal">iuse_runtime</tt>;</li>
207     <li>if <tt class="docutils literal">reg_use_changes</tt> is not empty and regular USE updates
208     are enabled, perform the dependency resolution on ebuilds (in order
209     to rebuild the package);</li>
210     <li><tt class="docutils literal">run_use_changes</tt> = <tt class="docutils literal">use_changes</tt> and <tt class="docutils literal">iuse_runtime</tt>;</li>
211     <li>if <tt class="docutils literal">run_use_changes</tt> is empty, continue to the next dependency;</li>
212     <li><tt class="docutils literal">required_use</tt> = installed package metadata . <tt class="docutils literal">REQUIRED_USE</tt>;</li>
213     <li>perform a check for <tt class="docutils literal">required_use</tt> constraints being satisfied
214     by <tt class="docutils literal">effective_use</tt>;</li>
215     <li><tt class="docutils literal">run_rdepend</tt> = installed package metadata . <tt class="docutils literal">RDEPEND</tt> (with
216     unexpanded <tt class="docutils literal">IUSE_RUNTIME</tt> conditionals);</li>
217     <li>perform the dependency resolution for <tt class="docutils literal">run_rdepend</tt> with
218     <tt class="docutils literal">effective_use</tt>,</li>
219     <li>queue the package for runtime-switchable USE update.</li>
220     </ol>
221     <p>Furthermore, after installing all dependencies introduced by the above
222     procedure (<tt class="docutils literal">run_rdepend</tt> resolution), if a package was queued for
223     runtime-switchable USE update, the package manager should write a new
224     value for <tt class="docutils literal">USE</tt> key in installed package metadata.</p>
225     </div>
226     <div class="section" id="backwards-compatibility">
227     <h1><a class="toc-backref" href="#id11">Backwards compatibility</a></h1>
228     <p>Package managers not implementing this GLEP will consider
229     the <tt class="docutils literal">IUSE_RUNTIME</tt> variable as an irrelevant bash variable and treat
230     runtime-switchable USE flags as regular USE flags. The dependency tree
231     will still be consistent yet packages may be rebuilt unnecessarily.</p>
232     </div>
233     <div class="section" id="copyright">
234     <h1><a class="toc-backref" href="#id12">Copyright</a></h1>
235     <p>This document has been placed in the public domain.</p>
236     </div>
238     </div>
239     <div class="footer">
240     <hr class="footer" />
241     <a class="reference external" href="glep-0062.txt">View document source</a>.
242     Generated on: 2012-07-11 20:57 UTC.
243     Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
245     </div>
246     </body>
247     </html>

  ViewVC Help
Powered by ViewVC 1.1.20