/[gentoo]/xml/htdocs/proj/en/glep/glep-0047.txt
Gentoo

Diff of /xml/htdocs/proj/en/glep/glep-0047.txt

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.1 Revision 1.2
1GLEP: 47 1GLEP: 47
2Title: Creating 'safe' environment variables 2Title: Creating 'safe' environment variables
3Version: $Revision: 1.1 $ 3Version: $Revision: 1.2 $
4Last-Modified: $Date: 2006/02/09 21:42:57 $ 4Last-Modified: $Date: 2006/02/11 21:43:14 $
5Author: Diego Pettenò, Fabian Groffen <{flameeyes,grobian}@gentoo.org> 5Author: Diego Pettenò, Fabian Groffen
6Status: Active 6Status: Draft
7Type: Standards Track 7Type: Standards Track
8Content-Type: text/x-rst 8Content-Type: text/x-rst
9Created: 14-Oct-2005 9Created: 14-Oct-2005
10Post-History: 10Post-History: 09-Feb-2006
11 11
12 12
13Credits 13Credits
14======= 14=======
15 15
45plethora of 'alternative' configurations such as FreeBSD, NetBSD, 45plethora of 'alternative' configurations such as FreeBSD, NetBSD,
46DragonflyBSD, GNU/kFreeBSD, Mac OS X, (Open)Darwin, (Open)Solaris and so 46DragonflyBSD, GNU/kFreeBSD, Mac OS X, (Open)Darwin, (Open)Solaris and so
47on. As such, the project is in need for a better grip on the actual 47on. As such, the project is in need for a better grip on the actual
48host being built on. This information on the host environment is 48host being built on. This information on the host environment is
49necessary to make proper (automated) decisions on settings that are 49necessary to make proper (automated) decisions on settings that are
50highly dependant on the build environment, such as platform or as in 50highly dependant on the build environment, such as platform or C-library
51[2]_. 51implementation.
52 52
53 53
54Rationale 54Rationale
55========= 55=========
56 56
82 82
83 83
84Specification 84Specification
85============= 85=============
86 86
87Unlike GLEP 22 the current keyword scheme as used in practice is not 87Unlike GLEP 22 the currently used keyword scheme is not changed.
88changed. Instead of proposing a 4-tuple [3]_ keyword, a 2-tuple 88Instead of proposing a 4-tuple [2]_ keyword, a 2-tuple keyword is chosen
89keyword is chosen for archs that require them. Archs for which a 89for archs that require them. Archs for which a 1-tuple keyword
901-tuple keyword suffices, keep that keyword. Since this doesn't change 90suffices, can keep that keyword. Since this doesn't change anything to
91anything to the current situation in the tree, it is considered to be a 91the current situation in the tree, it is considered to be a big
92big advantage over the 4-tuple keyword from GLEP 22. This GLEP is an 92advantage over the 4-tuple keyword from GLEP 22. This GLEP is an
93official specification of the syntax of the keyword. 93official specification of the syntax of the keyword.
94 94
95Keywords will consist out of two parts separated by a hyphen ('-'). The 95Keywords will consist out of two parts separated by a hyphen ('-'). The
96left hand part of the keyword 2-tuple is the architecture, such as 96left hand part of the keyword 2-tuple is the architecture, such as
97ppc64, sparc and x86. The right hand part indicates the operating 97ppc64, sparc and x86. The right hand part indicates the operating
98system or distribution, such as linux, macos, darwin, obsd, etc. If the 98system or distribution, such as linux, macos, darwin, obsd, etc. If the
99right hand part is omitted, it implies the operating system/distribution 99right hand part is omitted, it implies the operating system/distribution
100type is GNU/Linux. In such case the hyphen is also omitted. Examples 100type is Gentoo GNU/Linux. In such case the hyphen is also omitted.
101of such keywords are ppc-darwin and x86. This is fully compatible with 101Examples of such keywords are ppc-darwin and x86. This is fully
102the current keywords used in the tree. 102compatible with the current use of keywords in the tree.
103 103
104The variables ``ELIBC``, ``KERNEL`` and ``ARCH`` are currently set in 104The variables ``ELIBC``, ``KERNEL`` and ``ARCH`` are currently set in
105the profiles when other than their defaults for a GNU/Linux system. 105the profiles when other than their defaults for a GNU/Linux system.
106They can as such easily be overridden and defined by the user. To 106They can as such easily be overridden and defined by the user. To
107prevent this from happening, the variables should be auto filled by 107prevent this from happening, the variables should be auto filled by
108Portage itself, based on the ``CHOST`` variable. 108Portage itself, based on the ``CHOST`` variable. While the ``CHOST``
109variable can be as easy as the others set by the user, it still is
110assumed to be 'safe'. This assumption is grounded in the fact that the
111variable itself is being used in various other places with the same
112intention, and that an invalid ``CHOST`` will cause major malfunctioning
113of the system. A user that changes the ``CHOST`` into something that is
114not valid for the system, is already warned that this might render the
115system unusable. Concluding, the 'safeness' of the ``CHOST`` variable
116is based on externally assumed 'safeness', which's discussion falls
117outside this GLEP.
118
119Current USE-expansion of the variables is being maintained, as this
120results in full backward compatibility. Since the variables themself
121don't change in what they represent, but only how they are being
122assigned, there should be no problem in maintaining them. Using
123USE-expansion, conditional code can be written down in ebuilds, which is
124not different from any existing methods at all::
125
126 ...
127 RDEPEND="elibc_FreeBSD? ( sys-libs/com_err )"
128 ...
129 src_compile() {
130 ...
131 use elibc_FreeBSD && myconf="${myconf} -Dlibc=/usr/lib/libc.a"
132 ...
133 }
134
135Alternatively, the variables ``ELIBC``, ``KERNEL`` and ``ARCH``
136are available in the ebuild evironment and they can be used instead of
137invoking ``xxx_Xxxx`` or in switch statements where they are actually
138necessary.
109 139
110A map file can be used to have the various ``CHOST`` values being 140A map file can be used to have the various ``CHOST`` values being
111translated to the correct values for the four variables. This change is 141translated to the correct values for the four variables. This change is
112invisible for ebuilds and eclasses, but allows to rely on these 142invisible for ebuilds and eclasses, but allows to rely on these
113variables as they are based on a 'safe' value -- the ``CHOST`` variable. 143variables as they are based on a 'safe' value -- the ``CHOST`` variable.
114Ebuilds should not be sensitive to the keyword value, but use the 144Ebuilds should not be sensitive to the keyword value, but use the
115aforementioned four variables instead. They allow specific tests for 145aforementioned four variables instead. They allow specific tests for
116properties. If this is undesirable, the full ``CHOST`` variable can be 146properties. If this is undesirable, the full ``CHOST`` variable can be
117used to match a complete operating system. 147used to match a complete operating system.
118 148
119Current USE-expansion is being maintained, for backwards compatibility.
120Since the expansion is based on the variables mentioned above which do
121not change, but only in the way they are generated, there should be no
122problem in maintaining them.
123 149
124 150Variable Assignment
125Variables 151-------------------
126---------
127 152
128The ``ELIBC``, ``KERNEL``, ``ARCH`` variables are filled from a profile 153The ``ELIBC``, ``KERNEL``, ``ARCH`` variables are filled from a profile
129file. The file can be overlaid, such that the following entries in the 154file. The file can be overlaid, such that the following entries in the
130map file (on the left of the arrow) will result in the assigned 155map file (on the left of the arrow) will result in the assigned
131variables on the right hand side of the arrow: 156variables on the right hand side of the arrow::
132
133::
134 157
135 *-*-linux-* -> KERNEL="linux" 158 *-*-linux-* -> KERNEL="linux"
136 *-*-*-gnu -> ELIBC="glibc" 159 *-*-*-gnu -> ELIBC="glibc"
137 *-*-kfreebsd-gnu -> KERNEL="FreeBSD" ELIBC="glibc" 160 *-*-kfreebsd-gnu -> KERNEL="FreeBSD" ELIBC="glibc"
138 *-*-freebsd* -> KERNEL="FreeBSD" ELIBC="FreeBSD" 161 *-*-freebsd* -> KERNEL="FreeBSD" ELIBC="FreeBSD"
139 *-*-darwin* -> KERNEL="Darwin" ELIBC="Darwin" 162 *-*-darwin* -> KERNEL="Darwin" ELIBC="Darwin"
140 *-*-netbsd* -> KERNEL="NetBSD" ELIBC="NetBSD" 163 *-*-netbsd* -> KERNEL="NetBSD" ELIBC="NetBSD"
141 *-*-solaris* -> KERNEL="Solaris" ELIBC="Solaris" 164 *-*-solaris* -> KERNEL="Solaris" ELIBC="Solaris"
142 165
143A way to achieve this is proposed by Mike Frysinger [4]_, which 166A way to achieve this is proposed by Mike Frysinger, which
144suggests to have a env-map file, for instance filled with: 167suggests to have a env-map file, for instance filled with::
145
146::
147 168
148 % cat env-map 169 % cat env-map
149 *-linux-* KERNEL=linux 170 *-linux-* KERNEL=linux
150 *-gnu ELIBC=glibc 171 *-gnu ELIBC=glibc
151 x86_64-* ARCH=amd64 172 x86_64-* ARCH=amd64
152 173
153then the following bash script can be used to set the four variables to 174then the following bash script can be used to set the four variables to
154their correct values: 175their correct values::
155
156::
157 176
158 % cat readmap 177 % cat readmap
159 #!/bin/bash 178 #!/bin/bash
160 179
161 CBUILD=${CBUILD:-${CHOST=${CHOST:-$1}}} 180 CBUILD=${CBUILD:-${CHOST=${CHOST:-$1}}}
170 [[ ${CBUILD} == ${targ} ]] && eval $@ 189 [[ ${CBUILD} == ${targ} ]] && eval $@
171 done < env-map 190 done < env-map
172 191
173 echo ARCH=${ARCH} KERNEL=${KERNEL} ELIBC=${ELIBC} 192 echo ARCH=${ARCH} KERNEL=${KERNEL} ELIBC=${ELIBC}
174 193
175Given the example env-map file, this script would result in: 194Given the example env-map file, this script would result in::
176
177::
178 195
179 % ./readmap x86_64-pc-linux-gnu 196 % ./readmap x86_64-pc-linux-gnu
180 ARCH=amd64 KERNEL=linux ELIBC=glibc 197 ARCH=amd64 KERNEL=linux ELIBC=glibc
181 198
199The entries in the ``env-map`` file will be evaluated in a forward
200linear full scan. A side-effect of this exhaustive search is that the
201variables can be re-assigned if multiple entries match the given
202``CHOST``. Because of this, the order of the entries does matter.
203Because the ``env-map`` file size is assumed not to exceed the block
204size of the file system, the performance penalty of a full scan versus
205'first-hit-stop technique' is assumed to be minimal.
206
182It should be noted, however, that the bash script is a proof of concept 207It should be noted, however, that the above bash script is a proof of
183implementation. It cannot be used as Portage will need this 208concept implementation. Since Portage is largerly written in Python, it
184information, which is written in Python. Hence, an equivalent of this 209will be more efficient to write an equivalent of this code in Python
185bash script should be written in Python to be able to use it within 210also. Coding wise, this is considered to be a non-issue, but the format
186Portage. This is considered to be a non-issue coding wise. 211of the ``env-map`` file, and especially its wildcard characters, might
212not be the best match with Python. For this purpose, the format
213specification of the ``env-map`` file is deferred to the Python
214implementation, and only the requirements are given here.
215
216The ``env-map`` file should be capable of encoding a ``key``, ``value``
217pair, where ``key`` is a (regular) expression that matches a
218chost-string, and ``value`` contains at least one, distinct variable
219assignment for the variables ``ARCH``, ``KERNEL`` and ``ELIBC``. The
220interpreter of the ``env-map`` file must scan the file linearly and
221continue trying to match the ``key``\s and assign variables if
222appropriate until the end of file.
223
224Since Portage will use the ``env-map`` file, the location of the file is
225beyond the scope of this GLEP and up to the Portage implementors.
187 226
188 227
189References 228References
190========== 229==========
191 230
192.. [1] GLEP 22, New "keyword" system to incorporate various 231.. [1] GLEP 22, New "keyword" system to incorporate various
193 userlands/kernels/archs, Goodyear, 232 userlands/kernels/archs, Goodyear,
194 (http://glep.gentoo.org/glep-0022.html) 233 (http://glep.gentoo.org/glep-0022.html)
195 234
196.. [2] For example in the perl ebuild, it is necessary to
197 fill in the C-library part, which on a FreeBSD system is other than
198 on a Linux system and currently is handled as follows:
199 ::
200
201 [[ ${ELIBC} == "FreeBSD" ]] && myconf="${myconf} -Dlibc=/usr/lib/libc.a"
202
203.. [3] For the purpose of readability, we will refer to 1, 2 and 235.. [2] For the purpose of readability, we will refer to 1, 2 and
204 4-tuples, even though tuple in itself suggest a field consisting of 236 4-tuples, even though tuple in itself suggest a field consisting of
205 two values. For clarity: a 1-tuple describes a single value field, 237 two values. For clarity: a 1-tuple describes a single value field,
206 while a 4-tuple decribes a field consisting out of four values. 238 while a 4-tuple describes a field consisting out of four values.
207
208.. [4] mailto:vapier [at) gentoo .dot org
209
210 239
211 240
212Copyright 241Copyright
213========= 242=========
214 243

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.2

  ViewVC Help
Powered by ViewVC 1.1.20