# 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.

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