User:MGorny/GLEP:EFH

From Gentoo Wiki
Jump to: navigation, search


GLEP xx"xx" is not a number.: 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:

  1. multilib library directories, defined by the profile,
  2. 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/.