void-packages/doc/BINPKG_INFO

------------------------------------------------------------------------------
 BRIEF INTRODUCTION
------------------------------------------------------------------------------

A binary package built with xbps is a normal tar(1) archive, compressed
with bzip2 and has the following structure:

	/
	/usr ------|
	/var ------| => Package structure that will be installed.
	/etc ------|
	...
	/var/db/xbps/metadata/$pkgname
	/var/db/xbps/metadata/$pkgname/flist
	/var/db/xbps/metadata/$pkgname/props.plist
	/var/db/xbps/metadata/$pkgname/INSTALL
	/var/db/xbps/metadata/$pkgname/REMOVE

Metadata info is stored in the "/var/db/xbps/metadata/$pkgname"
directory and two files will be always be present: flist and props.plist.

The flist file contains the list of files that the package will
install. The props.plist file is a proplib(3) property list and
has the following structure:

<dict>
	<key>pkgname</key>
	<string>foo</string>

	<key>version</key>
	<string>3.40</string>

	<key>maintainer</key>
	<string>The Master BOFH <bofh@baobab.org> </string>

	<key>short_desc</key>
	<string>Foo is a virtual package</string>

	<key>long_desc</key>
	<string>
 Foo is a virtual package to show how the metadata props.plist file works
 with xbps handling binary packages.</string>

	<key>architecture</key>
	<string>x86_64</string>

	<key>installed_size</key>
	<integer>500000</integer>

	<key>configuration_files</key>
	<array>
		<string>/etc/foo.conf</string>
		...
	</array>
	<key>run_depends</key>
	<array>
		<string>bofh-2.0</string>
		<string>blab-1.1</string>
		...
	</array>
	...
</dict>

The INSTALL/REMOVE executables allows you to trigger any action
at pre/post installation/removal of the binary package.

The package's dictionary will also be written into the repository's package
index file, that describes information about a binary package on it.
See the BINPKG_REPOSITORY file for more info about repositories.

------------------------------------------------------------------------------
 HOW TO USE BINARY PACKAGES
------------------------------------------------------------------------------

To install binary packages, firstly a repository must be created as well as
some binary packages for it. The flow for this task is:

	1- xbps-src install <package>
	2- xbps-src build-pkg all [requires sudo access]
	3- xbps-src genindex
	4- xbps-repo add $XBPS_PACKAGES
	5- xbps-bin install -r /rootdir <package>

So the tasks are: install the package into destdir (and all its dependencies),
build the binary package from the required package, generate the repository
index, add the repository into the pool and install the binary package.

Please note that by default, the xbps-* utils accept the -r flag, to specify
the root directory for all operations, in that case the package will be
installed into <rootdir> and metadata files into <rootdir>/var/db/xbps.

Don't forget to set this flag if you aren't using xbps as the primary
package manager in your system, otherwise it could overwrite some files!

See the BINPKG_REPOSITORY file for more info about repositories for
binary packages or SRCPKG_INFO for source packages.

------------------------------------------------------------------------------
	Juan Romero Pardines <xtraeme@gmail.com>