en/glep/glep-0047.html

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!--
This HTML is auto-generated.  DO NOT EDIT THIS FILE!  If you are writing a new
PEP, see http://www.python.org/peps/pep-0001.html for instructions and links
to templates.  DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
-->
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <meta name="generator" content="Docutils 0.3.5: http://docutils.sourceforge.net/" />
  <title>GLEP 47 -- Creating 'safe' environment variables</title>
  <link rel="stylesheet" href="tools/glep.css" type="text/css" />
</head>
<body bgcolor="white">
<table class="navigation" cellpadding="0" cellspacing="0"
       width="100%" border="0">
<tr><td class="navicon" width="150" height="35">
<a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
<img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
 border="0" width="150" height="35" /></a></td>
<td class="textlinks" align="left">
[<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
[<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>]
[<b><a href="./glep-0047.txt">GLEP Source</a></b>]
</td></tr></table>
<div class="document">
<table class="rfc2822 field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">GLEP:</th><td class="field-body">47</td>
</tr>
<tr class="field"><th class="field-name">Title:</th><td class="field-body">Creating 'safe' environment variables</td>
</tr>
<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.1</td>
</tr>
<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>
</tr>
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Diego Pettenò, Fabian Groffen</td>
</tr>
<tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
</tr>
<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
</tr>
<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>
</tr>
<tr class="field"><th class="field-name">Created:</th><td class="field-body">14-Oct-2005</td>
</tr>
<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">09-Feb-2006</td>
</tr>
</tbody>
</table>
<hr />
<div class="contents topic" id="contents">
<p class="topic-title first"><a name="contents">Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#credits" id="id5" name="id5">Credits</a></li>
<li><a class="reference" href="#abstract" id="id6" name="id6">Abstract</a></li>
<li><a class="reference" href="#motivation" id="id7" name="id7">Motivation</a></li>
<li><a class="reference" href="#rationale" id="id8" name="id8">Rationale</a></li>
<li><a class="reference" href="#backwards-compatibility" id="id9" name="id9">Backwards Compatibility</a></li>
<li><a class="reference" href="#specification" id="id10" name="id10">Specification</a><ul>
<li><a class="reference" href="#variable-assignment" id="id11" name="id11">Variable Assignment</a></li>
</ul>
</li>
<li><a class="reference" href="#references" id="id12" name="id12">References</a></li>
<li><a class="reference" href="#copyright" id="id13" name="id13">Copyright</a></li>
</ul>
</div>
<div class="section" id="credits">
<h1><a class="toc-backref" href="#id5" name="credits">Credits</a></h1>
<p>The text of this GLEP is a result of a discussion and input of the
following persons, in no particular order: Mike Frysinger, Diego
Pettenò, Fabian Groffen and Finn Thain.</p>
</div>
<div class="section" id="abstract">
<h1><a class="toc-backref" href="#id6" name="abstract">Abstract</a></h1>
<p>In order for ebuilds and eclasses to be able to make host specific
decisions, it is necessary to have a number of environmental variables
which allow for such decisions.  This GLEP introduces some measures that
need to be made to make these decisions 'safe', by making sure the
variables the decisions are based on are 'safe'.  A small overlap with
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
keywords are being kept instead of 4-tuple keywords.  Additionally, the
<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
<tt class="literal"><span class="pre">CHOST</span></tt> and the 2-tuple keyword, instead of solely from they 4-tuple
keyword as proposed in GLEP 22.</p>
<p>The destiny of the <tt class="literal"><span class="pre">USERLAND</span></tt> variable is out of the scope of this
GLEP.  Depending on its presence in the tree, it may be decided to set
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
<tt class="literal"><span class="pre">ARCH</span></tt>, or alternatively, e.g. via the profiles.</p>
</div>
<div class="section" id="motivation">
<h1><a class="toc-backref" href="#id7" name="motivation">Motivation</a></h1>
<p>The Gentoo/Alt project is in an emerging state to get ready to serve a
plethora of 'alternative' configurations such as FreeBSD, NetBSD,
DragonflyBSD, GNU/kFreeBSD, Mac OS X, (Open)Darwin, (Open)Solaris and so
on.  As such, the project is in need for a better grip on the actual
host being built on.  This information on the host environment is
necessary to make proper (automated) decisions on settings that are
highly dependant on the build environment, such as platform or C-library
implementation.</p>
</div>
<div class="section" id="rationale">
<h1><a class="toc-backref" href="#id8" name="rationale">Rationale</a></h1>
<p>Gentoo's unique Portage system allows easy installation of applications
from source packages.  Compiling sources is prone to many environmental
settings and availability of certain tools.  Only recently the Gentoo
for FreeBSD project has started, as second Gentoo project that operates
on a foreign host operating system using foreign (non-GNU) C-libraries
and userland utilities.  Such projects suffer from the current implicit
assumption made within Gentoo Portage's ebuilds that there is a single
type of operating system, C-libraries and system utilities.  In order to
enable ebuilds -- and also eclasses -- to be aware of these
environmental differences, information regarding it should be supplied.
Since decisions based on this information can be vital, it is of high
importance that this information can be trusted and the values can be
considered 'safe' and correct.</p>
</div>
<div class="section" id="backwards-compatibility">
<h1><a class="toc-backref" href="#id9" name="backwards-compatibility">Backwards Compatibility</a></h1>
<p>The proposed keywording scheme in this GLEP is fully compatible with the
current situation of the portage tree, this in contrast to GLEP 22.  The
variables provided by GLEP 22 can't be extracted from the new keyword,
but since GLEP 22-style keywords aren't in the tree at the moment, that
is not a problem.  The same information can be extracted from the CHOST
variable, if necessary.  No modifications to ebuilds will have to be
made.</p>
</div>
<div class="section" id="specification">
<h1><a class="toc-backref" href="#id10" name="specification">Specification</a></h1>
<p>Unlike GLEP 22 the currently used keyword scheme is not changed.
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
for archs that require them.  Archs for which a 1-tuple keyword
suffices, can keep that keyword.  Since this doesn't change anything to
the current situation in the tree, it is considered to be a big
advantage over the 4-tuple keyword from GLEP 22.  This GLEP is an
official specification of the syntax of the keyword.</p>
<p>Keywords will consist out of two parts separated by a hyphen ('-').  The
left hand part of the keyword 2-tuple is the architecture, such as
ppc64, sparc and x86.  The right hand part indicates the operating
system or distribution, such as linux, macos, darwin, obsd, etc.  If the
right hand part is omitted, it implies the operating system/distribution
type is Gentoo GNU/Linux.  In such case the hyphen is also omitted.
Examples of such keywords are ppc-darwin and x86.  This is fully
compatible with the current use of keywords in the tree.</p>
<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
the profiles when other than their defaults for a GNU/Linux system.
They can as such easily be overridden and defined by the user.  To
prevent this from happening, the variables should be auto filled by
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>
variable can be as easy as the others set by the user, it still is
assumed to be 'safe'.  This assumption is grounded in the fact that the
variable itself is being used in various other places with the same
intention, and that an invalid <tt class="literal"><span class="pre">CHOST</span></tt> will cause major malfunctioning
of the system.  A user that changes the <tt class="literal"><span class="pre">CHOST</span></tt> into something that is
not valid for the system, is already warned that this might render the
system unusable.  Concluding, the 'safeness' of the <tt class="literal"><span class="pre">CHOST</span></tt> variable
is based on externally assumed 'safeness', which's discussion falls
outside this GLEP.</p>
<p>Current USE-expansion of the variables is being maintained, as this
results in full backward compatibility.  Since the variables themself
don't change in what they represent, but only how they are being
assigned, there should be no problem in maintaining them.  Using
USE-expansion, conditional code can be written down in ebuilds, which is
not different from any existing methods at all:</p>
<pre class="literal-block">
...
RDEPEND=&quot;elibc_FreeBSD? ( sys-libs/com_err )&quot;
...
src_compile() {
    ...
    use elibc_FreeBSD &amp;&amp; myconf=&quot;${myconf} -Dlibc=/usr/lib/libc.a&quot;
    ...
}
</pre>
<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>
are available in the ebuild evironment and they can be used instead of
invoking <tt class="literal"><span class="pre">xxx_Xxxx</span></tt> or in switch statements where they are actually
necessary.</p>
<p>A map file can be used to have the various <tt class="literal"><span class="pre">CHOST</span></tt> values being
translated to the correct values for the four variables.  This change is
invisible for ebuilds and eclasses, but allows to rely on these
variables as they are based on a 'safe' value -- the <tt class="literal"><span class="pre">CHOST</span></tt> variable.
Ebuilds should not be sensitive to the keyword value, but use the
aforementioned four variables instead.  They allow specific tests for
properties.  If this is undesirable, the full <tt class="literal"><span class="pre">CHOST</span></tt> variable can be
used to match a complete operating system.</p>
<div class="section" id="variable-assignment">
<h2><a class="toc-backref" href="#id11" name="variable-assignment">Variable Assignment</a></h2>
<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
file.  The file can be overlaid, such that the following entries in the
map file (on the left of the arrow) will result in the assigned
variables on the right hand side of the arrow:</p>
<pre class="literal-block">
*-*-linux-*      -&gt; KERNEL=&quot;linux&quot;  
*-*-*-gnu        -&gt; ELIBC=&quot;glibc&quot;
*-*-kfreebsd-gnu -&gt; KERNEL=&quot;FreeBSD&quot; ELIBC=&quot;glibc&quot;
*-*-freebsd*     -&gt; KERNEL=&quot;FreeBSD&quot; ELIBC=&quot;FreeBSD&quot;
*-*-darwin*      -&gt; KERNEL=&quot;Darwin&quot; ELIBC=&quot;Darwin&quot;
*-*-netbsd*      -&gt; KERNEL=&quot;NetBSD&quot; ELIBC=&quot;NetBSD&quot;
*-*-solaris*     -&gt; KERNEL=&quot;Solaris&quot; ELIBC=&quot;Solaris&quot;
</pre>
<p>A way to achieve this is proposed by Mike Frysinger, which
suggests to have a env-map file, for instance filled with:</p>
<pre class="literal-block">
% cat env-map
*-linux-* KERNEL=linux
*-gnu ELIBC=glibc
x86_64-* ARCH=amd64
</pre>
<p>then the following bash script can be used to set the four variables to
their correct values:</p>
<pre class="literal-block">
% cat readmap 
#!/bin/bash 

CBUILD=${CBUILD:-${CHOST=${CHOST:-$1}}} 
[[ -z ${CHOST} ]] &amp;&amp; echo need chost 

unset KERNEL ELIBC ARCH 

while read LINE ; do 
    set -- ${LINE} 
    targ=$1 
    shift 
    [[ ${CBUILD} == ${targ} ]] &amp;&amp; eval $&#64; 
done &lt; env-map 

echo ARCH=${ARCH} KERNEL=${KERNEL} ELIBC=${ELIBC}
</pre>
<p>Given the example env-map file, this script would result in:</p>
<pre class="literal-block">
% ./readmap x86_64-pc-linux-gnu 
ARCH=amd64 KERNEL=linux ELIBC=glibc
</pre>
<p>The entries in the <tt class="literal"><span class="pre">env-map</span></tt> file will be evaluated in a forward
linear full scan.  A side-effect of this exhaustive search is that the
variables can be re-assigned if multiple entries match the given
<tt class="literal"><span class="pre">CHOST</span></tt>.  Because of this, the order of the entries does matter.
Because the <tt class="literal"><span class="pre">env-map</span></tt> file size is assumed not to exceed the block
size of the file system, the performance penalty of a full scan versus
'first-hit-stop technique' is assumed to be minimal.</p>
<p>It should be noted, however, that the above bash script is a proof of
concept implementation.  Since Portage is largerly written in Python, it
will be more efficient to write an equivalent of this code in Python
also.  Coding wise, this is considered to be a non-issue, but the format
of the <tt class="literal"><span class="pre">env-map</span></tt> file, and especially its wildcard characters, might
not be the best match with Python.  For this purpose, the format
specification of the <tt class="literal"><span class="pre">env-map</span></tt> file is deferred to the Python
implementation, and only the requirements are given here.</p>
<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>
pair, where <tt class="literal"><span class="pre">key</span></tt> is a (regular) expression that matches a
chost-string, and <tt class="literal"><span class="pre">value</span></tt> contains at least one, distinct variable
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
interpreter of the <tt class="literal"><span class="pre">env-map</span></tt> file must scan the file linearly and
continue trying to match the <tt class="literal"><span class="pre">key</span></tt>s and assign variables if
appropriate until the end of file.</p>
<p>Since Portage will use the <tt class="literal"><span class="pre">env-map</span></tt> file, the location of the file is
beyond the scope of this GLEP and up to the Portage implementors.</p>
</div>
</div>
<div class="section" id="references">
<h1><a class="toc-backref" href="#id12" name="references">References</a></h1>
<table class="footnote" frame="void" id="id3" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<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
userlands/kernels/archs, Goodyear,
(<a class="reference" href="http://glep.gentoo.org/glep-0022.html">http://glep.gentoo.org/glep-0022.html</a>)</td></tr>
</tbody>
</table>
<table class="footnote" frame="void" id="id4" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<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
4-tuples, even though tuple in itself suggest a field consisting of
two values.  For clarity: a 1-tuple describes a single value field,
while a 4-tuple describes a field consisting out of four values.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="copyright">
<h1><a class="toc-backref" href="#id13" name="copyright">Copyright</a></h1>
<p>This document has been placed in the public domain.</p>
</div>
</div>

<hr class="footer" />
<div class="footer">
<a class="reference" href="glep-0047.txt">View document source</a>.
Generated on: 2006-02-11 21:38 UTC.
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.
</div>
</body>
</html>

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>
298