Documentation of /usr/src directory layout

From: Mitchell Horne <>
Date: Wed, 26 Oct 2022 16:07:05 UTC

Currently, hier(7) contains detailed but outdated [1] documentation of 
the directory structure under /usr/src. The src tree's file 
duplicates much of this information by maintaining a distinctly 
incomplete table.

I propose that we reduce the maintenance overhead by keeping one of 
these lists as the source of truth. is the more natural option 
here: being located at the root of the src tree it is more discoverable 
(especially for those new to the src tree), and the raw markdown text is 
much more human-readable than mdoc. Of course, the added benefit is that is presented front-and-center when browsing the git repository 
on GitHub, GitLab, etc. See it on my fork [2].

The list of /usr/src subdirectories will be removed from hier(7) and 
replaced with a sentence informing the reader they can consult 
for the details.

I have retained and improved the list of directories under sys/ from 
hier(7), but to avoid polluting the top-level source roadmap I have 
added a secondary sys/ which documents the layout of the kernel 

I do not expect these changes to be contentious, but I'd like to cast a 
wider net for review. Productive feedback is welcome by email or 
directly in the Phabricator reviews:

Also, this information is duplicated in at least one more place: the 
Developer's Handbook [3]. I intend to address this too after the current 
series of changes is complete. Most likely, this will be done by 
replacing the list with a link to the file in cgit.