Mercurial > vanilla
diff HOWTO.md @ 714:6b4ba668a43c
vanilla: update documentation
author | David Demelier <markand@malikania.fr> |
---|---|
date | Fri, 02 Aug 2019 21:20:00 +0200 |
parents | 393525a3ecc3 |
children | 150598ec37e7 |
line wrap: on
line diff
--- a/HOWTO.md Fri Aug 02 21:15:00 2019 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,370 +0,0 @@ -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". - -# Desktop files - -We usually never add .desktop files for any package that doesn't provide one by -itself. This also includes terminal based applications. - -If a .desktop is provided by the package, make sure though that it is valid and -specifies the appropriate category (i.e. it does not appear in multiple menus at -once). - -See [desktop entry specification][] for more information. - -[desktop entry specification]: https://specifications.freedesktop.org/desktop-entry-spec/latest