User:MGorny/GLEP:EFH
| GLEP : Ebuild Filesystem Hierarchy | |
|---|---|
| Type | Standards Track |
| Status | Draft |
| Author | Michał Górny <mgorny@gentoo.org> |
| Editor | |
| Replaces | |
| Replaced by | (none) |
| Requires | |
| Post History | |
Abstract
This GLEP specifies the install filesystem structure for ebuilds. In particular, it defines recommendations on where specific files are to be installed and can serve as a base for QA checks preventing ebuilds from accidentally installing into incorrect locations. It amends and extends Filesystem Hierarchy Standard as appropriate for Gentoo.
Motivation
While Filesystem Hierarchy Standard was often considered the base definition on how filesystem is used, Gentoo did not fully conform to it. Instead, a semi-normative filesystem policy was published in the Developer Manual Filesystem section, along with a few non-written amendments. This documentation is neither complete, fully correct or up-to-date.
Furthermore, a number of ebuilds over time had various bugs resulting in files being installed in uncommon and incorrect locations. This included stray files and directories in the root directory, home directories, temporary filesystems (i.e. discarded on reboot). It seems quite appropriate to employ additional QA checks that automatically warn developers whenever ebuilds do this.
However, employing proper QA checks requires precise definition on how various directories are to be used. This GLEP serves the purpose of providing a normative reference that can be used both as a source of clear policy on how ebuilds must and must not install files, and a recommendation on how ebuild authors should choose between multiple possible variants.
Specification
Initial requirements
Directory maintenance
Throughout the directories listed in this specification, specific types of maintenance are listed to describe who is allowed to install files and directories inside the specific directory. The meaning of different types is described in this section.
Ebuild-maintained means that ebuilds are allowed to install files and directories into the specific directory. If a specific directory is not listed as ebuild-maintained, then ebuilds must not install any files there. The only allowed exception is that ebuilds are allowed to create the specific top directory and install a keepfile in order to prevent it from being accidentally removed while pruning empty directories.
User-maintained means that the users (either sysadmin or appropriate users) are allowed to install files and directories into the specific directory. If a specific directory is not listed as user-maintained, then sysadmin should not attempt to install or alter the files inside it. Doing so may result in file collisions and alterations being lost on software installs, unless specified otherwise.
Software-maintained means that various background services and applications can modify the specific directory structure at runtime (i.e. without an explicit request made by user). For software to work correctly, those directories can not be mounted read-only during runtime.
System-maintained means that the contents of the directory may be altered by the operating system kernel. This is the case with special filesystems.
Use of symlinks
The directories listed in this specification can be implemented in terms of symlinks to other directories. The target directories can either be dedicated directories serving no other purpose in this specification, or other directories serving the same purpose.
Hierarchies and hierarchy dependencies
The directories listed in this specification are organized in hierarchies, starting with a well-defined top directory. All subdirectories in a specific hierarchy belong to the hierarchy, unless they form the top directory of another hierarchy.
Each of the hierarchies may depend on other hierarchies. The objects installed into hierarchy A may depend on objects from hierarchy B only if hierarchy A also depends on hierarchy B. In other words, it is disallowed to install objects that depend on objects from a sub-hierarchy into a parent hierarchy.
All hierarchy definitions in this specification are considered complete. Inside a particular hierarchy root, no other subdirectories can exist except for the directories noted and optionally directories specific to a particular operating system.
Directory list
Hierarchies
The following hierarchies (prefixes) are defined, including their dependencies and short descriptions:
| Top directory | Depends on | Description | Maintained by | |||
|---|---|---|---|---|---|---|
| Ebuild | User | Soft | Sys | |||
| / | top hierarchy, including boot-critical resources and system interfaces | (defined for specific directories) | ||||
| /usr | / | general application hierarchy, including most of the installed software | Yes | No | No | No |
| /usr/local | /usr, / | administrator-installed application hierarchy | No | Yes | No | No |
| /opt | /usr, / | binary-packaged application hierarchy | Yes | Yes | No | No |
Root directory hierarchy
The following directories are defined in the root directory hierarchy:
| Path | Description | Maintained by | |||
|---|---|---|---|---|---|
| Ebuild | User | Soft | Sys | ||
| /bin | application executables | Yes | No | No | No |
| /boot | bootloader data | Yes | Yes | No | No |
| /dev | system device tree | Yes | Yes | No | Yes |
| /etc | administrator-controlled system configuration files (config-protected) | Yes | Yes | No | No |
| /home | user home directories | No | Yes | Yes | No |
| /lib* | libraries and software packages | Yes | No | No | No |
| /lib/firmware | kernel firmware | Yes | Yes | No | No |
| /lib/modules | kernel modules | Yes | Yes | No | No |
| /media | mount points for removable media | No | Yes | Yes | No |
| /mnt | temporary mount points for filesystems | No | Yes | No | No |
| /opt | top directory for /opt hierarchy | ||||
| /proc | proc filesystem | No | No | No | Yes |
| /root | administrator's home directory | No | Yes | Yes | No |
| /run | run-time variable data (volatile) | No | No | Yes | No |
| /sbin | application executables for sysadmin use | Yes | No | No | No |
| /srv | data for services provided by the system | No | Yes | No | No |
| /sys | sys filesystem | No | No | No | Yes |
| /tmp | temporary directory (volatile) | No | Yes | Yes | No |
| /usr | top directory for /usr hierarchy | ||||
| /var | runtime-writable application data | Yes | Yes | Yes | No |
/usr directory hierarchy
The following directories are defined for the /usr hierarchy:
| Path | Description | Maintained by | |||
|---|---|---|---|---|---|
| Ebuild | User | Soft | Sys | ||
| /usr/bin | application executables | Yes | No | No | No |
| /usr/include | C/C++ header files | Yes | No | No | No |
| /usr/lib* | libraries and software packages | Yes | No | No | No |
| /usr/libexec | executables used internally by other programs | Yes | No | No | No |
| /usr/local | top directory of /usr/local hierarchy | ||||
| /usr/sbin | application executables for sysadmin use | Yes | No | No | No |
| /usr/share | read-only application data | Yes | No | No | No |
| /usr/src | source code | Yes | Yes | No | No |
/usr/local directory hierarchy
The following directories are defined for the /usr/local hierarchy:
| Path | Description | Maintained by | |||
|---|---|---|---|---|---|
| Ebuild | User | Soft | Sys | ||
| /usr/local/bin | application executables | No | Yes | No | No |
| /usr/local/include | C/C++ header files | No | Yes | No | No |
| /usr/local/lib* | libraries and software packages | No | Yes | No | No |
| /usr/local/libexec | executables used internally by other programs | No | Yes | No | No |
| /usr/local/sbin | application executables for sysadmin use | No | Yes | No | No |
| /usr/local/share | read-only application data | No | Yes | No | No |
| /usr/local/src | source code | No | Yes | No | No |
/opt directory hierarchy
The /opt directory hierarchy is used to provide additional binary software packages. Those packages are installed in subdirectories of /opt named by the vendor or software name. The directory structure could be summarized as:
| Path | Description | Maintained by | |||
|---|---|---|---|---|---|
| Ebuild | User | Soft | Sys | ||
| /opt/bin | application executable symlinks or shell script wrappers | Yes | Yes | No | No |
| /opt/<name> | software package named name | Yes | Yes | No | No |
| /opt/<vendor> | software packages coming from specific vendor | Yes | Yes | No | No |
Requirements for specific directory types
Application executable directories
Applies to: /bin, /sbin, /usr/bin, /usr/sbin, /usr/local/bin, /usr/local/sbin, /opt/bin
Application executable directories are intended for storing program executables, scripts and symlinks to them. All of executables stored in those directories should be intended for direct execution by users, and therefore those directories can be added to PATH.
Specific requirements:
- all files in application executable directories should be executable (+x permission),
- no subdirectories are allowed in application executable directories.
C/C++ header file directories
Applies to: /usr/include, /usr/local/include
C/C++ header file directories are intended for storing header files for C/C++ libraries. The directory structure of installed files should correspond to desired include paths, as those directories are searched for headers by compilers by default. Alternatively, subdirectories can be used to provide package-specific headers that are explicitly used through -I flags.
It is recommended to store only arch-independent headers in the top header directory structure. Arch-dependent headers should be stored in package subdirectories in library and package data directories. Alternatively, arch-specific subdirectory of header file directory can be used.
Specific requirements:
- all files should be valid C/C++ header files.
Library and software package directories
Applies to: /lib*, /usr/lib*, /usr/local/lib*
Those directories are considered separately as two kinds of directories:
- multilib library directories, defined by the profile,
- native software package lib directory.
Depending on the particular profile, lib can serve the purpose of both a multilib library directory (not necessarily the native one) or a symlink to it, and the native software package directory.
The multilib library directories are used for two purposes:
- storing shared and static C/C++ libraries,
- storing architecture-dependent package data (headers, modules…).
The subdirectories of the native software package lib directory can be used for two purposes:
- storing installed software packages,
- storing executables and scripts for internal use of installed software.
Specific requirements:
- all arch-dependent files must correspond to one of the following ABIs:
- the specific multilib ABI — if the lib* directory corresponds to one,
- the native ABI — if it is the lib directory,
- rules for specific subdirectories:
- pkgconfig subdirectory must contain only valid pkg-config .pc files and no subdirectories.
Internal use executable directories directories
Applies to: /usr/libexec, /usr/local/libexec
Those directories contain executables (and libraries) that are not intended to be called (linked) directly by the user. Instead, they are only used internally by the programs installing them.
Read-only application data directories
Applies to: /usr/share, /usr/local/share
Those directories contain application data that is not modified by the applications at runtime and that is not arch-dependent. Sometimes it is also used to contain internal use scripts (as long as they are not arch-dependent).
Specific requirements:
- no arch-dependent files can be installed in the directory,
- rules for specific subdirectories:
- pkgconfig subdirectory must contain only valid pkg-config .pc files and no subdirectories.
Rationale
Backwards Compatibility
Copyright
This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/.