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.8</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/01/26 20:56:55</a></td>
</tr>
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Diego Pettenò, Fabian rroffen &lt;{flameeyes,grobian}&#64;gentoo.org&gt;</td>
</tr>
<tr class="field"><th class="field-name">Status:</th><td class="field-body">Active</td>
</tr>
<tr class="field"><th class="field-name">Type:</th><td class="field-body">Proposal</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"></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="id9" name="id9">Credits</a></li>
<li><a class="reference" href="#abstract" id="id10" name="id10">Abstract</a></li>
<li><a class="reference" href="#motivation" id="id11" name="id11">Motivation</a></li>
<li><a class="reference" href="#rationale" id="id12" name="id12">Rationale</a></li>
<li><a class="reference" href="#backwards-compatibility" id="id13" name="id13">Backwards Compatibility</a></li>
<li><a class="reference" href="#specification" id="id14" name="id14">Specification</a><ul>
<li><a class="reference" href="#variables" id="id15" name="id15">Variables</a></li>
</ul>
</li>
<li><a class="reference" href="#references" id="id16" name="id16">References</a></li>
<li><a class="reference" href="#copyright" id="id17" name="id17">Copyright</a></li>
</ul>
</div>
<div class="section" id="credits">
<h1><a class="toc-backref" href="#id9" 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="#id10" 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="#id5" 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="#id11" 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 as in
<a class="footnote-reference" href="#id6" id="id2" name="id2">[2]</a>.</p>
</div>
<div class="section" id="rationale">
<h1><a class="toc-backref" href="#id12" 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="#id13" 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="#id14" name="specification">Specification</a></h1>
<p>Unlike GLEP 22 the current keyword scheme as used in practice is not
changed.  Instead of proposing a 4-tuple <a class="footnote-reference" href="#id7" id="id3" name="id3">[3]</a> keyword, a 2-tuple
keyword is chosen for archs that require them.  Archs for which a
1-tuple keyword suffices, 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 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 keywords used 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.</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>
<p>Current USE-expansion is being maintained, for backwards compatibility.
Since the expansion is based on the variables mentioned above which do
not change, but only in the way they are generated, there should be no
problem in maintaining them.</p>
<div class="section" id="variables">
<h2><a class="toc-backref" href="#id15" name="variables">Variables</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 <a class="footnote-reference" href="#id8" id="id4" name="id4">[4]</a>, 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>It should be noted, however, that the bash script is a proof of concept
implementation.  It cannot be used as Portage will need this
information, which is written in Python.  Hence, an equivalent of this
bash script should be written in Python to be able to use it within
Portage.  This is considered to be a non-issue coding wise.</p>
</div>
</div>
<div class="section" id="references">
<h1><a class="toc-backref" href="#id16" name="references">References</a></h1>
<table class="footnote" frame="void" id="id5" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1" name="id5">[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="id6" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2" name="id6">[2]</a></td><td><p>For example in the perl ebuild, it is necessary to
fill in the C-library part, which on a FreeBSD system is other than
on a Linux system and currently is handled as follows:</p>
<pre class="literal-block">
[[ ${ELIBC} == &quot;FreeBSD&quot; ]] &amp;&amp; myconf=&quot;${myconf} -Dlibc=/usr/lib/libc.a&quot;
</pre>
</td></tr>
</tbody>
</table>
<table class="footnote" frame="void" id="id7" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id3" name="id7">[3]</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 decribes a field consisting out of four values.</td></tr>
</tbody>
</table>
<table class="footnote" frame="void" id="id8" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id4" name="id8">[4]</a></td><td><a class="reference" href="mailto:vapier">mailto:vapier</a> [at) gentoo .dot org</td></tr>
</tbody>
</table>
</div>
<div class="section" id="copyright">
<h1><a class="toc-backref" href="#id17" 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-09 21:32 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	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
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.8</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/01/26 20:56:55</a></td>
39			</tr>
40			<tr class="field"><th class="field-name">Author:</th><td class="field-body">Diego Pettenò, Fabian rroffen <{flameeyes,grobian}@gentoo.org></td>
41			</tr>
42			<tr class="field"><th class="field-name">Status:</th><td class="field-body">Active</td>
43			</tr>
44			<tr class="field"><th class="field-name">Type:</th><td class="field-body">Proposal</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"></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="id9" name="id9">Credits</a></li>
59			<li><a class="reference" href="#abstract" id="id10" name="id10">Abstract</a></li>
60			<li><a class="reference" href="#motivation" id="id11" name="id11">Motivation</a></li>
61			<li><a class="reference" href="#rationale" id="id12" name="id12">Rationale</a></li>
62			<li><a class="reference" href="#backwards-compatibility" id="id13" name="id13">Backwards Compatibility</a></li>
63			<li><a class="reference" href="#specification" id="id14" name="id14">Specification</a><ul>
64			<li><a class="reference" href="#variables" id="id15" name="id15">Variables</a></li>
65			</ul>
66			</li>
67			<li><a class="reference" href="#references" id="id16" name="id16">References</a></li>
68			<li><a class="reference" href="#copyright" id="id17" name="id17">Copyright</a></li>
69			</ul>
70			</div>
71			<div class="section" id="credits">
72			<h1><a class="toc-backref" href="#id9" 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="#id10" 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="#id5" 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="#id11" 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 as in
103			<a class="footnote-reference" href="#id6" id="id2" name="id2">[2]</a>.</p>
104			</div>
105			<div class="section" id="rationale">
106			<h1><a class="toc-backref" href="#id12" 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="#id13" 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="#id14" name="specification">Specification</a></h1>
133			<p>Unlike GLEP 22 the current keyword scheme as used in practice is not
134			changed. Instead of proposing a 4-tuple <a class="footnote-reference" href="#id7" id="id3" name="id3">[3]</a> keyword, a 2-tuple
135			keyword is chosen for archs that require them. Archs for which a
136			1-tuple keyword suffices, keep that keyword. Since this doesn't change
137			anything to the current situation in the tree, it is considered to be a
138			big 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 GNU/Linux. In such case the hyphen is also omitted. Examples
146			of such keywords are ppc-darwin and x86. This is fully compatible with
147			the current keywords used 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.</p>
153			<p>A map file can be used to have the various <tt class="literal"><span class="pre">CHOST</span></tt> values being
154			translated to the correct values for the four variables. This change is
155			invisible for ebuilds and eclasses, but allows to rely on these
156			variables as they are based on a 'safe' value -- the <tt class="literal"><span class="pre">CHOST</span></tt> variable.
157			Ebuilds should not be sensitive to the keyword value, but use the
158			aforementioned four variables instead. They allow specific tests for
159			properties. If this is undesirable, the full <tt class="literal"><span class="pre">CHOST</span></tt> variable can be
160			used to match a complete operating system.</p>
161			<p>Current USE-expansion is being maintained, for backwards compatibility.
162			Since the expansion is based on the variables mentioned above which do
163			not change, but only in the way they are generated, there should be no
164			problem in maintaining them.</p>
165			<div class="section" id="variables">
166			<h2><a class="toc-backref" href="#id15" name="variables">Variables</a></h2>
167			<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
168			file. The file can be overlaid, such that the following entries in the
169			map file (on the left of the arrow) will result in the assigned
170			variables on the right hand side of the arrow:</p>
171			<pre class="literal-block">
172			--linux-* -> KERNEL="linux"
173			--*-gnu -> ELIBC="glibc"
174			--kfreebsd-gnu -> KERNEL="FreeBSD" ELIBC="glibc"
175			--freebsd* -> KERNEL="FreeBSD" ELIBC="FreeBSD"
176			--darwin* -> KERNEL="Darwin" ELIBC="Darwin"
177			--netbsd* -> KERNEL="NetBSD" ELIBC="NetBSD"
178			--solaris* -> KERNEL="Solaris" ELIBC="Solaris"
179			</pre>
180			<p>A way to achieve this is proposed by Mike Frysinger <a class="footnote-reference" href="#id8" id="id4" name="id4">[4]</a>, which
181			suggests to have a env-map file, for instance filled with:</p>
182			<pre class="literal-block">
183			% cat env-map
184			-linux- KERNEL=linux
185			*-gnu ELIBC=glibc
186			x86_64-* ARCH=amd64
187			</pre>
188			<p>then the following bash script can be used to set the four variables to
189			their correct values:</p>
190			<pre class="literal-block">
191			% cat readmap
192			#!/bin/bash
193
194			CBUILD=${CBUILD:-${CHOST=${CHOST:-$1}}}
195			[[ -z ${CHOST} ]] && echo need chost
196
197			unset KERNEL ELIBC ARCH
198
199			while read LINE ; do
200			set -- ${LINE}
201			targ=$1
202			shift
203			[[ ${CBUILD} == ${targ} ]] && eval $@
204			done < env-map
205
206			echo ARCH=${ARCH} KERNEL=${KERNEL} ELIBC=${ELIBC}
207			</pre>
208			<p>Given the example env-map file, this script would result in:</p>
209			<pre class="literal-block">
210			% ./readmap x86_64-pc-linux-gnu
211			ARCH=amd64 KERNEL=linux ELIBC=glibc
212			</pre>
213			<p>It should be noted, however, that the bash script is a proof of concept
214			implementation. It cannot be used as Portage will need this
215			information, which is written in Python. Hence, an equivalent of this
216			bash script should be written in Python to be able to use it within
217			Portage. This is considered to be a non-issue coding wise.</p>
218			</div>
219			</div>
220			<div class="section" id="references">
221			<h1><a class="toc-backref" href="#id16" name="references">References</a></h1>
222			<table class="footnote" frame="void" id="id5" rules="none">
223			<colgroup><col class="label" /><col /></colgroup>
224			<tbody valign="top">
225			<tr><td class="label"><a class="fn-backref" href="#id1" name="id5">[1]</a></td><td>GLEP 22, New "keyword" system to incorporate various
226			userlands/kernels/archs, Goodyear,
227			(<a class="reference" href="http://glep.gentoo.org/glep-0022.html">http://glep.gentoo.org/glep-0022.html</a>)</td></tr>
228			</tbody>
229			</table>
230			<table class="footnote" frame="void" id="id6" rules="none">
231			<colgroup><col class="label" /><col /></colgroup>
232			<tbody valign="top">
233			<tr><td class="label"><a class="fn-backref" href="#id2" name="id6">[2]</a></td><td><p>For example in the perl ebuild, it is necessary to
234			fill in the C-library part, which on a FreeBSD system is other than
235			on a Linux system and currently is handled as follows:</p>
236			<pre class="literal-block">
237			[[ ${ELIBC} == "FreeBSD" ]] && myconf="${myconf} -Dlibc=/usr/lib/libc.a"
238			</pre>
239			</td></tr>
240			</tbody>
241			</table>
242			<table class="footnote" frame="void" id="id7" rules="none">
243			<colgroup><col class="label" /><col /></colgroup>
244			<tbody valign="top">
245			<tr><td class="label"><a class="fn-backref" href="#id3" name="id7">[3]</a></td><td>For the purpose of readability, we will refer to 1, 2 and
246			4-tuples, even though tuple in itself suggest a field consisting of
247			two values. For clarity: a 1-tuple describes a single value field,
248			while a 4-tuple decribes a field consisting out of four values.</td></tr>
249			</tbody>
250			</table>
251			<table class="footnote" frame="void" id="id8" rules="none">
252			<colgroup><col class="label" /><col /></colgroup>
253			<tbody valign="top">
254			<tr><td class="label"><a class="fn-backref" href="#id4" name="id8">[4]</a></td><td><a class="reference" href="mailto:vapier">mailto:vapier</a> [at) gentoo .dot org</td></tr>
255			</tbody>
256			</table>
257			</div>
258			<div class="section" id="copyright">
259			<h1><a class="toc-backref" href="#id17" name="copyright">Copyright</a></h1>
260			<p>This document has been placed in the public domain.</p>
261			</div>
262			</div>
263
264			<hr class="footer" />
265			<div class="footer">
266			<a class="reference" href="glep-0047.txt">View document source</a>.
267			Generated on: 2006-02-09 21:32 UTC.
268			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.
269			</div>
270			</body>
271			</html>
272