=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 PACKAGES 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 PACKAGES 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>

After completing the execution of B<prereqs>,
pkg will offer to install all the packages added by this command.
Use in conjunction with B<is_installed>, like
  is_installed brain || offer_install brain

=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, pkg add and pkg push

=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 AUTHOR

Daniel Friesel <derf@derf.homelinux.org>

=head1 LICENSE

  0. You just DO WHAT THE FUCK YOU WANT TO.

=head1 SEE ALSO

checklinks(1), pkg(1)

=cut

vim:ft=pod