From ad0cb14bcbc3c535a4ad65cec3c5a9d1f172fb02 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Wed, 17 Jun 2026 13:11:30 +0200 Subject: [PATCH 1/4] lfsh: rewrite the description of directories for shared libraries MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This "rewrite" mostly rearranges the existing text and does some minor corrections, but does not introduce changes to the meaning of the spec. The old text was initially written to describe multiarch systems, and was later extended to describe multilib systems, by adding exceptions and clarifications in various places. As a result, it didn't describe either case very well. Users will primarily be interested in one layout or the other (whatever is used by their system), so the text becomes easier to read if the two layouts are described in separate subsections. > /usr/lib/ > Static, private vendor data that is compatible with all architectures This part was actually wrong. /usr/lib/ contains a lot of stuff that is architecture-specific. Also, the data is not "private" in any meaningful way. Shared libraries in particular are … shared. But plenty of other files are used by multiple consumers too. The descriptions for ~/.local/lib* and /usr/lib*/ are adjusted accordingly. The description for /usr/include/ is tweaked to say that it only applies to multiarch systems. The description of /usr/share is modified to follow the change that was done in 1f621b31e389c0d0519f1035a4e1e0fecf9617e4 in the other location. Co-authored-by: Jörg Behrmann --- specs/linux_file_system_hierarchy.md | 105 ++++++++++++++++----------- 1 file changed, 61 insertions(+), 44 deletions(-) diff --git a/specs/linux_file_system_hierarchy.md b/specs/linux_file_system_hierarchy.md index 8bea2db..848f445 100644 --- a/specs/linux_file_system_hierarchy.md +++ b/specs/linux_file_system_hierarchy.md @@ -231,7 +231,9 @@ or in a subdirectory. Using a subdirectory is recommended if the package installs multiple files. It is also necessary if multiple versions of the same headers shall be coinstallable. The subdirectory may be named after the package or project providing it. -Packages may place architecture-dependent header files and directories in a + +If the multiarch layout is used, +packages may place architecture-dependent header files and directories in a `/usr/include//` subdirectory, following the identifiers defined on the [Multiarch Architecture Specifiers (Tuples)](https://wiki.debian.org/Multiarch/Tuples) @@ -250,16 +252,14 @@ The corresponding library or libraries shall be placed in `$libdir`, see below. ### Libraries, system programs, and program assets This section describes the directories used to store shared libraries, -internal binaries or other programs that are not regularly invoked from a shell +internal binaries and other programs that are not regularly invoked from a shell (and thus should not be placed in the directories in `$PATH`), -and other static files that are part of program installations. +as well as other static files that are part of program installations. There are two main schemes for shared libraries. On "multiarch" systems, -multiple different architecture and ABI variants can be installed in parallel. -Each variant uses a hierarchy of files under a directory named using the -[Multiarch Architecture Specifiers (Tuples)](https://wiki.debian.org/Multiarch/Tuples) -list. +multiple different architecture and ABI variants can be installed in parallel, +using subdirectories for different architectures. On "multilib" systems, a simpler scheme is used that only supports 32-bit and 64-bit variants of the same architecture. @@ -270,40 +270,57 @@ Note that many locations described in this section are under shared ownership, with multiple different packages installing and consuming resources on equal footing without any obvious primary owner, -and are subject to specifications that ensure interoperability. - -#### `/usr/lib/` - -Static, private vendor data that is compatible with all architectures -(though not necessarily architecture-independent). -Note that this includes -internal binaries or other programs that are not regularly invoked from a shell. -Such binaries may be for any architecture supported by the system. - -In the multilib scheme, -32-bit libraries are placed directly in this directory. -In the multiarch scheme, -libraries should not be placed directly in this directory, -but in `$libdir` (see below), instead. +and are subject to further specifications to ensure interoperability. -#### `/usr/lib//` +#### Multiarch systems -Location for dynamic libraries, also called `$libdir`. +The "multiarch" layout is used primarily by the Debian family of distributions. +In this layout, shared libraries are stored in subdirectories of `/usr/lib/`, +with files for architecture `` in a hierarchy under the directory `/usr/lib//`. +This allows files for multiple architectures to be installed in parallel. The architecture identifier to use is defined on the [Multiarch Architecture Specifiers (Tuples)](https://wiki.debian.org/Multiarch/Tuples) list. -Those directories are used on multiarch systems. -On multilib systems, -`/usr/lib/` and `/usr/lib64/` are used instead, -and one of them is `$libdir`. +##### `/usr/lib/` + +The top-level `/usr/lib/` directory contains +architecture-independent files, +and internal binaries and other programs that are not regularly invoked from a shell +compiled for the the primary architecture of the system. + +##### `/usr/lib//` + +A hierarchy of directories containing shared libraries for architecture `` +and other architecture-dependent files. + +#### Multilib systems + +The "multilib" layout is used by most other distributions, +in particular all that are RPM-based. +This layout supports parallel installation of 32-bit and 64-bit variants of the same architecture. -This directory can be used for architecture-dependent package-specific data too. +##### `/usr/lib/` -The primary architecture of the system (`$libdir`) may be queried with: +This directory contains architecture-independent files, +internal binaries and other programs that are not regularly invoked from a shell, +and shared libraries for the 32-bit architecture. + +##### `/usr/lib64/` + +This directory contains shared libraries for the 64-bit architecture. +It can be used for architecture-dependent package-specific data too. + +#### The directory for shared libraries for the primary architecture + +The directory for shared libraries for the primary architecture is called `$libdir` +and may be queried with: systemd-path system-library-arch +On multiarch systems this will point to one of the `/usr/lib/` directories, +and either `/usr/lib/` or `/usr/lib64/` on multilib systems. + #### `/usr/libexec/` ⚠️ A secondary location for @@ -554,16 +571,15 @@ Care should be taken when placing architecture-dependent binaries in this place, which might be problematic if the home directory is shared between multiple hosts with different architectures. -### `~/.local/lib/` +### User's libraries, system programs, and program assets -Static, private vendor data that is compatible with all architectures. - -### `~/.local/lib//` - -Location for placing public dynamic libraries. -The architecture identifier to use is defined on -[Multiarch Architecture Specifiers (Tuples)](https://wiki.debian.org/Multiarch/Tuples) -list. +A private set of directories that mirrors +the directories described for the system in +[Libraries, system programs, and program assets](#libraries-system-programs-and-program-assets) +is defined for the user under `~/.local/`: +`~/.local/lib/` analoguous to `/usr/lib/`, +`~/.local/lib/` analoguous to `/usr/lib/`, +`~/.local/lib32/` and `~/.local/lib64/` analoguous to `/usr/lib32/` and `/usr/lib64/`. ### `~/.local/share/` @@ -669,13 +685,14 @@ specific types of files supplied by the vendor. | Directory | Purpose | |-------------------------------|---------| | `/usr/bin/` | Package executables that shall appear in the `$PATH` executable search path, compiled for any of the supported architectures compatible with the operating system. It is not recommended to place internal binaries or binaries that are not commonly invoked from the shell in this directory, such as daemon binaries. As this directory is shared with most other packages of the system, special care should be taken to pick unique names for files placed here, that are unlikely to clash with other package's files. | -| `/usr/lib//` | Public shared libraries of the package. As above, be careful with using too generic names, and pick unique names for your libraries to place here to avoid name clashes. | -| `/usr/lib/package/` | Private static vendor resources of the package, including private binaries and libraries, or any other kind of read-only vendor data. | -| `/usr/lib//package/` | Private other vendor resources of the package that are architecture-specific and cannot be shared between architectures. Note that this generally does not include private executables since binaries of a specific architecture may be freely invoked from any other supported system architecture. | +| `$libdir` and other directories described in [Libraries, system programs, and program assets](#libraries-system-programs-and-program-assets) | Public shared libraries of the package. As above, be careful with using too generic names, and pick unique names for your libraries to place here to avoid name clashes. | +| `/usr/lib//` | Program assets of the package, including shared libraries and plugins, +internal binaries and other programs that are not regularly invoked from a shell, and any other kind of read-only vendor data. | +| `~/.local/lib//` `~/.local/lib32/` `~/.local/lib64/` | Per-package program assets that are architecture-specific. Note that this generally does not include executables since binaries of a specific architecture may be freely invoked from any other supported system architecture. The specific directory to use should be selected based on the system layout as described in [Libraries, system programs, and program assets](#libraries-system-programs-and-program-assets).| -Additional static vendor files with shared ownership +Additional architecture-independent files may be installed in the `/usr/share/` hierarchy -to the locations defined by the various relevant specifications. +in the locations defined by the various relevant specifications. ### System package variable files locations From 194ea5136fcccdec73f55e6a1e425ddcf0b8dc70 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Wed, 17 Jun 2026 13:51:00 +0200 Subject: [PATCH 2/4] lfsh: fix descriptions of /lib and /lib64 symlinks We described those symlinks as legacy, but they are part of the ABI, and are not going away. The symlinks themselves are not legacy, the original directories were, but we are describing the symlinks not the old layout. In a multiarch layout, /lib64 does not point to $libdir. It points to a directory with loaders (or more likely symlinks to loaders) for different architectures. The premise of multiarch is parallel installation of multiple architectures, so pointing to a single architecture (either the primary architecture denoted by $libdir or any other) would be incompatible with that. --- specs/linux_file_system_hierarchy.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/specs/linux_file_system_hierarchy.md b/specs/linux_file_system_hierarchy.md index 848f445..ba4a39a 100644 --- a/specs/linux_file_system_hierarchy.md +++ b/specs/linux_file_system_hierarchy.md @@ -514,17 +514,18 @@ correctly find their binaries. ### `/lib/` -This compatibility symlink points to `/usr/lib/`, -ensuring that programs referencing this legacy path -correctly find their resources. +A symlink required for the correct execution of binaries specifying +the dynamic loader with a path starting with `/lib/`. +This symlink points to `/usr/lib/`. ### `/lib64/` -On some architecture ABIs, this compatibility symlink points to `$libdir`, -ensuring that binaries referencing this legacy path -correctly find their dynamic loader. -This symlink only exists on architectures whose ABI -places the dynamic loader in this path. +A symlink required for the correct execution of binaries specifying +the dynamic loader with a path starting with `/lib64/`. +The directory to which it points varies between multiarch and multilib installations +and even between different distributions using the multilib layout. +This symlink may not exist on architectures whose ABI +does not place the dynamic loader in this path. ### `/var/run/` From 6b6723c9705a6134f9988c5e2f4e5b66790fbbe3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Wed, 17 Jun 2026 13:22:28 +0200 Subject: [PATCH 3/4] lfsh: do not recommend multiarch over multilib This document inherited the recommandation for multiarch from its precedessor, the file-hierarchy man page. The multiarch layout _is_ elegant and flexible, but it hasn't been widely adopted, it is only used by the Debian family of distributions. At this point, it doesn't seem likely that it'll be adopted elsewhere. Wiring up installations in this more complex scheme if much more effort. The ability to support multiple architectures from a single installation was more useful when installations were shared. Nowadays, small, tailored images are used much more often. In particular, for immutable installations, the size of the image creates a pretty significant cost, so installations that are trimmed down to support just one architecture make sense. Users who want to run something on a different architecture will probably download a full image and spawn a VM. We shouldn't say that multiarch is the future, or recommend it for "new" installations. New distro efforts are not doing this and we shouldn't be trying to convince more gullible readers to try this. --- specs/linux_file_system_hierarchy.md | 1 - 1 file changed, 1 deletion(-) diff --git a/specs/linux_file_system_hierarchy.md b/specs/linux_file_system_hierarchy.md index ba4a39a..cb165c8 100644 --- a/specs/linux_file_system_hierarchy.md +++ b/specs/linux_file_system_hierarchy.md @@ -264,7 +264,6 @@ On "multilib" systems, a simpler scheme is used that only supports 32-bit and 64-bit variants of the same architecture. Both schemes are widely used, and distributions typically choose one or the other. -Multiarch is the recommended approach, especially for new systems. Note that many locations described in this section are under shared ownership, From c73cc087b7e2303462a992c1e1e474268e17481c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Behrmann?= Date: Wed, 17 Jun 2026 14:09:29 +0200 Subject: [PATCH 4/4] lfsh: describe the different versions of multilib rpm-based distros and Arch handle multilib differently with one shipping /usr/lib64 and the other shipping /usr/lib32 and therefore /usr/lib containing different widths among the two. This adds a split that describes both situations. --- specs/linux_file_system_hierarchy.md | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/specs/linux_file_system_hierarchy.md b/specs/linux_file_system_hierarchy.md index cb165c8..eb0d383 100644 --- a/specs/linux_file_system_hierarchy.md +++ b/specs/linux_file_system_hierarchy.md @@ -303,12 +303,23 @@ This layout supports parallel installation of 32-bit and 64-bit variants of the This directory contains architecture-independent files, internal binaries and other programs that are not regularly invoked from a shell, -and shared libraries for the 32-bit architecture. +and shared libraries for either the 32-bit or 64-bit architecture. -##### `/usr/lib64/` +##### `/usr/lib64/` or `/usr/lib32/` -This directory contains shared libraries for the 64-bit architecture. -It can be used for architecture-dependent package-specific data too. +This directory contains shared libraries for the other architecture. + +Either directory can be used for architecture-dependent package-specific data too. + +###### `/usr/lib64/` + +If `/usr/lib/` contains files for the 32-bit architecture, +`/usr/lib64/` may exist and contain files for the 64-bit architecture + +###### `/usr/lib32/` + +If `/usr/lib/` contains files for the 64-bit architecture, +`/usr/lib32/` may exist and contain files for the 32-bit architecture. #### The directory for shared libraries for the primary architecture