Mercurial > vanilla
diff HOWTO.md @ 349:7b000befead5
vanilla: improve docs and hierarchy
author | David Demelier <markand@malikania.fr> |
---|---|
date | Thu, 28 Mar 2019 20:15:00 +0100 |
parents | |
children | 0b7acfc69fec |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/HOWTO.md Thu Mar 28 20:15:00 2019 +0100 @@ -0,0 +1,350 @@ +# vanilla HOWTO + +This documentation explains how to write a package file. + +Each package lives under a dedicated directory broken down into several +categories. Change the directory to the desired package and use `vpk build` to +construct a package. The repository does not contain the distribution files from +upstream but `vpk build` will download them for you if not present (see also +`vpk download` command). + +Note: vpk build does not handle dependencies. + +Example with lib/zlib + + # cd lib/zlib + # vpk build + +If build succeeded, you can install the package as +/tmp/vpk/zlib#version-revision-arch.txz + +Tip: you can use `vpk build -q` to silent the process. + +# How to create a new package + +To create a new package, create a directory in the appropriate category +directory. Then create the sscript file. See Templates directory. + +Example, if you want to create a package abc in category lib you must have the +following files. + +lib/abc +lib/abc/abc.sh + +The following variables must be present: + +- PKGNAME: the package name +- PKGVERSION: the package upstream version +- PKGREVISION: the vanilla revision (starts at 1) +- PKGLICENSE: a space separated list of licenses (see README.licenses.md) +- PKGSUMMARY: a short summary + +The following variables are optional + +- PKGDEPENDS: a space separated list of packages required to build. Use the + syntax category/package for runtime requirement (includes building too) and + category/package:build for build requirement only. +- PKGDOWNLOAD: a space separated list of files to download from the web, if the + package does not need to download anything don't set it. +- PKGUIDS: a space separated list of uid to create +- PKGGIDS: a space separated list of gid to create +- PKGPROTECT: a space separated list of relative path to files to preserve on + installation (e.g. etc/nginx/nginx.conf) +- PKGOPTIONS: a space separated list of CAPITALIZED options. + +The script file is the build procedure for the package. It must be as simple as +possible as its sole purpose is to build and install files through the DESTDIR +variable. + +There are already various of templates in the templates/ directory. + +# Topics + +## Licenses + +Use the following licenses in *PKGLICENSE* or CUSTOM. + +- AGPLv3 +- AGPLv3+ +- APACHE10 +- APACHE11 +- APACHE20 +- BOOST +- BSD +- BSD2CLAUSE +- BSD3CLAUSE +- BSD4CLAUSE +- GFDL +- GPLv1 +- GPLv1+ +- GPLv2 +- GPLv2+ +- GPLv3 +- GPLv3+ +- ISC +- LGPLv20 +- LGPLv20+ +- LGPLv21 +- LGPLv21+ +- LGPLv3 +- LGPLv3+ +- MIT +- UNLICENSE + +## Dependencies + +The variable *PKGDEPENDS* is filled up with package origins, thus you need to +write *lib/zlib* NOT *zlib*. + +Also, the following qualifiers may be appended to the dependency to alter the +meaning: + +- `:build` the dependency is only required for building, +- `:optional` the dependency is optional and not strictly required. +- `:recommended` same as optional but installed by default. + +Example: + + PKGDEPENDS="dev/cmake:build graphics/qt5:recommended lib/zlib" + +## Configuration files + +Configuration files (usually everything under /etc) must be marked as well in +*PKGPROTECT* variables. This prevents `vpk` for overriding user configurations. + +Note: if the package ships a init script file, it must be marked as well. + +Example: + + PKGPROTECT="/etc/nginx.conf /etc/rc.d/nginx" + +## Uids / Gids + +If the package requires UNIX users and groups, adapt the *PKGUIDS* and *PKGGIDS* +variables as a space separated list. You can assign a default numeric id using +the syntax `:number`. + +Example: + + PKGUIDS="messagebus" # vpk will assign an id + PKGUIDS="gdm:55" # vpk will use 55 + +Warning: if you need to change file permissions, do it *ONLY* in a post install +script as users may have set different numeric id than the package defaults. + +## Options + +Some packages are configurable via compile time options. Check the variable +PKGOPTIONS in the script file and read the associated documentation for more +explanation. Options are usually passed as environment variables + +Example with network/wget: + + # cd network/wget + # SSL=openssl NLS=no vpk build + +Add the desired options in *PKGOPTIONS* variable and don't forget to set default +values. + +Example with NLS + + PKGOPTIONS="NLS" + + : ${NLS:=yes} + + if [ "$NLS" = "yes" ]; then + PKGDEPENDS="core/gettext $PKGDEPENDS" + with_nls="--enable-nls" + else + with_nls="--disable-nls" + fi + +Then at configure step: + + ./configure $with_nls + +Proper handling of options is done by explicitly disabling/enabling options. +Most programs will try to enable/disable features depending on what is available +on the system thus, if the package finds a dependency and enable it you need to +adapt *PKGDEPENDS*. Always check what options are available in the package and +use their default as explicit knobs to avoid invisible dependencies. + +Use the following predefined options before creating your own. + +- ACL: enable access control list support +- BLUETOOTH: enable bluetooth support +- BZIP2: enable bzip2 compression support +- DBUS: enable D-Bus support +- DOXYGEN: enable doxygen documentation support +- DRM: enable direct rendering manager support +- DTD: enable XML validation support +- EGL: enable EGL support +- FONTCONFIG: enable fontconfig support +- FREETYPE: enable freetype support +- GALLIUM: enable LLVM gallium support +- GDBM: enable GNU database support +- GLAMOR: enable 2D graphics support +- GLES2: enable GLES2 support +- GLES3: enable GLES3 support +- GMP: enable GNU multiple precision library +- GTK2: enable Gtk 2 toolkit support +- GTK3: enable Gtk 3 toolkit support +- GTK4: enable Gtk 4 toolkit support +- GUILE: enable GNU guile support +- IDN2: enable libidn2 support +- KMS: enable kernel mode settings support +- LLVM: enable LLVM support +- LZ4: enable lz4 compression support +- LZMA: enable lzma compression support +- MNL: enable netlink minimalistic library support +- NLS: enable native language support +- PAM: enable PAM support +- PCRE: enable perl-like regular expression support +- PULSEAUDIO: enable PulseAudio support +- PYTHON: enable Python 3 bindings or support +- QT5: enable Qt 5 toolkit support +- SPHINX: enable sphinx documentation support +- SSH: enable SSH support +- SSL: enable SSL/TLS, some packages offer several choices (e.g. openssl, gnutls) +- UDEV: enable eudev support +- UUID: enable UUID support +- WACOM: enable wacom support +- WAYLAND: enable wayland support +- X: enable X.Org support +- XML: enable XML support +- XZ: enable XZ support +- ZLIB: enable zlib compression support +- ZSTD: enable zstd compression support + +Always try to make an option easy to understand and not package specific. For +example BLUETOOTH is preferred over BLUEZ because a user knows what bluetooth is +but may not know that bluez is the current reference implementation. Also, it is +preferred to make an option generic to allow multiple values in case the +package offers it. + +Example, if a package offers different implementations for SSL, consider the +option with a value (e.g. SSL=openssl, SSL=gnutls, and such). + +Also, if a package offers different implementations that can be enabled all +together, use a list separated by space (e.g. XML="libxml2 expat"). + +Those options should only change the package behaviour, for example: manual +pages or any other resource files that are not strictly required; they must be +installed and the user may exclude them via `vpk` instead. + +The following options should be available for any package that builds C or C++ +code: + +- CBUILD: build system (usually ARCH-linux-musl) +- CHOST: host system (usually ARCH-linux-musl) +- CTARGET: target system (usually ARCH-linux-musl) +- CC: C compiler (defaults to gcc) +- CFLAGS: C flags (defaults to -O2) +- CXX: C++ compiler (defaults to g++) +- CXXFLAGS: C++ flags (defaults to -O2) + +## Keep vanilla + +Do not make any modifications to the package. Keep it as close to upstream as +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 + +## Package naming + +The following prefixes must be used for those packages: + +- py-: for python modules +- ruby-: for native ruby modules +- rubygem-: for rubygems modules +- p5-: for perl 5 modules +- hs-: for haskell modules +- font-: for fonts (of any kind) + +When a package is available with different versions (e.g. Gtk, Qt) we add the +major number as suffix to the PKGNAME to *old* versions. Example, if Qt 5 is the +current major version and Qt 4 is also shipped then, the package *qt* refers to +version 5 while *qt4* to version 4. + +## Paths + +The package must ensure appropriate directories for installing files. This +includes: + +- /etc/rc.d for service files +- /usr/lib/pkgconfig: for .pc files +- /usr/lib/cmake: for CMake config files +- /usr/lib: for libraries (no lib64 suffix) +- /usr/share/man/man{1,2,3,4,5,6,7,8}: for man pages (in uncompressed form) +- /usr/share/doc/PKGNAME (exact directory, no version) + +## Services + +Services files must be installed in /etc/rc.d. You must use the following +conventions regarding messages the service will print. + +The script must at least support start, stop and restart. + +#### start (required) + +Always add arguments with the invocation. + + Starting foo: /usr/bin/foo -d + +#### stop (required) + +If the service is not running, don't write any message. Otherwise write: + + Stopping foo. + +#### restart (required) + +Basically, this command just calls stop and start. + + Stopping foo. + Starting foo: /usr/bin/foo -d + +#### status + +Depending on the status, write the following messages. + + foo is running with pid: 1234 + foo is not running + +#### usage + +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 + +If your script may support additional operations, messages and usage are up to +the maintainer discretion. + +See also the template file as Templates/rc. + +## Static libraries and 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. + +Note: the C and C++ library are shipped for technical reasons though. + +## Don't delete blindly + +Do never delete global files through the prefix installation as some people may +use scripts directly for the system. + +Example (BAD): + + rm -f $DESTDIR/usr/lib/*.la + +Example (BETTER): + + rm -f $DESTDIR/usr/lib/libfoo.la + +Assuming the package is "foo".