The contents of file-hierarchy.7 have been copied over to the new page in
uapi-docs, and are already going stale here, since a bunch of additions and
improvements has been made there. OTOH, a commit was made here, but not there.
https://github.com/uapi-group/specifications/pull/172 updates the other doc.
OTOH, a reader should also read MOUNT_REQUIREMENTS if they care about what
systemd cares about. Thus, replace most of the text in our man page by a
reference to those two pages. In case we later want to list some disagreements
or differences wrt. LFSH, we can always add a paragraph or two here,
but having two documents with almost the same content is not going to work.
As discussed in this thread:
https://github.com/redhat-performance/tuned/issues/798#issuecomment-3197697654
/usr/share/factory/ is not intended to be read from by programs,
but the wording in the FHS can be misread to think that programs
should be using /usr/share/factory/ as the vendor supplied configuration
directory rather than something like /usr/lib/foo/ or /usr/share/foo/.
This commit points developers to the UAPI configuration spec for how to
make their programs hermetic /usr/ compatible.
Signed-off-by: Ryan Brue <ryanbrue.dev@gmail.com>
Today it seems this is mostly used by mail and printer servers, and it's
not clear to me at all what the property is that makes
/var/spool/<package> the better place for the relevant data than
/var/lib/<package>.
Hence, in the interest of shortening the spec, let's not mention the dir
anymore. In particular as the dir really isn't used by us much, for
example we do not have a counterpart for RuntimeDirectory=,
StateDirectory=, … that would cover the spool.
Since most systems these days we care about probably come *without* a
printer or mail server, let's maybe no mention this in the man page that
is supposed to discuss the rough skeleton how things are set up. After
all, people are supposed to exend the skeleton with their stuff, and
this sounds more like a case for an extension of the skeleton instead of
being considered part of the skeleton itself.
The man page is supposed to provide a "generalized, though minimal and
modernized subset" (as per introductory pargapraghs), from a systemd
perspective. But the thing is that /usr/include/ really doesn't matter
to us. It's a development thing, and slightly weird (because it arguably
would be better places in /usr/share/include/ or so). It's not going to
be there on 95% of deployed systems, and we really don't want people to
bother with it on such systems.
We only define the skeleton of directories in this document, and it's
expected that people extend it, and I think this really should be one of
those dirs that is an extension of our skeleton, but not part of the
skeleton, if that makes any sense.
Somebody wrapped the text, but whitespace is preserved in <programlisting>, so
the output was mangled. It also doesn't make sense to run systemd-path as root
(as indicated by '#'), so drop that. Also, this chunk should be a separate
paragraph.
The XDG base dir spec adopted ~/.local/state/ as a thing a while back,
and we updated our docs in b4d6bc63e6, but
forgot to to update the table at the bottom to fully reflect the update.
Fix that.
This file doesn't document features of systemd, but is more a of a
general description that generalizes/modernizes FHS. As such, the items
listed in it weren't "added" in systemd versions, they simply reflect
general concepts independent of any specific systemd version. hence
let's drop this misleading and confusing version info.
Or in other words, the man page currently claims under "/usr/": "Added
in version 215." – Which of course is rubbish, the directory existed
since time began.
This also rebreaks all paragaphs this touches.
No content changes.
As I noticed a lot of missing information when trying to implement checking
for missing info. I reimplemented the version information script to be more
robust, and here is the result.
Follow up to ec07c3c80b
This tries to add information about when each option was added. It goes
back to version 183.
The version info is included from a separate file to allow generating it,
which would allow more control on the formatting of the final output.
* Avoid traling slash as most links are defined without.
* Always use https:// protocol and www. subdomain
Allows for easier tree-wide linkvalidation
for our migration to systemd.io.
file-hierarchy does not mention anything about the expected mountpoint
for cgroups. This may lead some software to believe it will need to
search for it (e.g. by scanning mountinfo) rather than just looking in
the canonical location.
Document the canonical mountpoint as /sys/fs/cgroup. Also provide
information on the non-default configurations, but
make it clear that in such configurations if cgroup2 is mounted (hybrid
mode) it won't have resource controllers attached. This will help
software know if it should fall back to /sys/fs/cgroup/unified or just
ignore that case.
We have three somewhat separate ideas: what the directory is for, what $TMPDIR is for, and security considerations.
Let's use paragraphs.
Also, conjunctions in titles aren't capitalized usually.
In table titles, capitalize only the first word (they are rather long and
it is easier to read when it looks like a normal sentence).
Adjust some phrases to make them clearer when reported as unclear in #17177.
The "include" files had type "book" for some raeason. I don't think this
is meaningful. Let's just use the same everywhere.
$ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
No need to waste space, and uniformity is good.
$ perl -i -0pe 's|\n+<!--\s*SPDX-License-Identifier: LGPL-2.1..\s*-->|\n<!-- SPDX-License-Identifier: LGPL-2.1+ -->|gms' man/*.xml
Docbook styles required those to be present, even though the templates that we
use did not show those names anywhere. But something changed semi-recently (I
would suspect docbook templates, but there was only a minor version bump in
recent years, and the changelog does not suggest anything related), and builds
now work without those entries. Let's drop this dead weight.
Tested with F26-F29, debian unstable.
$ perl -i -0pe 's/\s*<authorgroup>.*<.authorgroup>//gms' man/*xml
These lines are generally out-of-date, incomplete and unnecessary. With
SPDX and git repository much more accurate and fine grained information
about licensing and authorship is available, hence let's drop the
per-file copyright notice. Of course, removing copyright lines of others
is problematic, hence this commit only removes my own lines and leaves
all others untouched. It might be nicer if sooner or later those could
go away too, making git the only and accurate source of authorship
information.
This part of the copyright blurb stems from the GPL use recommendations:
https://www.gnu.org/licenses/gpl-howto.en.html
The concept appears to originate in times where version control was per
file, instead of per tree, and was a way to glue the files together.
Ultimately, we nowadays don't live in that world anymore, and this
information is entirely useless anyway, as people are very welcome to
copy these files into any projects they like, and they shouldn't have to
change bits that are part of our copyright header for that.
hence, let's just get rid of this old cruft, and shorten our codebase a
bit.
Our CODING_STYLE document suggests to suffix all paths referring to dirs
rather than regular files with a "/" in our docs and log messages.
Update file-hierarchy(7) to do just that.
No other changes.
We document this further down in the text, but let's also list this
early on, where we mention the FHS as major influence too, so that it is
clear we incorporate all that thinking.
Double newlines (i.e. one empty lines) are great to structure code. But
let's avoid triple newlines (i.e. two empty lines), quadruple newlines,
quintuple newlines, …, that's just spurious whitespace.
It's an easy way to drop 121 lines of code, and keeps the coding style
of our sources a bit tigther.
Files which are installed as-is (any .service and other unit files, .conf
files, .policy files, etc), are left as is. My assumption is that SPDX
identifiers are not yet that well known, so it's better to retain the
extended header to avoid any doubt.
I also kept any copyright lines. We can probably remove them, but it'd nice to
obtain explicit acks from all involved authors before doing that.
Follow-up to @poettering’s comments in #7723:
- Slightly expand on the difference between using tmpfiles.d and service
directives
- Mention CacheDirectory=
- Mention LogsDirectory=
- Abbreviate and unify some later descriptions
ConfigDirectory= is not mentioned, since it does not support the
functionality mentioned in the manpage which tmpfiles.d provides:
copying or symlinking default configuration from /usr/share/factory. And
the user package variable file locations don’t mention the directives
because in user units the service can always create the directories
itself (whereas in system units lesser-privileged services lack
permission to create them).
