> In particular, the service launcher (launchd, mentioned in the article), and various other system level things (including logs, also mentioned in the article), have so little official documentation as to be laughable.
God launchd's documentation is so woefully incomplete it's soul-crushing, even more so as they deprecate "legacy" subcommand (which are "community documented" as various souls tried to understand how to make them work) and the documentation for the "replacements" is even worse. I'm not a sysadmin, I don't really care for launchd, but every time I want to set up a cron I waste an hour trying to coerce it into doing something useful before just falling back onto crontab.
Not to mention the… idiosyncratic command lines which makes even documented tools a chore to use fucking `lipo`:
the various options are mostly exclusive which is documented but weird as fuck, but then say you want to check if a given binary contains a specific arch
-verify_arch arch_type …
Take one input file and verify the specified arch_types are
present in the file. If so then exit with a status of 0
else exit with a status of 1.
You'd expect `lipo -verify_arch x86_64 <file>`, but no, since it can take multiple arch rather than repeat -verify_arch you must put it at the tail: `lipo <file> -verify_arch x86_64`, if you don't you get a screenful of garbage telling you that you gave an incorrect architecture flag, which architecture flags are valid and re-printing the synopsys.
> launchd's documentation is so woefully incomplete it's soul-crushing
Interestingly, systemd (which, AFAIK, is influenced in large parts by launchd) goes the exact opposite way and has amazingly complete and well-structured documentation.
I've found that to be true, as well. Say what you will about systemd, but they've really done a good job documenting it. There are also useful blog posts from some of the developers delving into various topics. Nearly every question I've had about systemd (and I've had a lot, as our products interact with the init system tons) has been answered either by the docs or by a blog post by one of the systemd developers.
e.g. I recently dug into how to build an inetd style (called "socket activation" in systemd) service. I found pretty good core docs, and a very good blog post with real and useful examples.
Learning my way around systemd has just been a good experience, all around. I have my complaints, but doc quality isn't among them.
It's a big project, but having it all come from the same folks does lead to a consistency across sub-systems that is rarely seen in the Linux world.
God launchd's documentation is so woefully incomplete it's soul-crushing, even more so as they deprecate "legacy" subcommand (which are "community documented" as various souls tried to understand how to make them work) and the documentation for the "replacements" is even worse. I'm not a sysadmin, I don't really care for launchd, but every time I want to set up a cron I waste an hour trying to coerce it into doing something useful before just falling back onto crontab.
Not to mention the… idiosyncratic command lines which makes even documented tools a chore to use fucking `lipo`:
the various options are mostly exclusive which is documented but weird as fuck, but then say you want to check if a given binary contains a specific arch You'd expect `lipo -verify_arch x86_64 <file>`, but no, since it can take multiple arch rather than repeat -verify_arch you must put it at the tail: `lipo <file> -verify_arch x86_64`, if you don't you get a screenful of garbage telling you that you gave an incorrect architecture flag, which architecture flags are valid and re-printing the synopsys.