en/glep/glep-0022.txt

GLEP: 22
Title: New "keyword" system to incorporate various userlands/kernels/archs
Version: $Revision: 1.5 $
Last-Modified: $Date: 2004/07/20 18:15:17 $
Author: Grant Goodyear <g2boojum@gentoo.org>
Status: Informational
Type: Standards Track
Content-Type: text/x-rst
Created: 6-Mar-2004
Post-History: 6-Mar-2004, 5-Jun-2004, 20-Jul-2004

Status
======

After withdrawing this GLEP temporarily, a rewritten version has
now been resubmitted.  This version no longer tries to prevent a
keyword explosion, but merely tries to make it manageable.  

This version was approved on 14-Jun-2004, with the amendment that cascading
profiles should be used. 

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.  The original version of this GLEP
generated quite useful comments which hopefully have been addressed here to
make the GLEP much more reasonable.

Abstract
========

As Gentoo branches out to support non-Linux and non-GNU systems (such as Hurd,
the \*BSDs, or even the soon-to-be-open-sourced Solaris), the potential for an
"explosion" of possible keywords becomes rather large, since each new
userland/kernel/arch/whatever combination will require a new keyword.  This
GLEP proposes a simple extension to the current KEYWORDS variable that
encompasses the four parameters ARCH, USERLAND, KERNEL, and LIBC, but uses
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
need keywords that can specify all possible permutations of arch,
userland, kernel and libc.  A systematic nomenclature is needed.
Fortunately, the author is a Chemist.  *Grin*

.. _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
=============

Keyword Fragments
-----------------

Each keyword needs to specify, either explicitly or 
implicitly, the following parameters: 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.)

A fully-specified keyword would look like 
"ARCH-KERNEL-USERLAND-LIBC", so, for example,
"ppc-fbsd-gnu-glibc" would indicate a Gentoo system corresponding to
a ppc architecture running the FreeBSD kernel with a GNU userland and glibc 
as the system C library.

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

To keep this system manageable (and both to reduce typing and maintain
backwards compatibility), we need sensible defaults.  For backwards 
compatibility, the Gentoo default is a Linux kernel with a GNU userland
and glibc C library.  Thus, the current crop of ARCH-based keywords 
(x86, ppc, etcetera) require no change whatsoever.  For the \*BSD-based
systems the default USERLAND and LIBC would be those normally associated
with the corresponding KERNEL, so "x86-obsd" describes an x86 system
with an OpenBSD kernel, a BSD userland, and the OpenBSD C library.  If
either USERLAND or LIBC is specified, and thus not the default, then the
entire four-parameter string must be used.


Ebuild Keyword Database?
------------------------

One issue that has been raised is that adding a large number of keywords
to ebuilds is likely to become cumbersome over the long run.  (One could
imagine that for a simple `econf && emake && einstall` ebuild that the
list of keywords could grow to be the lengthiest part of the ebuild.)
Instead, perhaps it would make more sense to move each ebuild's keywords
out of the ebuild proper into a separate, perhaps online, database.
Nothing in this GLEP would be incompatible with such an approach, so
any further discussion will be deferred to a possible future GLEP on
that topic.


Profiles
--------

Along with an explosion of keywords comes a concomitant explosion of potential
profiles.  Just as in the current system, the profile name would be
"FLAVOR-KEYWORD-VERSION" (such as "default-s390-2004.1").  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, and the changes can be implemented
gradually over time.


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

Since the new keyword system is backwards-compatible with the current
system, "implementation" just means adding new keywords to ebuilds
as new systems are supported.


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

Backwards compatibility has already been addressed in some detail,
with the stated goal being a system that would leave all current
ebuilds working exactly as they are now.


Copyright
=========

