The Funtoo Linux project has transitioned to "Hobby Mode" and this wiki is now read-only.
Difference between revisions of "New EAPI specification"
(explain what's wrong with PMS) |
(some guidelines for new spec) |
||
Line 10: | Line 10: | ||
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 [https://wiki.gentoo.org/wiki/GLEP:44 GLEP-44] which also doesn't cover most recent changes in Manifest format. | 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 [https://wiki.gentoo.org/wiki/GLEP:44 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: | |||
# it should be self-contained and provide coverage of all the most important interoperability aspects. | |||
# It should be focused on the newest EAPI. Previous EAPIs should be covered as differences from the newest EAPI and dedicated historical sections. | |||
# It should contain (as appropriately marked subsections) rationales, implementation notes, explanatory notes, possibly examples. | |||
# Format descriptions should be as simple as possible. Whenever appropriate, a BNF variant should be preferred over textual descriptions or regular expressions. |
Latest revision as of 11:52, January 18, 2015
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:
- it should be self-contained and provide coverage of all the most important interoperability aspects.
- It should be focused on the newest EAPI. Previous EAPIs should be covered as differences from the newest EAPI and dedicated historical sections.
- It should contain (as appropriately marked subsections) rationales, implementation notes, explanatory notes, possibly examples.
- Format descriptions should be as simple as possible. Whenever appropriate, a BNF variant should be preferred over textual descriptions or regular expressions.