Getting started
===============

This documentation explains how to write a package file from scratch.

Synopsis
========

Each package lives under a dedicated directory broken down into several
categories. A package consists of the following files:

- NAME.sh: a pure POSIX shell that process the build and contains some
  metadata required for installation.
- NAME.sha1: contains the checksums for individual source files (Optional).
- NAME-post.sh: a script to be executed before/after the installation
  (Optional).

In the listing above, replace NAME with the actual package name. For example the
package *zlib* contains the following files:

- compression/zlib/zlib.sh
- compression/zlib/zlib.sha1

The build script
================

The build script (NAME.sh) is a pure POSIX shell that defines various
information about the package and how to build it. To be included within the
official Vanilla Linux repository it must be licensed under the terms of the ISC
license.

Several templates are already available for most build systems in the Templates
directory.

Metadata
--------

A package requires several information to be installed, the following variables
must be present:

- PKGNAME: the package name (same as the directory).
- PKGVERSION: the package upstream version.
- PKGREVISION: the initial revision (starts at 1).
- PKGLICENSE: a space separated list of licenses (see licenses.md file).
- PKGSUMMARY: a short summary.

The following variables are optional

- PKGDEPENDS: a space separated list of packages required to build (see below). 
- 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 (see below)
- PKGGIDS: a space separated list of gid to create (see below)
- 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.

Build
-----

To build the package, you need to define a build function that install the
package into the $DESTDIR variable.

Usually, the build function does:

1. Clean the build directory in case the previous build failed.
2. Extract distribution files.
3. Process build and installs into $DESTDIR.
4. Clean up again the build directory.

Package naming
==============

The following prefixes must be used for those packages:

- py-: for python modules.
- py2-: for python modules (only for exceptional cases).
- 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.

Handling dependencies
=====================

The variable *PKGDEPENDS* is filled up with package origins, thus you need to
write *lib/zlib* NOT *zlib*.

Also, the following selectors 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"

Protected 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"

In this case, `vpk` will rename the file to *etc/nginx.conf.vpk* and
*/etc/rc.d/nginx.vpk* in the archive and only be renamed if they are not present
on the disk or not manually modified.

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.md in this directory as well.

Options
=======

...

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.

See the file options.md for predefined options and proper naming.

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)

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

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 in Templates/rc.

Libraries
=========

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.

Post install scripts
====================

If you need to perform some custom steps after the installation of the binary
package in the target systems, you may create the NAME-post.sh script. This
script must be written also in pure POSIX shell language.

As unique argument, `vpk` will provide one of these to the post script:

- pre-install: before the extraction of the package.
- post-install: after the extraction of the package.
- pre-uninstall: before removing the package.
- post-uninstall: after the removal of the package.

Note: if the package wants to call a binary from an other package, it is usually
a good idea to check it's presence first.

Example:

	#!/bin/sh

	if [ -x /bin/gtk-update-icon-cache ]; then
		gtk-update-icon-cache -vf /share/icons/hicolor
	fi

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