New EAPI specification

This page explains the need for a new EAPI specification and the guidelines for it.

Current specification

The ebuild format is currently covered by the Package Manager Specification. This is an Exherbo-originated project that is maintained in Gentoo-Exherbo cooperation. Sadly, the current spec shows a number of issues.

Most notably, the current organization and wording often proves cumbersome for developers. It is easy to mis-understand some of the sections of the specification. Sometimes it is necessary to read multiple (non-cross-referenced) sections to understand the actual status.

The specification often misses rationale, historical or implementation notes. It also has been changed retroactively a few times without a proper behavior change note.

The specification offers only limited description of ebuild, profile and repository format. It lacks any details on multi-repository systems, installed package database (vardb), md5-cache. The Manifest files are specified only via reference to GLEP-44 which also doesn't cover most recent changes in Manifest format.

Guidelines for new specification

The new EAPI specification needs to follow the following guidelines:

1. it should be self-contained and provide coverage of all the most important interoperability aspects.
2. It should be focused on the newest EAPI. Previous EAPIs should be covered as differences from the newest EAPI and dedicated historical sections.
3. It should contain (as appropriately marked subsections) rationales, implementation notes, explanatory notes, possibly examples.
4. Format descriptions should be as simple as possible. Whenever appropriate, a BNF variant should be preferred over textual descriptions or regular expressions.