en/glep/glep-0022.txt

GLEP: 22
Title: New "keyword" system to incorporate various userlands/kernels/archs
Version: $Revision: 1.1 $
Last-Modified: $Date: 2004/03/07 02:20:32 $
Author: Grant Goodyear <g2boojum@gentoo.org>
Status: Withdrawn
Type: Standards Track
Content-Type: text/x-rst
Created: 6-Mar-2004
Post-History: 6-Mar-2004 

Status
======

I'm withdrawing this GLEP.  It is clear from the discussions on 
gentoo-dev that although breaking they keywords into four components
is probably a good idea, the four components are *not* independent.
Thus, the "keyword explosion" that this GLEP tries to prevent is
inevitable.  The real issue, then, is how to make the keyword
explosion reasonably manageable, but that's a topic for another 
GLEP.

Credits
=======

This GLEP originated from the concerns that Daniel Robbins had with
the *x86obsd* keyword, and his desire to make the KEYWORDS variable more
"feature-rich".  Drobbins' original idea was that we should 
allow compound 
keywords such as gnu/x86, gnu/ppc, and macos/ppc (which would be explicit
versions of the more familiar x86, ppc, and macos keywords).  Method noted
that userland/arch failed to capture the full range of possibilities (what 
about a GNU userland on a BSD kernel+libc?), and
the issue has languished due to a lack of reasonable solutions.

Abstract
========

As Gentoo branches out to support non-Linux and non-GNU systems (such
as Hurd or the \*BSDs), the potential for an "explosion" of possible
keywords becomes rather large, since each 
new userland/kernel/arch/whatever
combination would require a new keyword.  
This GLEP proposes replacing the current
KEYWORDS variable with four variables, ARCH, USERLAND, KERNEL, and LIBC,
along with sensible defaults to keep the new system manageable.

Motivation
==========

Since the beginning, Gentoo Linux has been conceived as a "metadistribution"
that combines remarkable flexibility with sensible defaults and exceptional
maintainablilty.  The goal of the Gentoo-Alt_ project has been to extend that
flexibility to include systems other than GNU/Linux.  For example, the author
of this GLEP has been working to create a version_ of Gentoo that uses 
OpenBSD_ as the underlying kernel, userland, and libc.  OpenBSD_ supports
a variety of different architectures, so, in principle, we would need a new
*openbsd-arch* keyword for each supported architecture.  In fact, the situation 
is even more complicated, because the Gentoo-Alt_ project would eventually
like
to support the option of "mixing-and-matching" GNU/\*BSD/whatever userlands
and libcs irrespective of the underlying kernel. (Debian_, for example
has a similar BSD project_, except that they have replaced the 
BSD userland with a GNU userland.)  The net result is that we would need 
keywords that specified all possible permutations of arch, userland, kernel
and libc.  Not fun.

.. _Gentoo-Alt: http://www.gentoo.org/proj/en/gentoo-alt/index.xml
.. _OpenBSD: http://www.openbsd.com
.. _version: http://www.gentoo.org/proj/en/gentoo-alt/bsd/index.xml
.. _Debian: http://www.debian.org
.. _project: http://www.debian.org/ports/netbsd/

Specification
=============

New Variables
-------------

I suggest that we replace the single KEYWORDS variable in ebuilds
with four separate variables: ARCH, USERLAND, LIBC, and KERNEL.

    ARCH: 
        x86, amd64, cobalt, mips64, arm, hppa, ia64, ppc64, sparc
    USERLAND: 
        gnu, bsd
    LIBC: 
        glibc, openbsd, freebsd, netbsd, macosx
    KERNEL: 
        linux, selinux, openbsd, freebsd, netbsd, macosx

(The above examples are not meant to be complete.  Hurd, for example
is not included because I know very little about Hurd.)
For each variable the standard "-,-\*,~" prefixes would be allowed.
Similarly, `/etc/make.conf` would have ACCEPT_ARCH, ACCEPT_USERLAND,
ACCEPT_LIBC, and ACCEPT_KERNEL variables.

Reasonable Defaults
-------------------

To keep this system manageable, we need sensible defaults. An ebuild
that has missing USERLAND, KERNEL, or LIBC variables is provided 
with implicit USERLAND="gnu", KERNEL="linux", and/or LIBC="glibc"
variables.  However, once a variable is explicitly added (such as 
KERNEL="openbsd"), the default is no longer assumed.  That is,
one would need KERNEL="openbsd linux" if the ebuild is stable on
both openbsd and linux kernels.

The ARCH variable, on the other hand, does *not* have a default, per se.
Instead, if no ARCH variable exists then portage would automatically
add the ebuild's KEYWORD entries to ARCH.  Thus, all current ebuilds
would still work without changes, allowing for a gradual transition
to the new system as the new variables are needed.

Profiles
--------

