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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.4 - (hide annotations) (download) (as text)
Mon Feb 13 21:00:50 2006 UTC (13 years ago) by grobian
Branch: MAIN
Changes since 1.3: +4 -4 lines
File MIME type: text/html

1 grobian 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">
4     <!--
5     This HTML is auto-generated. DO NOT EDIT THIS FILE! If you are writing a new
6     PEP, see http://www.python.org/peps/pep-0001.html for instructions and links
8     -->
9     <head>
10     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
11     <meta name="generator" content="Docutils 0.3.5: http://docutils.sourceforge.net/" />
12     <title>GLEP 47 -- Creating 'safe' environment variables</title>
13     <link rel="stylesheet" href="tools/glep.css" type="text/css" />
14     </head>
15     <body bgcolor="white">
16     <table class="navigation" cellpadding="0" cellspacing="0"
17     width="100%" border="0">
18     <tr><td class="navicon" width="150" height="35">
19     <a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
20     <img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
21     border="0" width="150" height="35" /></a></td>
22     <td class="textlinks" align="left">
23     [<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
24     [<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>]
25     [<b><a href="./glep-0047.txt">GLEP Source</a></b>]
26     </td></tr></table>
27     <div class="document">
28     <table class="rfc2822 field-list" frame="void" rules="none">
29     <col class="field-name" />
30     <col class="field-body" />
31     <tbody valign="top">
32     <tr class="field"><th class="field-name">GLEP:</th><td class="field-body">47</td>
33     </tr>
34     <tr class="field"><th class="field-name">Title:</th><td class="field-body">Creating 'safe' environment variables</td>
35     </tr>
36 grobian 1.4 <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.3</td>
37 grobian 1.1 </tr>
38 grobian 1.4 <tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference" href="http://www.gentoo.org/cgi-bin/viewcvs/xml/htdocs/proj/en/glep/glep-0047.txt?cvsroot=gentoo">2006/02/12 19:57:57</a></td>
39 grobian 1.1 </tr>
40 grobian 1.2 <tr class="field"><th class="field-name">Author:</th><td class="field-body">Diego Pettenò, Fabian Groffen</td>
41 grobian 1.1 </tr>
42 grobian 1.2 <tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
43 grobian 1.1 </tr>
44 grobian 1.2 <tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
45 grobian 1.1 </tr>
46     <tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference" href="glep-0012.html">text/x-rst</a></td>
47     </tr>
48     <tr class="field"><th class="field-name">Created:</th><td class="field-body">14-Oct-2005</td>
49     </tr>
50 grobian 1.2 <tr class="field"><th class="field-name">Post-History:</th><td class="field-body">09-Feb-2006</td>
51 grobian 1.1 </tr>
52     </tbody>
53     </table>
54     <hr />
55     <div class="contents topic" id="contents">
56     <p class="topic-title first"><a name="contents">Contents</a></p>
57     <ul class="simple">
58 grobian 1.2 <li><a class="reference" href="#credits" id="id5" name="id5">Credits</a></li>
59     <li><a class="reference" href="#abstract" id="id6" name="id6">Abstract</a></li>
60     <li><a class="reference" href="#motivation" id="id7" name="id7">Motivation</a></li>
61     <li><a class="reference" href="#rationale" id="id8" name="id8">Rationale</a></li>
62     <li><a class="reference" href="#backwards-compatibility" id="id9" name="id9">Backwards Compatibility</a></li>
63     <li><a class="reference" href="#specification" id="id10" name="id10">Specification</a><ul>
64     <li><a class="reference" href="#variable-assignment" id="id11" name="id11">Variable Assignment</a></li>
65 grobian 1.1 </ul>
66     </li>
67 grobian 1.2 <li><a class="reference" href="#references" id="id12" name="id12">References</a></li>
68     <li><a class="reference" href="#copyright" id="id13" name="id13">Copyright</a></li>
69 grobian 1.1 </ul>
70     </div>
71     <div class="section" id="credits">
72 grobian 1.2 <h1><a class="toc-backref" href="#id5" name="credits">Credits</a></h1>
73 grobian 1.1 <p>The text of this GLEP is a result of a discussion and input of the
74     following persons, in no particular order: Mike Frysinger, Diego
75     Pettenò, Fabian Groffen and Finn Thain.</p>
76     </div>
77     <div class="section" id="abstract">
78 grobian 1.2 <h1><a class="toc-backref" href="#id6" name="abstract">Abstract</a></h1>
79 grobian 1.1 <p>In order for ebuilds and eclasses to be able to make host specific
80     decisions, it is necessary to have a number of environmental variables
81     which allow for such decisions. This GLEP introduces some measures that
82     need to be made to make these decisions 'safe', by making sure the
83     variables the decisions are based on are 'safe'. A small overlap with
84 grobian 1.2 GLEP 22 <a class="footnote-reference" href="#id3" id="id1" name="id1">[1]</a> is being handled in this GLEP where the use of 2-tuple
85 grobian 1.1 keywords are being kept instead of 4-tuple keywords. Additionally, the
86     <tt class="literal"><span class="pre">ELIBC</span></tt>, <tt class="literal"><span class="pre">KERNEL</span></tt> and <tt class="literal"><span class="pre">ARCH</span></tt> get auto filled starting from
87     <tt class="literal"><span class="pre">CHOST</span></tt> and the 2-tuple keyword, instead of solely from they 4-tuple
88     keyword as proposed in GLEP 22.</p>
89     <p>The destiny of the <tt class="literal"><span class="pre">USERLAND</span></tt> variable is out of the scope of this
90     GLEP. Depending on its presence in the tree, it may be decided to set
91     this variable the same way we propose to set <tt class="literal"><span class="pre">ELIBC</span></tt>, <tt class="literal"><span class="pre">KERNEL</span></tt> and
92     <tt class="literal"><span class="pre">ARCH</span></tt>, or alternatively, e.g. via the profiles.</p>
93     </div>
94     <div class="section" id="motivation">
95 grobian 1.2 <h1><a class="toc-backref" href="#id7" name="motivation">Motivation</a></h1>
96 grobian 1.1 <p>The Gentoo/Alt project is in an emerging state to get ready to serve a
97     plethora of 'alternative' configurations such as FreeBSD, NetBSD,
98     DragonflyBSD, GNU/kFreeBSD, Mac OS X, (Open)Darwin, (Open)Solaris and so
99     on. As such, the project is in need for a better grip on the actual
100     host being built on. This information on the host environment is
101     necessary to make proper (automated) decisions on settings that are
102 grobian 1.2 highly dependant on the build environment, such as platform or C-library
103     implementation.</p>
104 grobian 1.1 </div>
105     <div class="section" id="rationale">
106 grobian 1.2 <h1><a class="toc-backref" href="#id8" name="rationale">Rationale</a></h1>
107 grobian 1.1 <p>Gentoo's unique Portage system allows easy installation of applications
108     from source packages. Compiling sources is prone to many environmental
109     settings and availability of certain tools. Only recently the Gentoo
110     for FreeBSD project has started, as second Gentoo project that operates
111     on a foreign host operating system using foreign (non-GNU) C-libraries
112     and userland utilities. Such projects suffer from the current implicit
113     assumption made within Gentoo Portage's ebuilds that there is a single
114     type of operating system, C-libraries and system utilities. In order to
115     enable ebuilds -- and also eclasses -- to be aware of these
116     environmental differences, information regarding it should be supplied.
117     Since decisions based on this information can be vital, it is of high
118     importance that this information can be trusted and the values can be
119     considered 'safe' and correct.</p>
120     </div>
121     <div class="section" id="backwards-compatibility">
122 grobian 1.2 <h1><a class="toc-backref" href="#id9" name="backwards-compatibility">Backwards Compatibility</a></h1>
123 grobian 1.1 <p>The proposed keywording scheme in this GLEP is fully compatible with the
124     current situation of the portage tree, this in contrast to GLEP 22. The
125     variables provided by GLEP 22 can't be extracted from the new keyword,
126     but since GLEP 22-style keywords aren't in the tree at the moment, that
127     is not a problem. The same information can be extracted from the CHOST
128     variable, if necessary. No modifications to ebuilds will have to be
129     made.</p>
130     </div>
131     <div class="section" id="specification">
132 grobian 1.2 <h1><a class="toc-backref" href="#id10" name="specification">Specification</a></h1>
133     <p>Unlike GLEP 22 the currently used keyword scheme is not changed.
134     Instead of proposing a 4-tuple <a class="footnote-reference" href="#id4" id="id2" name="id2">[2]</a> keyword, a 2-tuple keyword is chosen
135     for archs that require them. Archs for which a 1-tuple keyword
136     suffices, can keep that keyword. Since this doesn't change anything to
137     the current situation in the tree, it is considered to be a big
138     advantage over the 4-tuple keyword from GLEP 22. This GLEP is an
139 grobian 1.1 official specification of the syntax of the keyword.</p>
140     <p>Keywords will consist out of two parts separated by a hyphen ('-'). The
141 grobian 1.3 part up to the first hyphen from the left of the keyword 2-tuple is the
142     architecture, such as ppc64, sparc and x86. Allowed characters for the
143     architecture name are in <tt class="literal"><span class="pre">a-z0-9</span></tt>. The remaining part on the right of
144     the first hyphen from the left indicates the operating system or
145     distribution, such as linux, macos, darwin, obsd, et-cetera. If the
146 grobian 1.1 right hand part is omitted, it implies the operating system/distribution
147 grobian 1.3 type is Gentoo GNU/Linux. In such case the hyphen is also omitted, and
148     the keyword consists of solely the architecture. The operating system
149     or distribution name can consist out of characters in <tt class="literal"><span class="pre">a-zA-Z0-9_+:-</span></tt>.
150     Please note that the hyphen is an allowed character, and therefore the
151     separation of the two fields in the keyword is only determinable by
152     scanning for the first hyphen character from the start of the keyword
153     string. Examples of keywords following this specification are
154     ppc-darwin and x86. This is fully compatible with the current use of
155     keywords in the tree.</p>
156 grobian 1.1 <p>The variables <tt class="literal"><span class="pre">ELIBC</span></tt>, <tt class="literal"><span class="pre">KERNEL</span></tt> and <tt class="literal"><span class="pre">ARCH</span></tt> are currently set in
157     the profiles when other than their defaults for a GNU/Linux system.
158     They can as such easily be overridden and defined by the user. To
159     prevent this from happening, the variables should be auto filled by
160 grobian 1.2 Portage itself, based on the <tt class="literal"><span class="pre">CHOST</span></tt> variable. While the <tt class="literal"><span class="pre">CHOST</span></tt>
161     variable can be as easy as the others set by the user, it still is
162     assumed to be 'safe'. This assumption is grounded in the fact that the
163     variable itself is being used in various other places with the same
164     intention, and that an invalid <tt class="literal"><span class="pre">CHOST</span></tt> will cause major malfunctioning
165     of the system. A user that changes the <tt class="literal"><span class="pre">CHOST</span></tt> into something that is
166     not valid for the system, is already warned that this might render the
167     system unusable. Concluding, the 'safeness' of the <tt class="literal"><span class="pre">CHOST</span></tt> variable
168     is based on externally assumed 'safeness', which's discussion falls
169     outside this GLEP.</p>
170     <p>Current USE-expansion of the variables is being maintained, as this
171     results in full backward compatibility. Since the variables themself
172     don't change in what they represent, but only how they are being
173     assigned, there should be no problem in maintaining them. Using
174     USE-expansion, conditional code can be written down in ebuilds, which is
175     not different from any existing methods at all:</p>
176     <pre class="literal-block">
177     ...
178     RDEPEND=&quot;elibc_FreeBSD? ( sys-libs/com_err )&quot;
179     ...
180     src_compile() {
181     ...
182     use elibc_FreeBSD &amp;&amp; myconf=&quot;${myconf} -Dlibc=/usr/lib/libc.a&quot;
183     ...
184     }
185     </pre>
186     <p>Alternatively, the variables <tt class="literal"><span class="pre">ELIBC</span></tt>, <tt class="literal"><span class="pre">KERNEL</span></tt> and <tt class="literal"><span class="pre">ARCH</span></tt>
187     are available in the ebuild evironment and they can be used instead of
188     invoking <tt class="literal"><span class="pre">xxx_Xxxx</span></tt> or in switch statements where they are actually
189     necessary.</p>
190 grobian 1.1 <p>A map file can be used to have the various <tt class="literal"><span class="pre">CHOST</span></tt> values being
191     translated to the correct values for the four variables. This change is
192     invisible for ebuilds and eclasses, but allows to rely on these
193     variables as they are based on a 'safe' value -- the <tt class="literal"><span class="pre">CHOST</span></tt> variable.
194     Ebuilds should not be sensitive to the keyword value, but use the
195     aforementioned four variables instead. They allow specific tests for
196     properties. If this is undesirable, the full <tt class="literal"><span class="pre">CHOST</span></tt> variable can be
197     used to match a complete operating system.</p>
198 grobian 1.2 <div class="section" id="variable-assignment">
199     <h2><a class="toc-backref" href="#id11" name="variable-assignment">Variable Assignment</a></h2>
200 grobian 1.1 <p>The <tt class="literal"><span class="pre">ELIBC</span></tt>, <tt class="literal"><span class="pre">KERNEL</span></tt>, <tt class="literal"><span class="pre">ARCH</span></tt> variables are filled from a profile
201     file. The file can be overlaid, such that the following entries in the
202     map file (on the left of the arrow) will result in the assigned
203     variables on the right hand side of the arrow:</p>
204     <pre class="literal-block">
205     *-*-linux-* -&gt; KERNEL=&quot;linux&quot;
206     *-*-*-gnu -&gt; ELIBC=&quot;glibc&quot;
207     *-*-kfreebsd-gnu -&gt; KERNEL=&quot;FreeBSD&quot; ELIBC=&quot;glibc&quot;
208     *-*-freebsd* -&gt; KERNEL=&quot;FreeBSD&quot; ELIBC=&quot;FreeBSD&quot;
209     *-*-darwin* -&gt; KERNEL=&quot;Darwin&quot; ELIBC=&quot;Darwin&quot;
210     *-*-netbsd* -&gt; KERNEL=&quot;NetBSD&quot; ELIBC=&quot;NetBSD&quot;
211     *-*-solaris* -&gt; KERNEL=&quot;Solaris&quot; ELIBC=&quot;Solaris&quot;
212     </pre>
213 grobian 1.2 <p>A way to achieve this is proposed by Mike Frysinger, which
214 grobian 1.4 suggests to have an env-map file, for instance filled with:</p>
215 grobian 1.1 <pre class="literal-block">
216     % cat env-map
217     *-linux-* KERNEL=linux
218     *-gnu ELIBC=glibc
219     x86_64-* ARCH=amd64
220     </pre>
221     <p>then the following bash script can be used to set the four variables to
222     their correct values:</p>
223     <pre class="literal-block">
224     % cat readmap
225     #!/bin/bash
227     CBUILD=${CBUILD:-${CHOST=${CHOST:-$1}}}
228     [[ -z ${CHOST} ]] &amp;&amp; echo need chost
230     unset KERNEL ELIBC ARCH
232     while read LINE ; do
233     set -- ${LINE}
234     targ=$1
235     shift
236     [[ ${CBUILD} == ${targ} ]] &amp;&amp; eval $&#64;
237     done &lt; env-map
240     </pre>
241     <p>Given the example env-map file, this script would result in:</p>
242     <pre class="literal-block">
243     % ./readmap x86_64-pc-linux-gnu
244     ARCH=amd64 KERNEL=linux ELIBC=glibc
245     </pre>
246 grobian 1.2 <p>The entries in the <tt class="literal"><span class="pre">env-map</span></tt> file will be evaluated in a forward
247     linear full scan. A side-effect of this exhaustive search is that the
248     variables can be re-assigned if multiple entries match the given
249     <tt class="literal"><span class="pre">CHOST</span></tt>. Because of this, the order of the entries does matter.
250     Because the <tt class="literal"><span class="pre">env-map</span></tt> file size is assumed not to exceed the block
251     size of the file system, the performance penalty of a full scan versus
252     'first-hit-stop technique' is assumed to be minimal.</p>
253     <p>It should be noted, however, that the above bash script is a proof of
254     concept implementation. Since Portage is largerly written in Python, it
255     will be more efficient to write an equivalent of this code in Python
256     also. Coding wise, this is considered to be a non-issue, but the format
257     of the <tt class="literal"><span class="pre">env-map</span></tt> file, and especially its wildcard characters, might
258     not be the best match with Python. For this purpose, the format
259     specification of the <tt class="literal"><span class="pre">env-map</span></tt> file is deferred to the Python
260     implementation, and only the requirements are given here.</p>
261     <p>The <tt class="literal"><span class="pre">env-map</span></tt> file should be capable of encoding a <tt class="literal"><span class="pre">key</span></tt>, <tt class="literal"><span class="pre">value</span></tt>
262     pair, where <tt class="literal"><span class="pre">key</span></tt> is a (regular) expression that matches a
263     chost-string, and <tt class="literal"><span class="pre">value</span></tt> contains at least one, distinct variable
264     assignment for the variables <tt class="literal"><span class="pre">ARCH</span></tt>, <tt class="literal"><span class="pre">KERNEL</span></tt> and <tt class="literal"><span class="pre">ELIBC</span></tt>. The
265     interpreter of the <tt class="literal"><span class="pre">env-map</span></tt> file must scan the file linearly and
266     continue trying to match the <tt class="literal"><span class="pre">key</span></tt>s and assign variables if
267     appropriate until the end of file.</p>
268     <p>Since Portage will use the <tt class="literal"><span class="pre">env-map</span></tt> file, the location of the file is
269     beyond the scope of this GLEP and up to the Portage implementors.</p>
270 grobian 1.1 </div>
271     </div>
272     <div class="section" id="references">
273 grobian 1.2 <h1><a class="toc-backref" href="#id12" name="references">References</a></h1>
274     <table class="footnote" frame="void" id="id3" rules="none">
275 grobian 1.1 <colgroup><col class="label" /><col /></colgroup>
276     <tbody valign="top">
277 grobian 1.2 <tr><td class="label"><a class="fn-backref" href="#id1" name="id3">[1]</a></td><td>GLEP 22, New &quot;keyword&quot; system to incorporate various
278 grobian 1.1 userlands/kernels/archs, Goodyear,
279     (<a class="reference" href="http://glep.gentoo.org/glep-0022.html">http://glep.gentoo.org/glep-0022.html</a>)</td></tr>
280     </tbody>
281     </table>
282 grobian 1.2 <table class="footnote" frame="void" id="id4" rules="none">
283 grobian 1.1 <colgroup><col class="label" /><col /></colgroup>
284     <tbody valign="top">
285 grobian 1.2 <tr><td class="label"><a class="fn-backref" href="#id2" name="id4">[2]</a></td><td>For the purpose of readability, we will refer to 1, 2 and
286 grobian 1.1 4-tuples, even though tuple in itself suggest a field consisting of
287     two values. For clarity: a 1-tuple describes a single value field,
288 grobian 1.2 while a 4-tuple describes a field consisting out of four values.</td></tr>
289 grobian 1.1 </tbody>
290     </table>
291     </div>
292     <div class="section" id="copyright">
293 grobian 1.2 <h1><a class="toc-backref" href="#id13" name="copyright">Copyright</a></h1>
294 grobian 1.1 <p>This document has been placed in the public domain.</p>
295     </div>
296     </div>
298     <hr class="footer" />
299     <div class="footer">
300     <a class="reference" href="glep-0047.txt">View document source</a>.
301 grobian 1.4 Generated on: 2006-02-12 19:59 UTC.
302 grobian 1.1 Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
303     </div>
304     </body>
305     </html>

  ViewVC Help
Powered by ViewVC 1.1.20