Mercurial > vanilla
changeset 821:c5cbe07af6a9
vanilla: update manual.md
author | David Demelier <markand@malikania.fr> |
---|---|
date | Wed, 21 Aug 2019 20:45:00 +0200 |
parents | 1b1191e628a6 |
children | a73b34fe66ec |
files | Docs/manual.md |
diffstat | 1 files changed, 105 insertions(+), 42 deletions(-) [+] |
line wrap: on
line diff
--- a/Docs/manual.md Wed Aug 21 16:40:27 2019 +0200 +++ b/Docs/manual.md Wed Aug 21 20:45:00 2019 +0200 @@ -139,21 +139,17 @@ Options ======= -... - -Example with network/wget: - - # cd network/wget - # SSL=openssl NLS=no vpk build +If the package offer build options, edit the *PKGOPTIONS* variable and always +add default values that match upstream if possible. Boolean options must always +be considered as *yes* or *no*. If an option requires a list, use a space +separated list of values. -Add the desired options in *PKGOPTIONS* variable and don't forget to set default -values. +Example: -Example with NLS - - PKGOPTIONS="NLS" + PKGOPTIONS="NLS DRIVERS" : ${NLS:=yes} + : ${DRIVERS:=amd intel} if [ "$NLS" = "yes" ]; then PKGDEPENDS="core/gettext $PKGDEPENDS" @@ -180,13 +176,14 @@ The package must ensure appropriate directories for installing files. This includes: -- /etc/rc.d for service files -- /lib/pkgconfig: for .pc files -- /lib/cmake: for CMake config files -- /lib: for libraries (no lib64 suffix) -- /share/locale: for NLS files -- /share/man/man{1,2,3,4,5,6,7,8}: for man pages (in uncompressed form) -- /share/doc/PKGNAME (exact directory, no version) +- /etc/rc.d: for service files, +- /lib/pkgconfig: for .pc files, +- /lib/cmake: for CMake config files, +- /lib: for libraries (no lib64 suffix), +- /share/PKGNAME: data directory (if applicable), +- /share/locale: for NLS files, +- /share/man/man{1,2,3,4,5,6,7,8}: for man pages (in uncompressed form), +- /share/doc/PKGNAME (exact directory, no version): arbitrary documentation. Keep neutral ============ @@ -195,64 +192,130 @@ possible. Only minor tweaks are allowed including: - adjusting pid/uid/gid in a default configuration file for easier deployment - (but not on the original file example) -- disabling static libraries -- making sure paths are consolidated -- making sure system libraries are used rather than in-source bundles + (but not on the original file example), +- making sure paths are consolidated, +- making sure system libraries are used rather than in-source bundles, +- replacing PAM files (see below). + +PAM files +========= + +The PAM system is an flexible and well designed authentication tool, it has a +large number of modules and configuration settings. This complexity leads to +inconsistent upstream PAM files that are not always compatible with the default +Vanilla Linux generic's files, therefore you *must* always replace the provided +PAM files with custom alternatives and sane defaults. In general, LFS is a good +recommandation regarding PAM files. + +Also, don't forget to add PAM files to the *PKGPROTECT* variable as they are +meant to be edited by the system administrator. + +Patches +======= + +If a software requires patching, always try to see if there is already an +upstream patch that fixes the issue. If not, you may check how other Linux +distributions fix the problem with a local workaround. + +Then, please consider sending the patch to the upstream if applicable. + +Patches must be named in the form *patch-category.patch*. We encourage old style +of patches that you usually create by editing the file and comparing with the +original one. + +Example: + + cp Makefile.orig Makefile + vim Makefile + diff -ub Makefile.orig Makefile > patch-musl.patch + +Warning: by default busybox patch is used and is much stricter than standalone + counterpart, in doubt always try to apply the patch manually with + busybox patch and edit if required. + +The following names are recommended depending on the situation: + +- patch-fhs.patch: when a patch is required to adapt installation/usage to the + Vanilla Linux file system hierarchy, +- patch-musl.patch: when the code assume a glibc specific code, +- patch-clang.patch: when the code does not compile with LLVM/Clang. Make sure + the patch does not break GCC, if it does apply the patch in a conditional. + +Also, do not create a patch for individual files if they all belong to the same +category. For example, if several source files require patching to build against +musl, use only one *patch-musl.patch* file. Services ======== -Services files must be installed in /etc/rc.d. You must use the following -conventions regarding messages the service will print. +Services files must be installed in /etc/rc.d in the mode 0644. + +Example: + + install -Dm0644 food $DESTDIR/etc/rc.d/food The script must at least support start, stop and restart. -#### start (required) +UX style +-------- + +You must use the following conventions regarding messages the service will +print. + +### start (required) Always add arguments with the invocation. - Starting foo: /bin/foo -d + Starting foo: /bin/foo -d + +If the service is already running, show: -#### stop (required) + foo is already running with pid: 1234 + +### stop (required) If the service is not running, don't write any message. Otherwise write: - Stopping foo. + Stopping foo. -#### restart (required) +### restart (required) Basically, this command just calls stop and start. - Stopping foo. - Starting foo: /bin/foo -d + Stopping foo. + Starting foo: /bin/foo -d -#### status +### status (recommended) Depending on the status, write the following messages. - foo is running with pid: 1234 - foo is not running + foo is running with pid: 1234 + foo is not running -#### usage +### usage (required) If the script is invoked with invalid arguments or none, write the usage like this through stderr and exit 1. Also keep all subcommands sorted. - usage: foo restart|start|status|stop + usage: foo restart|start|status|stop If your script may support additional operations, messages and usage are up to the maintainer discretion. See also the template file in Templates/rc. -Libraries -========= +Libtool files +============= + +Do not ship libtool files. -Do not ship static libraries and libtool files. Make sure your build script -suppress static builds if possible or delete the .a file. +Manual pages +============ -Note: the C and C++ library are shipped for technical reasons though. +Do never install compressed manual pages. The `vpk` tool performs automatic +compression on installation depending on the user setting. Check how to disable +compression in the package or decompress them after installation in the +destination directory. Post install scripts ==================== @@ -269,7 +332,7 @@ - post-uninstall: after the removal of the package. Note: if the package wants to call a binary from an other package, it is usually -a good idea to check it's presence first. + a good idea to check it's presence first. Example: