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:

	Package metadata
	-----------------
	/INSTALL
	/REMOVE
	/files.plist
	/props.plist

	Package data
	-----------------
	/usr
	/var
	/etc
	...

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

The files.plist file contains the list of files/links/dirs that package
will install, as well as SHA256 hashes for files.

The props.plist file contains package metadata properties 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-repo genindex $XBPS_PACKAGES
	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>