This document has been placed in the public domain.
1	GLEP: 22
2	Title: New "keyword" system to incorporate various userlands/kernels/archs
3	Version: $Revision: 1.5 $
4	Last-Modified: $Date: 2004/07/20 18:15:17 $
5	Author: Grant Goodyear <g2boojum@gentoo.org>
6	Status: Informational
7	Type: Standards Track
8	Content-Type: text/x-rst
9	Created: 6-Mar-2004
10	Post-History: 6-Mar-2004, 5-Jun-2004, 20-Jul-2004
11
12	Status
13	======
14
15	After withdrawing this GLEP temporarily, a rewritten version has
16	now been resubmitted. This version no longer tries to prevent a
17	keyword explosion, but merely tries to make it manageable.
18
19	This version was approved on 14-Jun-2004, with the amendment that cascading
20	profiles should be used.
21
22	Credits
23	=======
24
25	This GLEP originated from the concerns that Daniel Robbins had with the
26	x86obsd keyword, and his desire to make the KEYWORDS variable more
27	"feature-rich". Drobbins' original idea was that we should allow compound
28	keywords such as gnu/x86, gnu/ppc, and macos/ppc (which would be explicit
29	versions of the more familiar x86, ppc, and macos keywords). Method noted
30	that userland/arch failed to capture the full range of possibilities (what
31	about a GNU userland on a BSD kernel+libc?), and the issue has languished due
32	to a lack of reasonable solutions. The original version of this GLEP
33	generated quite useful comments which hopefully have been addressed here to
34	make the GLEP much more reasonable.
35
36	Abstract
37	========
38
39	As Gentoo branches out to support non-Linux and non-GNU systems (such as Hurd,
40	the \*BSDs, or even the soon-to-be-open-sourced Solaris), the potential for an
41	"explosion" of possible keywords becomes rather large, since each new
42	userland/kernel/arch/whatever combination will require a new keyword. This
43	GLEP proposes a simple extension to the current KEYWORDS variable that
44	encompasses the four parameters ARCH, USERLAND, KERNEL, and LIBC, but uses
45	sensible defaults to keep the new system manageable.
46
47	Motivation
48	==========
49
50	Since the beginning, Gentoo Linux has been conceived as a "metadistribution"
51	that combines remarkable flexibility with sensible defaults and exceptional
52	maintainablilty. The goal of the Gentoo-Alt_ project has been to extend that
53	flexibility to include systems other than GNU/Linux. For example, the author
54	of this GLEP has been working to create a version_ of Gentoo that uses
55	OpenBSD_ as the underlying kernel, userland, and libc. OpenBSD_ supports a
56	variety of different architectures, so, in principle, we would need a new
57	openbsd-arch keyword for each supported architecture. In fact, the
58	situation is even more complicated, because the Gentoo-Alt_ project would
59	eventually like to support the option of "mixing-and-matching"
60	GNU/\*BSD/whatever userlands and libcs irrespective of the underlying kernel.
61	(Debian_, for example has a similar BSD project_, except that they have
62	replaced the BSD userland with a GNU userland.) The net result is that we
63	need keywords that can specify all possible permutations of arch,
64	userland, kernel and libc. A systematic nomenclature is needed.
65	Fortunately, the author is a Chemist. Grin
66
67	.. _Gentoo-Alt: http://www.gentoo.org/proj/en/gentoo-alt/index.xml
68	.. _OpenBSD: http://www.openbsd.com
69	.. _version: http://www.gentoo.org/proj/en/gentoo-alt/bsd/index.xml
70	.. _Debian: http://www.debian.org
71	.. _project: http://www.debian.org/ports/netbsd/
72
73	Specification
74	=============
75
76	Keyword Fragments
77	-----------------
78
79	Each keyword needs to specify, either explicitly or
80	implicitly, the following parameters: ARCH, USERLAND, LIBC, and KERNEL.
81
82	ARCH:
83	x86, amd64, cobalt, mips64, arm, hppa, ia64, ppc64, sparc
84	USERLAND:
85	gnu, bsd
86	LIBC:
87	glibc, openbsd, freebsd, netbsd, macosx
88	KERNEL:
89	linux, selinux, openbsd, freebsd, netbsd, macosx
90
91	(The above examples are not meant to be complete. Hurd, for example
92	is not included because I know very little about Hurd.)
93
94	A fully-specified keyword would look like
95	"ARCH-KERNEL-USERLAND-LIBC", so, for example,
96	"ppc-fbsd-gnu-glibc" would indicate a Gentoo system corresponding to
97	a ppc architecture running the FreeBSD kernel with a GNU userland and glibc
98	as the system C library.
99
100	Reasonable Defaults
101	-------------------
102
103	To keep this system manageable (and both to reduce typing and maintain
104	backwards compatibility), we need sensible defaults. For backwards
105	compatibility, the Gentoo default is a Linux kernel with a GNU userland
106	and glibc C library. Thus, the current crop of ARCH-based keywords
107	(x86, ppc, etcetera) require no change whatsoever. For the \*BSD-based
108	systems the default USERLAND and LIBC would be those normally associated
109	with the corresponding KERNEL, so "x86-obsd" describes an x86 system
110	with an OpenBSD kernel, a BSD userland, and the OpenBSD C library. If
111	either USERLAND or LIBC is specified, and thus not the default, then the
112	entire four-parameter string must be used.
113
114
115	Ebuild Keyword Database?
116	------------------------
117
118	One issue that has been raised is that adding a large number of keywords
119	to ebuilds is likely to become cumbersome over the long run. (One could
120	imagine that for a simple `econf && emake && einstall` ebuild that the
121	list of keywords could grow to be the lengthiest part of the ebuild.)
122	Instead, perhaps it would make more sense to move each ebuild's keywords
123	out of the ebuild proper into a separate, perhaps online, database.
124	Nothing in this GLEP would be incompatible with such an approach, so
125	any further discussion will be deferred to a possible future GLEP on
126	that topic.
127
128
129	Profiles
130	--------
131
132	Along with an explosion of keywords comes a concomitant explosion of potential
133	profiles. Just as in the current system, the profile name would be
134	"FLAVOR-KEYWORD-VERSION" (such as "default-s390-2004.1"). One drawback
135	to having a large number of profiles is that maintainance becomes a
136	significant problem. In fact, one could reasonably argue that the current
137	number of profiles is already too many to be easily maintained. One proposal
138	that has been raised to simplify matters is the idea of stackable, or
139	cascading, profiles, so that only differences between profiles would have to
140	be maintained.
141
142
143	Rationale
144	=========
145
146	The proposed new "keywording" system is far from elegant, which is
147	a substantial drawback. On the other hand, it is simple, it requires
148	relatively minor changes, and the changes can be implemented
149	gradually over time.
150
151
152	Implementation
153	==============
154
155	Since the new keyword system is backwards-compatible with the current
156	system, "implementation" just means adding new keywords to ebuilds
157	as new systems are supported.
158
159
160	Backwards Compatibility
161	=======================
162
163	Backwards compatibility has already been addressed in some detail,
164	with the stated goal being a system that would leave all current
165	ebuilds working exactly as they are now.
166
167
168	Copyright
169	=========
170
171	This document has been placed in the public domain.