From: Lady Date: Thu, 2 May 2024 02:14:51 +0000 (-0400) Subject: Update documentation regarding (non‐)Posix needs X-Git-Tag: 0.8.1~4 X-Git-Url: https://git.ladys.computer/Shushe/commitdiff_plain/f6a3b3d4de9b99892c8d9179061546b52a46e471?hp=6773582e45aab385c96638fe9e90d811132a1005 Update documentation regarding (non‐)Posix needs --- diff --git a/GNUmakefile b/GNUmakefile index 2cb311f..7880926 100644 --- a/GNUmakefile +++ b/GNUmakefile @@ -29,9 +29,9 @@ override define makefileinfo ║│ • git (optional) │║ ║│ • ln │║ ║│ • ls │║ -║│ • mkdir (requires support for `-p´) │║ +║│ • mkdir │║ ║│ • mv │║ -║│ • od (requires support for `-t x1´) │║ +║│ • od │║ ║│ • pax (only when generating archives) │║ ║│ • printf │║ ║│ • rm │║ @@ -40,9 +40,9 @@ override define makefileinfo ║│ • stat │║ ║│ • test │║ ║│ • touch │║ -║│ • tr (requires support for `-d´) │║ -║│ • uuencode (requires support for `-m´ and `-r´) │║ -║│ • uudecode (requires support for `-m´ and `-r´) │║ +║│ • tr │║ +║│ • uuencode │║ +║│ • uudecode │║ ║│ • xargs (requires support for `-0´) │║ ║│ • xmlcatalog (provided by libxml2) │║ ║│ • xmllint (provided by libxml2) │║ diff --git a/README.markdown b/README.markdown index 9523a8a..bf353e0 100644 --- a/README.markdown +++ b/README.markdown @@ -23,26 +23,10 @@ It makes things easier by :⁠— It aims to do this with zero dependencies beyond the programs already installed on your computer†. -† The only non‐Posix programs‡ required (other than G·N·U Make itself, - and optionally Git) are those provided by `libxml2` and `libxslt`. -On most operating systems, these libraries come pre·installed, but on - Linux machines the commandline utilities are often packaged - separately (as **`libxml2-utils`** and **`xsltproc`**), which may - still need to be installed. -Additionally, not all Linux distributions bundle all necessary Posix - programs; on Debian (for example) you may need to separately install - **`sharutils`** for `uudecode` and `uuencode` and **`pax`** for - archiving. - -‡ This make·file also currently depends on non‐Posix `stat` but - attempts to handle both the G·N·U and B·S·D variants. -It expects `xargs` to accept a `-0` option, which, while widely - supported, is not a part of the Posix standard. - -**Note:** -⛩️📰 书社 requires functionality present in G·N·U Make 3.81 or later, - and will not work in previous versions, or with other implementations - of Make. +† Assuming an operating system with a fairly featureful, and + Posix‐compliant, development setup (e·g, macOS). +In fact, on Linux you will probably need to install a few programs: + `libxml2-utils`, `xsltproc`, `sharutils`, and `pax`. ## Nomenclature @@ -64,6 +48,99 @@ The name 书社 was chosen to play on this pun, as In Ascii environments, ⛩️📰 书社 should be written `Shushe`, following the pinyin transliteration. +## Prerequisites + +In most cases, ⛩️📰 书社 aims to require only functionality which is + present in all Posix‐compliant operating systems. +There are a few exceptions. +Details on particular programs are given below; if a program is not + listed, it is assumed that any Posix‐compliant implementation will + work. + +### `date` + +This is a Posix utility, but ⛩️📰 书社 currently depends on + unspecified behaviour. +When the G·N·U version of `stat` is being used, then the G·N·U version + of `date` is also expected. + +### `file` + +This is a Posix utility, but ⛩️📰 书社 currently depends on + unspecified behaviour. +It requires support for the following additional options :⁠— + +- **`-C`**, when supplied with `-m`, must be useable to compile a + `.mgc` magicfile for use with future invocations of `file`. + +- **`--files-from`** must be useable to provide a file that `file` + should read file·names from, and `-` must be useable in this + context to specify the standard input. + +- **`--mime-type`** must cause `file` to print the internet media type + of the file with no charset parameter. + +- **`--separator`** must be useable to set the separator that `file` + uses to separate file names from types. + +These options are implemented by the + [Fine Free File Command](https://darwinsys.com/file/), which is used + by most operating systems. + +### `git` + +This is not a Posix utility. +Usage of `git` is optional, but recommended (and activated by default). +To disable it, set `GIT=`. + +### `make` + +This is a Posix utility, but ⛩️📰 书社 currently depends on + unspecified behaviour. +⛩️📰 书社 requires specifically the G·N·U version of `make`, and + depends on functionality present in version 3.81 or later. +It is not expected to work in previous versions, or with other + implementations of Make. + +### `pax` + +This is a Posix utility, but not included in the Linux Standard Base or + installed by default in many distributions. +Only `ustar` format support is required. + +### `stat` + +This is not a Posix utility, and nor is it particularly portable. +To get around incompatibilities, ⛩️📰 书社 attempts to recognize G·N·U + `stat` by searching for the string `GNU` when invoked with the + `--version` option, and falls back to B·S·D behaviour otherwise. + +### `uudecode` and `uuencode` + +These are Posix utilities, but not included in the Linux Standard Base + or installed by default in many distributions. +The G·N·U [Sharutils](https://www.gnu.org/software/sharutils/) package + can be installed to access them. + +### `xargs` + +This is a Posix utility, but ⛩️📰 书社 currently depends on + unspecified behaviour. +It requires support for the `-0` flag, which must disable the special + quote and whitespace handling of `xargs` in favour of null‐terminated + strings. + +### `xmlcatalog` and `xmllint` + +These are not a Posix utilities. +They is a part of `libxml2`, but may need to be installed separately + (e·g by the name `libxml2-utils`). + +### `xsltproc` + +This is not a Posix utility. +It is a part of `libxslt`, but may need to be installed separately. + ## Basic Usage Place source files in `sources/` and run `make install` to compile