Mercurial > vanilla
view HOWTO.md @ 594:3cffdd760a86
vanilla: improve docs files
author | David Demelier <markand@malikania.fr> |
---|---|
date | Fri, 12 Jul 2019 20:50:00 +0200 |
parents | 1d82637c2980 |
children | 860ab66f5f71 |
line wrap: on
line source
Vanilla Linux 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 initial 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. Once you need a new UID/GID, edit the file UIDS_GIDS.md in the repository accordingly. ## 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 - LEGACY: enable obsolete or deprecated features - LLVM: enable LLVM support - LZ4: enable lz4 compression support - LZMA: enable lzma compression support - MIDI: enable midi 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 neutral 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 - /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) ## 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: /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: /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/lib/*.la Example (BETTER): rm -f $DESTDIR/lib/libfoo.la Assuming the package is "foo".