initial import of per-package eclass glep

1 files changed, 88 insertions, 0 deletions

diff --git a/users/antarus/projects/gleps/glep-XX.txt b/users/antarus/projects/gleps/glep-XX.txt
new file mode 100644
index 0000000000..c9a1810961
--- /dev/null
+++ b/users/antarus/projects/gleps/glep-XX.txt
@@ -0,0 +1,88 @@
+GLEP: 62
+Title: Per package eclasses
+Version: 
+Last-Modified:
+Author:	Matti Bickel <mabi@gentoo.org>
+Status: Draft
+Type: Standards Track
+Content-Type: text/x-rst
+Created:
+Post-History:
+
+Abstract
+========
+
+This document proposes a new kind of eclasses, which are specific to a certain
+package (hence "per-package eclasses"). It explains the current need for
+package specific eclasses, the proposed solution and a possible migration path.
+
+What is proposed is, in short, creation of eclasses in package directories for
+use by the ebuilds of the package in the same directory. Per-package eclasses
+can be thought of (broadly speaking) as normal eclasses used only by one
+package.
+
+Motivation and Rationale
+========================
+
+Gentoo currently provides 211 eclasses as of 14-08-2010, 36 of which are marked
+"@DEAD" and are scheduled for removal. At least three non-dead eclasses are
+specific to one package (mysql, php5_2-sapi and nvidia-drivers). The sheer
+number of eclasses makes it hard for old and new developers to quickly find the
+eclass they are looking for. Providing overlays and working on a single package
+also is not as easy as it should be. Last but not least, eclasses provided in
+the package directory could be part of the package's Manifest file, providing
+part of the eclass signing the Gentoo tree still lacks.
+
+Placing the package specific eclasses into the package directories themselves
+solves all of the problems mentioned (at least partly). It will reduce the
+clutter in the current eclass directory, provide a single directory to
+understand an ebuild and provides security benefits by including the eclasses in
+the Manifest file.
+
+Specification
+=============
+
+The per-package eclasses are specified to be placed directly under the package
+directory (as described in [1]_). The eclass may have any name permissible
+for other eclasses (specifically, must end with ".eclass").
+
+A per-package eclass is included in an ebuild by a new function ``pkg-inherit``
+called in the global scope of the ebuild.
+
+The ``pkg-inherit`` function must be given zero or more arguments. If no
+argument is given, the function shall behave like it was called with the
+argument ``default``. It is specified to search the package directory of the
+calling ebuild (but no other directories) for eclasses with the names of the
+arguments and the suffix ".eclass". If such files exist, they must be sourced by
+the function.
+
+If not specified otherwise below, the package manager shall treat the
+per-package eclass as a normal eclass in any other respect.
+
+It is made a requirement that per-package eclasses can not modify the ``EAPI``
+variable. It is assumed ``EAPI``, if it set, is set before calling pkg-inherit.
+
+Backwards Compatibility
+=======================
+
+The current Package Manager Specification requires package managers to ignore
+anything in the top-level package directory that does not have a filename ending
+in ".ebuild" ([1]_). Thus package manager which do not implement the per-package
+eclass feature can ignore them. They, however, will fail to execute ebuilds
+making use of the new ``pkg-inherit`` function. It is therefore required this
+feature be made part of a new EAPI.
+
+Additionally, tools that regenerate the Manifest file should be aware of
+per-package eclasses. However, this is only of concern to developers
+regenerating Manifests in a specific package directory. It is assumed that
+whoever changes functionality in a package also uses tools capable of supporting
+features used in the package's ebuilds.
+
+Copyright
+=========
+
+This document has been placed in the public domain.
+
+.. [1] http://distfiles.gentoo.org/distfiles/pms-3.pdf, Section 4.3
+
+