/[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.3
1GLEP: 47 1GLEP: 47
2Title: Creating 'safe' environment variables 2Title: Creating 'safe' environment variables
3Version: $Revision: 1.1 $ 3Version: $Revision: 1.3 $
4Last-Modified: $Date: 2006/02/09 21:42:57 $ 4Last-Modified: $Date: 2006/02/12 19:57:57 $
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 96part up to the first hyphen from the left of the keyword 2-tuple is the
97ppc64, sparc and x86. The right hand part indicates the operating 97architecture, such as ppc64, sparc and x86. Allowed characters for the
98architecture name are in ``a-z0-9``. The remaining part on the right of
99the first hyphen from the left indicates the operating system or
98system or distribution, such as linux, macos, darwin, obsd, etc. If the 100distribution, such as linux, macos, darwin, obsd, et-cetera. If the
99right hand part is omitted, it implies the operating system/distribution 101right hand part is omitted, it implies the operating system/distribution
100type is GNU/Linux. In such case the hyphen is also omitted. Examples 102type is Gentoo GNU/Linux. In such case the hyphen is also omitted, and
101of such keywords are ppc-darwin and x86. This is fully compatible with 103the keyword consists of solely the architecture. The operating system
102the current keywords used in the tree. 104or distribution name can consist out of characters in ``a-zA-Z0-9_+:-``.
105Please note that the hyphen is an allowed character, and therefore the
106separation of the two fields in the keyword is only determinable by
107scanning for the first hyphen character from the start of the keyword
108string. Examples of keywords following this specification are
109ppc-darwin and x86. This is fully compatible with the current use of
110keywords in the tree.
103 111
104The variables ``ELIBC``, ``KERNEL`` and ``ARCH`` are currently set in 112The variables ``ELIBC``, ``KERNEL`` and ``ARCH`` are currently set in
105the profiles when other than their defaults for a GNU/Linux system. 113the profiles when other than their defaults for a GNU/Linux system.
106They can as such easily be overridden and defined by the user. To 114They can as such easily be overridden and defined by the user. To
107prevent this from happening, the variables should be auto filled by 115prevent this from happening, the variables should be auto filled by
108Portage itself, based on the ``CHOST`` variable. 116Portage itself, based on the ``CHOST`` variable. While the ``CHOST``
117variable can be as easy as the others set by the user, it still is
118assumed to be 'safe'. This assumption is grounded in the fact that the
119variable itself is being used in various other places with the same
120intention, and that an invalid ``CHOST`` will cause major malfunctioning
121of the system. A user that changes the ``CHOST`` into something that is
122not valid for the system, is already warned that this might render the
123system unusable. Concluding, the 'safeness' of the ``CHOST`` variable
124is based on externally assumed 'safeness', which's discussion falls
125outside this GLEP.
126
127Current USE-expansion of the variables is being maintained, as this
128results in full backward compatibility. Since the variables themself
129don't change in what they represent, but only how they are being
130assigned, there should be no problem in maintaining them. Using
131USE-expansion, conditional code can be written down in ebuilds, which is
132not different from any existing methods at all::
133
134 ...
135 RDEPEND="elibc_FreeBSD? ( sys-libs/com_err )"
136 ...
137 src_compile() {
138 ...
139 use elibc_FreeBSD && myconf="${myconf} -Dlibc=/usr/lib/libc.a"
140 ...
141 }
142
143Alternatively, the variables ``ELIBC``, ``KERNEL`` and ``ARCH``
144are available in the ebuild evironment and they can be used instead of
145invoking ``xxx_Xxxx`` or in switch statements where they are actually
146necessary.
109 147
110A map file can be used to have the various ``CHOST`` values being 148A map file can be used to have the various ``CHOST`` values being
111translated to the correct values for the four variables. This change is 149translated to the correct values for the four variables. This change is
112invisible for ebuilds and eclasses, but allows to rely on these 150invisible for ebuilds and eclasses, but allows to rely on these
113variables as they are based on a 'safe' value -- the ``CHOST`` variable. 151variables as they are based on a 'safe' value -- the ``CHOST`` variable.
114Ebuilds should not be sensitive to the keyword value, but use the 152Ebuilds should not be sensitive to the keyword value, but use the
115aforementioned four variables instead. They allow specific tests for 153aforementioned four variables instead. They allow specific tests for
116properties. If this is undesirable, the full ``CHOST`` variable can be 154properties. If this is undesirable, the full ``CHOST`` variable can be
117used to match a complete operating system. 155used to match a complete operating system.
118 156
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 157
124 158Variable Assignment
125Variables 159-------------------
126---------
127 160
128The ``ELIBC``, ``KERNEL``, ``ARCH`` variables are filled from a profile 161The ``ELIBC``, ``KERNEL``, ``ARCH`` variables are filled from a profile
129file. The file can be overlaid, such that the following entries in the 162file. 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 163map file (on the left of the arrow) will result in the assigned
131variables on the right hand side of the arrow: 164variables on the right hand side of the arrow::
132
133::
134 165
135 *-*-linux-* -> KERNEL="linux" 166 *-*-linux-* -> KERNEL="linux"
136 *-*-*-gnu -> ELIBC="glibc" 167 *-*-*-gnu -> ELIBC="glibc"
137 *-*-kfreebsd-gnu -> KERNEL="FreeBSD" ELIBC="glibc" 168 *-*-kfreebsd-gnu -> KERNEL="FreeBSD" ELIBC="glibc"
138 *-*-freebsd* -> KERNEL="FreeBSD" ELIBC="FreeBSD" 169 *-*-freebsd* -> KERNEL="FreeBSD" ELIBC="FreeBSD"
139 *-*-darwin* -> KERNEL="Darwin" ELIBC="Darwin" 170 *-*-darwin* -> KERNEL="Darwin" ELIBC="Darwin"
140 *-*-netbsd* -> KERNEL="NetBSD" ELIBC="NetBSD" 171 *-*-netbsd* -> KERNEL="NetBSD" ELIBC="NetBSD"
141 *-*-solaris* -> KERNEL="Solaris" ELIBC="Solaris" 172 *-*-solaris* -> KERNEL="Solaris" ELIBC="Solaris"
142 173
143A way to achieve this is proposed by Mike Frysinger [4]_, which 174A way to achieve this is proposed by Mike Frysinger, which
144suggests to have a env-map file, for instance filled with: 175suggests to have a env-map file, for instance filled with::
145
146::
147 176
148 % cat env-map 177 % cat env-map
149 *-linux-* KERNEL=linux 178 *-linux-* KERNEL=linux
150 *-gnu ELIBC=glibc 179 *-gnu ELIBC=glibc
151 x86_64-* ARCH=amd64 180 x86_64-* ARCH=amd64
152 181
153then the following bash script can be used to set the four variables to 182then the following bash script can be used to set the four variables to
154their correct values: 183their correct values::
155
156::
157 184
158 % cat readmap 185 % cat readmap
159 #!/bin/bash 186 #!/bin/bash
160 187
161 CBUILD=${CBUILD:-${CHOST=${CHOST:-$1}}} 188 CBUILD=${CBUILD:-${CHOST=${CHOST:-$1}}}
170 [[ ${CBUILD} == ${targ} ]] && eval $@ 197 [[ ${CBUILD} == ${targ} ]] && eval $@
171 done < env-map 198 done < env-map
172 199
173 echo ARCH=${ARCH} KERNEL=${KERNEL} ELIBC=${ELIBC} 200 echo ARCH=${ARCH} KERNEL=${KERNEL} ELIBC=${ELIBC}
174 201
175Given the example env-map file, this script would result in: 202Given the example env-map file, this script would result in::
176
177::
178 203
179 % ./readmap x86_64-pc-linux-gnu 204 % ./readmap x86_64-pc-linux-gnu
180 ARCH=amd64 KERNEL=linux ELIBC=glibc 205 ARCH=amd64 KERNEL=linux ELIBC=glibc
181 206
207The entries in the ``env-map`` file will be evaluated in a forward
208linear full scan. A side-effect of this exhaustive search is that the
209variables can be re-assigned if multiple entries match the given
210``CHOST``. Because of this, the order of the entries does matter.
211Because the ``env-map`` file size is assumed not to exceed the block
212size of the file system, the performance penalty of a full scan versus
213'first-hit-stop technique' is assumed to be minimal.
214
182It should be noted, however, that the bash script is a proof of concept 215It should be noted, however, that the above bash script is a proof of
183implementation. It cannot be used as Portage will need this 216concept implementation. Since Portage is largerly written in Python, it
184information, which is written in Python. Hence, an equivalent of this 217will 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 218also. Coding wise, this is considered to be a non-issue, but the format
186Portage. This is considered to be a non-issue coding wise. 219of the ``env-map`` file, and especially its wildcard characters, might
220not be the best match with Python. For this purpose, the format
221specification of the ``env-map`` file is deferred to the Python
222implementation, and only the requirements are given here.
223
224The ``env-map`` file should be capable of encoding a ``key``, ``value``
225pair, where ``key`` is a (regular) expression that matches a
226chost-string, and ``value`` contains at least one, distinct variable
227assignment for the variables ``ARCH``, ``KERNEL`` and ``ELIBC``. The
228interpreter of the ``env-map`` file must scan the file linearly and
229continue trying to match the ``key``\s and assign variables if
230appropriate until the end of file.
231
232Since Portage will use the ``env-map`` file, the location of the file is
233beyond the scope of this GLEP and up to the Portage implementors.
187 234
188 235
189References 236References
190========== 237==========
191 238
192.. [1] GLEP 22, New "keyword" system to incorporate various 239.. [1] GLEP 22, New "keyword" system to incorporate various
193 userlands/kernels/archs, Goodyear, 240 userlands/kernels/archs, Goodyear,
194 (http://glep.gentoo.org/glep-0022.html) 241 (http://glep.gentoo.org/glep-0022.html)
195 242
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 243.. [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 244 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, 245 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. 246 while a 4-tuple describes a field consisting out of four values.
207
208.. [4] mailto:vapier [at) gentoo .dot org
209
210 247
211 248
212Copyright 249Copyright
213========= 250=========
214 251

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

  ViewVC Help
Powered by ViewVC 1.1.20