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/02/22 02:09:07 $
Author: Grant Goodyear <g2boojum@gentoo.org>
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 6-Mar-2004
Post-History: 6-Mar-2004 

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