#language en
~-[[DebianWiki/EditorGuide#translation|Translation(s)]]: none-~
----
= The Debian /usr Merge =

This page tracks Debian support for the merged /usr directories scheme, i.e. the
`/{bin,sbin,lib}/` directories becoming symbolic links to `/usr/{bin,sbin,lib}/`.

The DebianPkg:usrmerge package will convert the system it is installed on.

== Resources for developers ==

=== Status of the file move moratorium ===

In the [[https://lists.debian.org/debian-devel/2021/10/msg00190.html|second decision of the CTTE]] on merged-`/usr`, it also recommended not moving files between `/` and `/usr`. This recommendation is called the file move moratorium. It has since been [[https://lists.debian.org/debian-devel-announce/2023/10/msg00003.html|repealed and delegated]] to this page. We now encourage moves in a limited way.

/!\ Please suspend further moves temporarily. The effects of moves cause more problems than anticipated people are working to understand and solve them. Exceptions: Continue to perform moves that fix RC bugs (e.g. `dh_installsystemd` or `systemd.pc` issues) and DEP17P7 mitigations for `udev` rules.

Current moratorium rules (to be relaxed over time):
 * Do not move files from `/usr` to `/`:
   * We want `/bin`, `/lib` and `/sbin` to become empty. The direction of move is the wrong one.
   * When adding new packages or new functionality, add it to `/usr` if possible to avoid a later move.
 * `bash`, `base-files`, `coreutils`, `dash`, `glibc`, `util-linux` should not move files from `/` to `/usr`:
   * The upload of these packages needs to be synced.
   * `debootstrap` in `bookworm` and `bullseye` needs to be updated. That update is stuck in p-u still.
 * Packages containing diverted files or adding diversions should temporarily not be moved.
   * The proposed mitigation M18 does not work as is. We're in the process of fixing it. Until it is known to work, please wait. We shall have a solution within December 2023.
 * Transitively essential packages and `Priority: required` packages should not move files from `/` to `/usr` without extensive testing:
   * `debootstrap` currently is initially unmerged. Since we're still waiting for the p-u, `debootstrap` in `bookworm` and `bullseye` behaves differently from `debootstrap` in `trixie` and `unstable`, so these need to be tested separately. Also test `mmdebstrap` and `cdebootstrap`.
 * As an exception, you may move `systemd` units from `/lib` to `/usr/lib` in all packages (including essential and required):
   * `dh_installsystemd` generates maintainer scripts for `systemd` units below `/usr/lib` since version `13.11.6`. Please add `Build-Depends: debhelper (>= 13.11.6)`
   * Any `debian/*.service` files are now installed to `/usr/lib`. Your next upload will move them automatically.
   * Any units installed by an upstream build system to `systemd_system_unit_dir` as discovered using `pkgconf` continue to be installed to `/lib` for now. At a later time, this value shall be switched to `/usr/lib`. Therefore, it is best to not move them now. If you use this variable, ensure that you do not hard code `/lib/systemd/system` in `debian/*.install` files.
 * Upload restructuring changes to `experimental` first and wait three days:
   * Doing so gives the [[https://salsa.debian.org/helmutg/dumat|dumat service]] an opportunity to file a bug in case your change causes one of the problems from DEP17.
   * This only applies if the restructured package installed to `/bin`, `/lib` or `/sbin` in `bookworm` or `trixie`.
 * Do not update calls to `update-alternatives`:
   * Even if you move e.g. `/bin/more` to `/usr/bin/more`, do not change the location used in the `update-alternatives` invocation.
   * If you add new `alternatives`, install them to `/usr` if possible.

Build daemons are /usr-merged since [[https://lists.debian.org/debian-devel/2023/10/msg00024.html|2023-10-09]].

The debian-installer is /usr-merged [[https://salsa.debian.org/installer-team/debian-installer/-/commit/e90b4f783f725735d4f535d5134cb148a889c908|in git]] and the archive copy will be on the next upload.

=== How to move files from / to /usr? ===

For a lot of packages (about 500 source packages), the only affected files is systemd units. These will be automatically moved via changes in `debhelper` and `systemd.pc`. As of now `debhelper` will install units below `/usr` and `systemd.pc` will follow on 2023-11-30. A simple no-change upload or binNMU moves your units. If this applies to you, you may skip over most of this section, but still pay attention to the last paragraph.

Before moving files, please keep in mind that no `bookworm` suite (and that includes `bookworm-backports`) should move files to avoid breakage there. So when you look into moving files, the first question to ask is whether you want to support uploads of your package to `bookworm-backports`. If you do, your packaging should ensure that files continue to be distributed to / and /usr in the same way that they used to be in `bookworm`. Before `dh_installdeb`, you may insert `dh_movetousr` or `Build-Depends: dh-sequence-movetousr`. This helper shall become available in `bookworm-backports` and become a no-op there. That said, `dh_movetousr` is not meant to stay. It encourages maintaining code that becomes dead before too long. If you end up using it, be prepared to remove its use during the `forky` cycle.

If you have aliased systemd units that are manually installed, consider letting `dh_installsystemd` install them as it will also undo the move in `bookworm-backports`. In `3.0` source package, `debian/somepkge.service` may be a symbolic link pointing at location in the upstream source and will correctly be installed.

If you do not want to support uploads to `bookworm`-related suites such as `bookworm-backports`, manually moving the files may provide a simplification in packaging. Sometimes, it amounts to removing an existing `--prefix=/` and reverting to the default `--prefix=/usr`. Often times, a package's files have been split to / and /usr in a manual way and this can now be removed. When you do, please check all `debian/*.install`, `debian/*.links` and `debian/*.dirs` files and review that your package does not contain an empty `/bin`, `/lib` or `/sbin` directory.

Regardless of how you perform the move, please upload to `experimental`. A tool called dumat will analyze your package for some classes of known problems and shall get back to you within three days via the bug tracking system in the event of problems. [[https://subdivi.de/~helmut/dep17.html|DEP17]] provides a collection of known problem classes. Of these, dumat will check for P1, P2, P3 (mostly), P6, and P7. Problems P8, P9 and P10 are mostly relevant to packages close to the essential set. Affected packages have received instructions or patches. When in doubt, consider asking Helmut. Please check for the following problems before your upload:
 * P3: Does your package employ non-default diversions? If you unconditionally use `dpkg-divert`, dumat shall notice. It may fail to notice non-default diversions behind e.g. `debconf` questions. If those diversions interact with aliased locations, action is needed. Please get in touch with Helmut.
 * P4: Even when changing all aliased paths from / to /usr, you must not change the paths passed to `update-alternatives` invocations that already existed in `bookworm`. The current plan is to keep existing alternatives aliased as a legacy forever and add new alternatives without aliasing.
 * P5: If your package uses `dpkg-statoverride`, the paths may have to be updated. The old statoverride should be removed and the new one should be added.
 * P7: While `Multi-Arch: same` shared file loss is detected by dumat, you may mitigate it immediately. If affected, the [[https://subdivi.de/~helmut/dumat.yaml|dumat.yaml]] report shall contain a "risky m-a:same shared file". Chris Hofstaedtler wrote an [[https://salsa.debian.org/debian/libnjb/-/commit/9a473c94e0f5b697ed8adeec71b6c3587e1ed0d3|example to copy from]].

In general, we try to handle the more complex cases by sending patches.

After having successfully moved files from / to /usr, there is one more task. Any restructuring change to your package during the `trixie` cycle should be uploaded to `experimental` with a three day grace period to detect problems. A restructuring change is renaming a package (for instance adding a `t64` suffix for the 2038 transition) or moving a file from one binary package to a different binary package (from the same source package or a different source package).

== Transition priorities ==

This section is for people working on the transition beyond their own packages. We have a few areas of work.

=== Important packages and filesystem bootstrap ===

The target of this work is to get the aliasing symlinks into `base-files`. To get there we first have to move files in most important packages. Once only the exception are left, there will be a coordinated upload. This work is coordinated with Helmut Grohne and has high risk of fallout. Please refrain from uncoordinated uploads. The intention is to finish this by the end of March 2024.

=== udev ===

The moving of udev rules turns out to affect rather more packages. Therefore, `dh_installudev` and `udev.pc` should point below `/usr`, but doing so would cause M-A:same shared file loss (P7), which is a silent failure. For this reason, we now prioritize fixing these file loss cases. This work is [[https://mensuel.framapad.org/p/yk3d5mkbxj-a4jp|coordinated on a pad]] and mostly been prepared by folks in Cambridge and Chris Hofstaedler. After getting all of these changes into the archive, we can do a partial archive rebuild with updated `dh_installudev` and `udev.pc`, file bugs and eventually upload the changed defaults. The binNMUs can convert the remaining udev locations.

=== diversion mitigation ===

It turned out that the initial version of M18 did not work at all. We are developing a new one on `molly-guard`. Until this is validated, we should not touch further diversions as we cannot ensure to fix them in a timely manner. This work is driven by Helmut Grohne.

=== Move files to /usr in other packages ===

In effect, this is working on the long-tail of the transition and both serves reducing the size of the transition and in discovering unforeseen problems sooner rather than later. So just converting random packages and figuring out how that does not work is a useful thing to do at this time. This is not coordinated. Please report problems to Helmut Grohne. The intention is to finish this by the start of the transition freeze.

== FAQ ==

For more information, please refer to the
[[https://salsa.debian.org/md/usrmerge/raw/master/debian/README.Debian|usrmerge package FAQ]], another highly recommended read is <<mid(20181121140542.GA31273@espresso.pseudorandom.co.uk)>>

=== Is this about merging /usr/bin/ and /usr/sbin/? ===
No, there are no plans to do that.

=== Will switching to a merged /usr be mandatory? ===
In February 2021, the Technical Committee has resolved that Debian 'bookworm' should support only the merged-usr root filesystem layout, dropping support    for the non-merged-usr layout. (Bug:978636)

[[https://lists.debian.org/debian-devel-announce/2022/09/msg00001.html|The transition started on September 17th, 2022,]] by making init-system-helpers depend on usrmerge.

=== usrmerge is uninstallable, what do I do? ===
You might have run a script that installs a blocker metapackage. It needs to be removed manually, then apt will be able to upgrade the system:

 {{{
# apt install usrmerge
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Some packages could not be installed. This may mean that you have
requested an impossible situation or if you are using the unstable
distribution that some required packages have not yet been created
or been moved out of Incoming.
The following information may help to resolve the situation:

The following packages have unmet dependencies:
 dpkg-fsys-usrunmess : Conflicts: usrmerge
E: Error, pkgProblemResolver::Resolve generated breaks, this may be caused by held packages.
# dpkg --remove --force-all dpkg-fsys-usrunmess
dpkg: warning: overriding problem because --force enabled:
dpkg: warning: this is a protected package; it should not be removed
(Reading database ... 26987 files and directories currently installed.)
Removing dpkg-fsys-usrunmess (1.21.9) ...
# apt install usrmerge
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following NEW packages will be installed:
  usrmerge
0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded.
Need to get 13.0 kB of archives.
After this operation, 39.9 kB of additional disk space will be used.
Get:1 http://deb.debian.org/debian sid/main amd64 usrmerge all 31 [13.0 kB]
Fetched 13.0 kB in 0s (264 kB/s)
debconf: delaying package configuration, since apt-utils is not installed
Selecting previously unselected package usrmerge.
(Reading database ... 26988 files and directories currently installed.)
Preparing to unpack .../archives/usrmerge_31_all.deb ...
Unpacking usrmerge (31) ...
Setting up usrmerge (31) ...
The system has been successfully converted.
}}}


=== Adoption rate ===
DebianPkg:debootstrap has supported a `--merged-usr` option since version 1.0.83, and this has been the default since version 1.0.85.  The default was reverted in 1.0.87 and re-enabled in 1.0.102.  A `--no-merged-usr` option is also available.

See [[https://qa.debian.org/popcon-graph.php?packages=usrmerge&show_installed=on&from_date=2016-01-01&beenhere=1|popcon]] for upgrades of older systems.

== Developer Links ==

 * [[https://subdivi.de/~helmut/dumat.yaml]] Current dumat output, but note that you should automatically get bugs if your packages are affected
 * [[https://subdivi.de/~helmut/dep17.html|DEP17]]

User-tagged bugs:

 * [[https://udd.debian.org/bugs/?release=na&merged=ign&fnewerval=7&flastmodval=7&fusertag=only&fusertagtag=dep17m2&fusertaguser=helmutg%40debian.org&allbugs=1&chints=1&cseverity=1&ctags=1&caffected=1&clastupload=1&cautormtime=1&cbritney=1&sortby=id&sorto=asc&format=html#results|M2 Bugs]]
 * [[https://udd.debian.org/bugs/?release=na&merged=ign&fnewerval=7&flastmodval=7&fusertag=only&fusertagtag=dep17p7&fusertaguser=helmutg%40debian.org&allbugs=1&chints=1&cseverity=1&ctags=1&caffected=1&clastupload=1&cautormtime=1&cbritney=1&sortby=id&sorto=asc&format=html#results|P7 Bugs]]


== See also ==
 * [[http://www.freedesktop.org/wiki/Software/systemd/TheCaseForTheUsrMerge|The Case for /usr Merge.]]
 * [[https://fedoraproject.org/wiki/Features/UsrMove|Fedora: move all to /usr.]]
 * [[http://lists.busybox.net/pipermail/busybox/2010-December/074114.html|Understanding the bin, sbin, usr/bin, usr/sbin split.]]