=pod

=head1 NAME

pkg - Package maintenance utility, package format

=head1 INTRO

(if you prefer technical infos over historical blah-blah, skip this section)

Actually, pkg is just a pimped dotfile manager, which just happens to support
a sort of packages, version control, automatic sym- and hardlinking, and which
can also handle scripts and binaries. Oh, and it can cause serious brain damage.

It evolved from two hg repos for ~/bin and ~/etc and some management scripts,
and now it can handle as many git repos as you want, which may contain
basically anything you can think of - you can even store movies in them.
(Of course that would be completely braindead, but hey -
you could, if you wanted to)

Currently, pkg should be considered early-beta software. It already works quite
well and does not have many known bugs, however some concepts are really stupid
and are subject to change. Be warned that backwards compatibility can NOT be
guaranteed, though I will do my best.

=head1 THE BASICS

B<pkg> requires two directories in you home directory. B<~/bin> contains
symlinks to the executables shipped with your packages, and $PDIR
(B<~/packages> by default, but *theoretically* configurable) contains the
packages themselves. B<~/bin> may also contain normal executables, just make
sure they don't conflict with a package's ones.

=head1 THE PACKAGE DIRECTORY

$PDIR is the core of all this stuff. It's main use is storing the packages.
There is one directory for each installed package, as created by B<git clone>.
Additionally, $PDIR holds two speciel files: B<.list> and B<.list-remote>. For
an explanation about these files, refer to the section 'the package list' below.

=head2 NOTE

All directories in $PDIR must be valid git repositories which are not in the
state of 'initial commit'. Dotfiles (directories starting with a .) are exempt
from this, they will be ignored by pkg.

=head1 THE PACKAGE ROOT

The packages_root, in pkg referred to as $PKG_ROOT, is structured just like
the packages directory $PDIR, except that it neither contains .list nor
.list-remote. The packages root is the central point where pkg fetches
packages from and pushes packages to.

=head2 CAUTION

The file $PKG_ROOT/core/include/pkglist is used by pkg, so make sure the git
repo is checked out. A regular 'git checkout -f' in the core repo is recommended.

=head1 WHAT IS A PACKAGE?

Anything tracked with git can be used as package. However, as the purpose of pkg
is not to do your version control, you probably want to have at least one of the
files and directories described below in it.

=head1 PACKAGE STRUCTURE

Special (as in, mostly handled by pkg) directories and files in a package.

Unless marked with [*], all files and directories are optional

=over

=item bin/

The place for executables to be in the user's PATH. For their processing, see B<populate_collected>

=item etc/

Configuration files, not threated specially though

=item include/

Scripts used by the package that don't belong into B<bin/>. Not threated specially

=item man/

Manual files in POD format, separated by section (like man/7/pkg)

=item provides/

Files for inclusion into other packages

=item description

Package description for B<pkg info>

=item links

Sym- and hardlink descriptions. See checklinks(1)

=item prereqs

The package's prerequisites, mainly dependencies. See B<check_prereqs>

=item priority

Package priority as an [1;6] interval of integer numbers.

=back

=head1 MAJOR INTERNAL FUNCTIONS

=over

=item B<check_prereqs> I<package>

Checks a package's prerequisites as defined in B<prereqs>.
The prereqs file is a zsh script which is sourced by pkg.
The following pkg-related functions are available:

* B<is_installed> I<package>

Returns true if I<package> is installed, otherwise false

* B<perlmodule> I<perlmodule>

Returns true if I<perlmodule> can be used by perl, otherwise false

* B<file_in_path> I<commendname>

Returns true if I<commandname> was found in the users PATH, otherwise false

* B<offer_install> I<package>

Mark I<package> for installation

* B<require> I<expression> | B<require package> I<package>

Execute expression and automatically warn if it fails.
In case of B<require package>, automatically mark B<package> for installation
if it isn't installed

Additionally, the string parameter 'warn' can be used to soak up warnings.
It's also used by B<require>

After completing the execution of B<prereqs>,
pkg will offer to install all the packages added by B<offer_install> or
B<require package>, and will print out the text stored in $warn

=item B<populate_collected> I<package>

This command does two things.
First, it creates the appropiate symlinks in F<~/bin> to the files in B<bin/>.
Second, it runs podchecker(1) over the files in B<bin/> and B<man/> and
uses pod2man(1) to create man pages from them, which will then be stored in
B<.collected> (like .collected/man/man7/pkg.7).

The command is invoked with pkg upgrade, add, push and refresh

=item B<genocide_collected> I<package>

Revert the actions of populate_collected. Called with pkg delete.

=item B<update_provides> I<package>

Walks through the directories in B<provides> and executes the post-update hooks
of the corresponding packages.

=back

=head1 THE PACKAGE LIST

Thi package list lives in the files B<.list> and B<.list-remote> mentioned
above. It's used to decide whether a package needs to be pulled / pushed.
Also, the 'pkg add' completion relies on .list-remote, and back in the days when
pkg supported more than one DVCS, it was used to determine which DVCS to use
for which package.

It consists of one line per package, each line containing three items separated
by a single whitespace. The first item is the package name, the second one the
repository type (DVCS), the third the current revision. Example:

  core git 82d716d01dee0329af7df5e67b55558fe3ff1466


=head1 AUTHOR

Daniel Friesel <derf@derf.homelinux.org>

=head1 SEE ALSO

checklinks(1), pkg(1)

=cut

vim:ft=pod