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

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

Parent Directory | Revision Log | View Patch Patch

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

 Legend:



Removed from v.1.1
 


changed lines


 
Added in v.1.2
 Legend:



Removed from v.1.1
 


changed lines


 
Added in v.1.2
-Removed from v.1.1
+Added in v.1.2

	ViewVC Help
Powered by ViewVC 1.1.13