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).
This did not really work out as we had hoped. Trying to do this upstream
introduced several problems that probably makes it better suited as a
downstream patch after all. At any rate, it is not releaseable in the
current state, so we at least need to revert this before the release.
* by adjusting the path to binaries, but not do the same thing to the
search path we end up with inconsistent man-pages. Adjusting the search
path too would be quite messy, and it is not at all obvious that this is
worth the effort, but at any rate it would have to be done before we
could ship this.
* this means that distributed man-pages does not make sense as they depend
on config options, and for better or worse we are still distributing
man pages, so that is something that definitely needs sorting out before
we could ship with this patch.
* we have long held that split-usr is only minimally supported in order
to boot, and something we hope will eventually go away. So before we start
adding even more magic/effort in order to make this work nicely, we should
probably question if it makes sense at all.
In particular, use /lib/systemd instead of /usr/lib/systemd in distributions
like Debian which still have not adopted a /usr merge setup.
Use XML entities from man/custom-entities.ent to replace configured paths while
doing XSLT processing of the original XML files. There was precedent of some
files (such as systemd.generator.xml) which were already using this approach.
This addresses most of the (manual) fixes from this patch:
http://anonscm.debian.org/cgit/pkg-systemd/systemd.git/tree/debian/patches/Fix-paths-in-man-pages.patch?h=experimental-220
The idea of using generic XML entities was presented here:
http://lists.freedesktop.org/archives/systemd-devel/2015-May/032240.html
This patch solves almost all the issues, with the exception of:
- Path to /bin/mount and /bin/umount.
- Generic statements about preference of /lib over /etc.
These will be handled separately by follow up patches.
Tested:
- With default configure settings, ran "make install" to two separate
directories and compared the output to confirm they matched exactly.
- Used a set of configure flags including $CONFFLAGS from Debian:
http://anonscm.debian.org/cgit/pkg-systemd/systemd.git/tree/debian/rules
Installed the tree and confirmed the paths use /lib/systemd instead of
/usr/lib/systemd and that no other unexpected differences exist.
- Confirmed that `make distcheck` still passes.
The original idea of systemd.pc was to contain arch-independent system
and systemd information. By exposing libdir as part of the fields (added
in eb39a6239c), it started to carry
arch-dependent data, thus breaking multilib systems. It was then moved
to pkgconfiglibdir to deal with this (in
aec432c613), but actually the right
approach is to simply not include libdir in the .pc file at all.
THis patch hence more or less reverts both commits again, and moves the
.pc file back into pkgconfigdatadir.
As alternative for querying the systems primary libdir there's now
"systemd-path system-library-arch", hence a more correct alternative
exists for querying this variable from the .pc file.