Along with an explosion of keywords comes a concomitant explosion
of potential profiles.  The good news is that profiles show up only
in a single directory, so an explosion there is easier to contain.
I suggest an arch-kernel-userland-libc-version naming scheme, with
the kernel-userland-libc terms defaulting to linux-gnu-glibc if
absent.  (Yes, Chemists do tend to be fond of systematic naming
systems.)

One drawback to having a large number of profiles is that maintainance
becomes a significant problem.  In fact, one could reasonably argue
that the current number of profiles is already too many to be
easily maintained.  One proposal that has been raised to simplify
matters is the idea of stackable, or cascading, profiles, so that
only differences between profiles would have to be maintained.

Rationale
=========

The proposed new "keywording" system is far from elegant, which is
a substantial drawback.  On the other hand, it is simple, it requires
relatively minor changes (albeit ones that eventually would impact
every ebuild in the portage tree), and the changes can be implemented
gradually over time.

Implementation
==============

Implementation of this GLEP would divide into adding
Portage functionality to support the new system and 
modifying ebuilds to 
comply with the new system.
The Portage support involves hacking Portage 
to assemble and check a four-state 
arch-userland-kernel-libc variable instead of the simpler
KEYWORD variable.  One might quibble over algorithmic issues, but
the actual concept is pretty straightforward.  Rewriting ebuilds,
on the other hand, is a massive undertaking.  Fortunately, it is
also a process that can be done over whatever length of time is
required, since "legacy" ebuilds should work with no changes.


Backwards Compatibility
=======================

Backwards compatibility has already been addressed in some detail,
with the stated goal being a system that would leave all current
ebuilds in a still-functioning state after the portage modifications
have been made.  However, we are already using an ARCH variable for
some arcane purpose in Portage, and that issue would still need to
be resolved.


Copyright
=========

