| 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 |
| 7 |
to templates. DO NOT USE THIS HTML FILE AS YOUR TEMPLATE! |
| 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 |
<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.1</td> |
| 37 |
</tr> |
| 38 |
<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/09 21:42:57</a></td> |
| 39 |
</tr> |
| 40 |
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Diego Pettenò, Fabian Groffen</td> |
| 41 |
</tr> |
| 42 |
<tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td> |
| 43 |
</tr> |
| 44 |
<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td> |
| 45 |
</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 |
<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">09-Feb-2006</td> |
| 51 |
</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 |
<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 |
</ul> |
| 66 |
</li> |
| 67 |
<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 |
</ul> |
| 70 |
</div> |
| 71 |
<div class="section" id="credits"> |
| 72 |
<h1><a class="toc-backref" href="#id5" name="credits">Credits</a></h1> |
| 73 |
<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 |
<h1><a class="toc-backref" href="#id6" name="abstract">Abstract</a></h1> |
| 79 |
<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 |
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 |
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 |
<h1><a class="toc-backref" href="#id7" name="motivation">Motivation</a></h1> |
| 96 |
<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 |
highly dependant on the build environment, such as platform or C-library |
| 103 |
implementation.</p> |
| 104 |
</div> |
| 105 |
<div class="section" id="rationale"> |
| 106 |
<h1><a class="toc-backref" href="#id8" name="rationale">Rationale</a></h1> |
| 107 |
<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 |
<h1><a class="toc-backref" href="#id9" name="backwards-compatibility">Backwards Compatibility</a></h1> |
| 123 |
<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 |
<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 |
official specification of the syntax of the keyword.</p> |
| 140 |
<p>Keywords will consist out of two parts separated by a hyphen ('-'). The |
| 141 |
left hand part of the keyword 2-tuple is the architecture, such as |
| 142 |
ppc64, sparc and x86. The right hand part indicates the operating |
| 143 |
system or distribution, such as linux, macos, darwin, obsd, etc. If the |
| 144 |
right hand part is omitted, it implies the operating system/distribution |
| 145 |
type is Gentoo GNU/Linux. In such case the hyphen is also omitted. |
| 146 |
Examples of such keywords are ppc-darwin and x86. This is fully |
| 147 |
compatible with the current use of keywords in the tree.</p> |
| 148 |
<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 |
| 149 |
the profiles when other than their defaults for a GNU/Linux system. |
| 150 |
They can as such easily be overridden and defined by the user. To |
| 151 |
prevent this from happening, the variables should be auto filled by |
| 152 |
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> |
| 153 |
variable can be as easy as the others set by the user, it still is |
| 154 |
assumed to be 'safe'. This assumption is grounded in the fact that the |
| 155 |
variable itself is being used in various other places with the same |
| 156 |
intention, and that an invalid <tt class="literal"><span class="pre">CHOST</span></tt> will cause major malfunctioning |
| 157 |
of the system. A user that changes the <tt class="literal"><span class="pre">CHOST</span></tt> into something that is |
| 158 |
not valid for the system, is already warned that this might render the |
| 159 |
system unusable. Concluding, the 'safeness' of the <tt class="literal"><span class="pre">CHOST</span></tt> variable |
| 160 |
is based on externally assumed 'safeness', which's discussion falls |
| 161 |
outside this GLEP.</p> |
| 162 |
<p>Current USE-expansion of the variables is being maintained, as this |
| 163 |
results in full backward compatibility. Since the variables themself |
| 164 |
don't change in what they represent, but only how they are being |
| 165 |
assigned, there should be no problem in maintaining them. Using |
| 166 |
USE-expansion, conditional code can be written down in ebuilds, which is |
| 167 |
not different from any existing methods at all:</p> |
| 168 |
<pre class="literal-block"> |
| 169 |
... |
| 170 |
RDEPEND="elibc_FreeBSD? ( sys-libs/com_err )" |
| 171 |
... |
| 172 |
src_compile() { |
| 173 |
... |
| 174 |
use elibc_FreeBSD && myconf="${myconf} -Dlibc=/usr/lib/libc.a" |
| 175 |
... |
| 176 |
} |
| 177 |
</pre> |
| 178 |
<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> |
| 179 |
are available in the ebuild evironment and they can be used instead of |
| 180 |
invoking <tt class="literal"><span class="pre">xxx_Xxxx</span></tt> or in switch statements where they are actually |
| 181 |
necessary.</p> |
| 182 |
<p>A map file can be used to have the various <tt class="literal"><span class="pre">CHOST</span></tt> values being |
| 183 |
translated to the correct values for the four variables. This change is |
| 184 |
invisible for ebuilds and eclasses, but allows to rely on these |
| 185 |
variables as they are based on a 'safe' value -- the <tt class="literal"><span class="pre">CHOST</span></tt> variable. |
| 186 |
Ebuilds should not be sensitive to the keyword value, but use the |
| 187 |
aforementioned four variables instead. They allow specific tests for |
| 188 |
properties. If this is undesirable, the full <tt class="literal"><span class="pre">CHOST</span></tt> variable can be |
| 189 |
used to match a complete operating system.</p> |
| 190 |
<div class="section" id="variable-assignment"> |
| 191 |
<h2><a class="toc-backref" href="#id11" name="variable-assignment">Variable Assignment</a></h2> |
| 192 |
<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 |
| 193 |
file. The file can be overlaid, such that the following entries in the |
| 194 |
map file (on the left of the arrow) will result in the assigned |
| 195 |
variables on the right hand side of the arrow:</p> |
| 196 |
<pre class="literal-block"> |
| 197 |
*-*-linux-* -> KERNEL="linux" |
| 198 |
*-*-*-gnu -> ELIBC="glibc" |
| 199 |
*-*-kfreebsd-gnu -> KERNEL="FreeBSD" ELIBC="glibc" |
| 200 |
*-*-freebsd* -> KERNEL="FreeBSD" ELIBC="FreeBSD" |
| 201 |
*-*-darwin* -> KERNEL="Darwin" ELIBC="Darwin" |
| 202 |
*-*-netbsd* -> KERNEL="NetBSD" ELIBC="NetBSD" |
| 203 |
*-*-solaris* -> KERNEL="Solaris" ELIBC="Solaris" |
| 204 |
</pre> |
| 205 |
<p>A way to achieve this is proposed by Mike Frysinger, which |
| 206 |
suggests to have a env-map file, for instance filled with:</p> |
| 207 |
<pre class="literal-block"> |
| 208 |
% cat env-map |
| 209 |
*-linux-* KERNEL=linux |
| 210 |
*-gnu ELIBC=glibc |
| 211 |
x86_64-* ARCH=amd64 |
| 212 |
</pre> |
| 213 |
<p>then the following bash script can be used to set the four variables to |
| 214 |
their correct values:</p> |
| 215 |
<pre class="literal-block"> |
| 216 |
% cat readmap |
| 217 |
#!/bin/bash |
| 218 |
|
| 219 |
CBUILD=${CBUILD:-${CHOST=${CHOST:-$1}}} |
| 220 |
[[ -z ${CHOST} ]] && echo need chost |
| 221 |
|
| 222 |
unset KERNEL ELIBC ARCH |
| 223 |
|
| 224 |
while read LINE ; do |
| 225 |
set -- ${LINE} |
| 226 |
targ=$1 |
| 227 |
shift |
| 228 |
[[ ${CBUILD} == ${targ} ]] && eval $@ |
| 229 |
done < env-map |
| 230 |
|
| 231 |
echo ARCH=${ARCH} KERNEL=${KERNEL} ELIBC=${ELIBC} |
| 232 |
</pre> |
| 233 |
<p>Given the example env-map file, this script would result in:</p> |
| 234 |
<pre class="literal-block"> |
| 235 |
% ./readmap x86_64-pc-linux-gnu |
| 236 |
ARCH=amd64 KERNEL=linux ELIBC=glibc |
| 237 |
</pre> |
| 238 |
<p>The entries in the <tt class="literal"><span class="pre">env-map</span></tt> file will be evaluated in a forward |
| 239 |
linear full scan. A side-effect of this exhaustive search is that the |
| 240 |
variables can be re-assigned if multiple entries match the given |
| 241 |
<tt class="literal"><span class="pre">CHOST</span></tt>. Because of this, the order of the entries does matter. |
| 242 |
Because the <tt class="literal"><span class="pre">env-map</span></tt> file size is assumed not to exceed the block |
| 243 |
size of the file system, the performance penalty of a full scan versus |
| 244 |
'first-hit-stop technique' is assumed to be minimal.</p> |
| 245 |
<p>It should be noted, however, that the above bash script is a proof of |
| 246 |
concept implementation. Since Portage is largerly written in Python, it |
| 247 |
will be more efficient to write an equivalent of this code in Python |
| 248 |
also. Coding wise, this is considered to be a non-issue, but the format |
| 249 |
of the <tt class="literal"><span class="pre">env-map</span></tt> file, and especially its wildcard characters, might |
| 250 |
not be the best match with Python. For this purpose, the format |
| 251 |
specification of the <tt class="literal"><span class="pre">env-map</span></tt> file is deferred to the Python |
| 252 |
implementation, and only the requirements are given here.</p> |
| 253 |
<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> |
| 254 |
pair, where <tt class="literal"><span class="pre">key</span></tt> is a (regular) expression that matches a |
| 255 |
chost-string, and <tt class="literal"><span class="pre">value</span></tt> contains at least one, distinct variable |
| 256 |
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 |
| 257 |
interpreter of the <tt class="literal"><span class="pre">env-map</span></tt> file must scan the file linearly and |
| 258 |
continue trying to match the <tt class="literal"><span class="pre">key</span></tt>s and assign variables if |
| 259 |
appropriate until the end of file.</p> |
| 260 |
<p>Since Portage will use the <tt class="literal"><span class="pre">env-map</span></tt> file, the location of the file is |
| 261 |
beyond the scope of this GLEP and up to the Portage implementors.</p> |
| 262 |
</div> |
| 263 |
</div> |
| 264 |
<div class="section" id="references"> |
| 265 |
<h1><a class="toc-backref" href="#id12" name="references">References</a></h1> |
| 266 |
<table class="footnote" frame="void" id="id3" rules="none"> |
| 267 |
<colgroup><col class="label" /><col /></colgroup> |
| 268 |
<tbody valign="top"> |
| 269 |
<tr><td class="label"><a class="fn-backref" href="#id1" name="id3">[1]</a></td><td>GLEP 22, New "keyword" system to incorporate various |
| 270 |
userlands/kernels/archs, Goodyear, |
| 271 |
(<a class="reference" href="http://glep.gentoo.org/glep-0022.html">http://glep.gentoo.org/glep-0022.html</a>)</td></tr> |
| 272 |
</tbody> |
| 273 |
</table> |
| 274 |
<table class="footnote" frame="void" id="id4" rules="none"> |
| 275 |
<colgroup><col class="label" /><col /></colgroup> |
| 276 |
<tbody valign="top"> |
| 277 |
<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 |
| 278 |
4-tuples, even though tuple in itself suggest a field consisting of |
| 279 |
two values. For clarity: a 1-tuple describes a single value field, |
| 280 |
while a 4-tuple describes a field consisting out of four values.</td></tr> |
| 281 |
</tbody> |
| 282 |
</table> |
| 283 |
</div> |
| 284 |
<div class="section" id="copyright"> |
| 285 |
<h1><a class="toc-backref" href="#id13" name="copyright">Copyright</a></h1> |
| 286 |
<p>This document has been placed in the public domain.</p> |
| 287 |
</div> |
| 288 |
</div> |
| 289 |
|
| 290 |
<hr class="footer" /> |
| 291 |
<div class="footer"> |
| 292 |
<a class="reference" href="glep-0047.txt">View document source</a>. |
| 293 |
Generated on: 2006-02-11 21:38 UTC. |
| 294 |
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. |
| 295 |
</div> |
| 296 |
</body> |
| 297 |
</html> |
Parent Directory
| 
Revision Log
