--- /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".