This document is licensed under the Creative Commons - Attribution / Share
Alike license. (http://creativecommons.org/licenses/by-sa/1.0)
1	g2boojum	1.1	GLEP: 22
2			Title: New "keyword" system to incorporate various userlands/kernels/archs
3			Version: $Revision: 1.1 $
4	g2boojum	1.2	Last-Modified: $Date: 2004/03/07 02:20:32 $
5	g2boojum	1.1	Author: Grant Goodyear <g2boojum@gentoo.org>
6	g2boojum	1.2	Status: Withdrawn
7	g2boojum	1.1	Type: Standards Track
8			Content-Type: text/x-rst
9			Created: 6-Mar-2004
10			Post-History: 6-Mar-2004
11
12	g2boojum	1.2	Status
13			======
14
15			I'm withdrawing this GLEP. It is clear from the discussions on
16			gentoo-dev that although breaking they keywords into four components
17			is probably a good idea, the four components are not independent.
18			Thus, the "keyword explosion" that this GLEP tries to prevent is
19			inevitable. The real issue, then, is how to make the keyword
20			explosion reasonably manageable, but that's a topic for another
21			GLEP.
22
23	g2boojum	1.1	Credits
24			=======
25
26			This GLEP originated from the concerns that Daniel Robbins had with
27			the x86obsd keyword, and his desire to make the KEYWORDS variable more
28			"feature-rich". Drobbins' original idea was that we should
29			allow compound
30			keywords such as gnu/x86, gnu/ppc, and macos/ppc (which would be explicit
31			versions of the more familiar x86, ppc, and macos keywords). Method noted
32			that userland/arch failed to capture the full range of possibilities (what
33			about a GNU userland on a BSD kernel+libc?), and
34			the issue has languished due to a lack of reasonable solutions.
35
36			Abstract
37			========
38
39			As Gentoo branches out to support non-Linux and non-GNU systems (such
40			as Hurd or the \*BSDs), the potential for an "explosion" of possible
41			keywords becomes rather large, since each
42			new userland/kernel/arch/whatever
43			combination would require a new keyword.
44			This GLEP proposes replacing the current
45	g2boojum	1.2	KEYWORDS variable with four variables, ARCH, USERLAND, KERNEL, and LIBC,
46	g2boojum	1.1	along with sensible defaults to keep the new system manageable.
47
48			Motivation
49			==========
50
51			Since the beginning, Gentoo Linux has been conceived as a "metadistribution"
52			that combines remarkable flexibility with sensible defaults and exceptional
53			maintainablilty. The goal of the Gentoo-Alt_ project has been to extend that
54			flexibility to include systems other than GNU/Linux. For example, the author
55			of this GLEP has been working to create a version_ of Gentoo that uses
56			OpenBSD_ as the underlying kernel, userland, and libc. OpenBSD_ supports
57			a variety of different architectures, so, in principle, we would need a new
58			openbsd-arch keyword for each supported architecture. In fact, the situation
59			is even more complicated, because the Gentoo-Alt_ project would eventually
60			like
61			to support the option of "mixing-and-matching" GNU/\*BSD/whatever userlands
62			and libcs irrespective of the underlying kernel. (Debian_, for example
63			has a similar BSD project_, except that they have replaced the
64			BSD userland with a GNU userland.) The net result is that we would need
65			keywords that specified all possible permutations of arch, userland, kernel
66			and libc. Not fun.
67
68			.. _Gentoo-Alt: http://www.gentoo.org/proj/en/gentoo-alt/index.xml
69			.. _OpenBSD: http://www.openbsd.com
70			.. _version: http://www.gentoo.org/proj/en/gentoo-alt/bsd/index.xml
71			.. _Debian: http://www.debian.org
72			.. _project: http://www.debian.org/ports/netbsd/
73
74			Specification
75			=============
76
77			New Variables
78			-------------
79
80			I suggest that we replace the single KEYWORDS variable in ebuilds
81			with four separate variables: ARCH, USERLAND, LIBC, and KERNEL.
82
83			ARCH:
84			x86, amd64, cobalt, mips64, arm, hppa, ia64, ppc64, sparc
85			USERLAND:
86			gnu, bsd
87			LIBC:
88			glibc, openbsd, freebsd, netbsd, macosx
89			KERNEL:
90			linux, selinux, openbsd, freebsd, netbsd, macosx
91
92			(The above examples are not meant to be complete. Hurd, for example
93			is not included because I know very little about Hurd.)
94			For each variable the standard "-,-\*,~" prefixes would be allowed.
95			Similarly, `/etc/make.conf` would have ACCEPT_ARCH, ACCEPT_USERLAND,
96			ACCEPT_LIBC, and ACCEPT_KERNEL variables.
97
98			Reasonable Defaults
99			-------------------
100
101			To keep this system manageable, we need sensible defaults. An ebuild
102			that has missing USERLAND, KERNEL, or LIBC variables is provided
103			with implicit USERLAND="gnu", KERNEL="linux", and/or LIBC="glibc"
104			variables. However, once a variable is explicitly added (such as
105			KERNEL="openbsd"), the default is no longer assumed. That is,
106			one would need KERNEL="openbsd linux" if the ebuild is stable on
107			both openbsd and linux kernels.
108
109			The ARCH variable, on the other hand, does not have a default, per se.
110			Instead, if no ARCH variable exists then portage would automatically
111			add the ebuild's KEYWORD entries to ARCH. Thus, all current ebuilds
112			would still work without changes, allowing for a gradual transition
113			to the new system as the new variables are needed.
114
115			Profiles
116			--------
117
118			Along with an explosion of keywords comes a concomitant explosion
119			of potential profiles. The good news is that profiles show up only
120			in a single directory, so an explosion there is easier to contain.
121			I suggest an arch-kernel-userland-libc-version naming scheme, with
122			the kernel-userland-libc terms defaulting to linux-gnu-glibc if
123			absent. (Yes, Chemists do tend to be fond of systematic naming
124			systems.)
125
126			One drawback to having a large number of profiles is that maintainance
127			becomes a significant problem. In fact, one could reasonably argue
128			that the current number of profiles is already too many to be
129			easily maintained. One proposal that has been raised to simplify
130			matters is the idea of stackable, or cascading, profiles, so that
131			only differences between profiles would have to be maintained.
132
133			Rationale
134			=========
135
136			The proposed new "keywording" system is far from elegant, which is
137			a substantial drawback. On the other hand, it is simple, it requires
138			relatively minor changes (albeit ones that eventually would impact
139			every ebuild in the portage tree), and the changes can be implemented
140			gradually over time.
141
142			Implementation
143			==============
144
145			Implementation of this GLEP would divide into adding
146			Portage functionality to support the new system and
147			modifying ebuilds to
148			comply with the new system.
149			The Portage support involves hacking Portage
150			to assemble and check a four-state
151			arch-userland-kernel-libc variable instead of the simpler
152			KEYWORD variable. One might quibble over algorithmic issues, but
153			the actual concept is pretty straightforward. Rewriting ebuilds,
154			on the other hand, is a massive undertaking. Fortunately, it is
155			also a process that can be done over whatever length of time is
156			required, since "legacy" ebuilds should work with no changes.
157
158
159			Backwards Compatibility
160			=======================
161
162			Backwards compatibility has already been addressed in some detail,
163			with the stated goal being a system that would leave all current
164			ebuilds in a still-functioning state after the portage modifications
165			have been made. However, we are already using an ARCH variable for
166			some arcane purpose in Portage, and that issue would still need to
167			be resolved.
168
169
170			Copyright
171			=========
172
173			This document is licensed under the Creative Commons - Attribution / Share
174			Alike license. (http://creativecommons.org/licenses/by-sa/1.0)