=head1 NAME pkg - distributed dotfile and script manager, 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) =head1 THE BASICS pkg requires two directories in your home directory. B<~/bin> contains symlinks to the executables shipped with your packages, and $PKG_DIR (B<~/packages> by default) contains the packages themselves. B<~/bin> may also contain normal executables; pkg will not overwrite existing files. =head1 THE PACKAGE DIRECTORY $PKG_DIR is the core of all this stuff. Its main use is storing the packages. There is one directory for each installed package, as created by B. $PKG_DIR holds two special files: B<.list> and B<.list-remote>. For an explanation about these files, see L below. It also contains a special directory, F<.collected> - see L. =head2 NOTE All directories in $PKG_DIR 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 $PKG_DIR, 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. The package root should contain the pkglist script shipped in include/. If it doesn't, PKGLIST_PATH in .pkg.conf must be set to the appropiate location on the package root host. =head1 THE PACKAGE LIST The 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: pkg git 82d716d01dee0329af7df5e67b55558fe3ff1466 =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. Note that all files and directories mentioned here are optional. =over =item bin/ The place for executables to be in the user's PATH. pkg will automatically create symlinks in F<~/bin> pointing to the files in the package's F. Also, if a file in F contains valid POD, a manual will be generated out of it (see L) =item etc/ Configuration files, not treated specially though =item hooks/ Package hooks, see L =item include/ Scripts used by the package that don't belong into B. Not treated specially =item man/ Manual files in POD format, separated by section (like man/7/pkg.pod). To be prepared for possible future support of other manual formats, it is recommended to postfix each file with .pod =item provides/ Files for inclusion into other packages =item description Package description for B =item links Sym- and hardlink descriptions. See checklinks(1) =item Makefile If a Makefile is available, C will be executed every time the package is updated (pkg add/push/pull/refresh) =item prereqs The package's prerequisites, mainly dependencies. See L =item priority Package priority as an integer between 1 and 6. Packages with a priority above 3 require user confirmation to be removed =back =head1 PREREQUISITES The prerequisites are stored in a package in the file F. It as an ordinary shell script which is sourced by pkg's global post-update hook; so it will be sourced after pulling, pushing or refreshing a package. Note that the file will be sourced in function scope. It is recommended to introduce parameters and options local to the prereqs script with C<< typeset >> and C<< setopt localoptions >>, respectively. It's main use is to check for dependencies. To help with this, the following functions are available: =over =item B I Returns true if I is installed, otherwise false =item B I Returns true if I can be used by perl, otherwise false =item B I Returns true if I was found in the users PATH, otherwise false =item B I Mark I for installation =item B I | B I Execute expression and automatically warn if it fails. In case of B, automatically mark B for installation if it isn't installed. If a B fails, pkg will inform the user about it and wait for confirmation =item B I<...>, B I<...> Take the same arguments as B, but are of lower priority. recommend only causes "info" messages, and suggest does not interrupt pkg to make sure it's read by the user =back Additionally, the string parameters B and B can be used to store messages. After executing the prereqs script, pkg will print the content of these parameters and wait for confirmation. It will also offer to install packages marked by B or B. =head1 HOOKS Hooks are little zsh snippets residing in $PKG_DIR/hooks which are sourced from within pkg whenever needed. Currently, the following hooks exist: =over =item post-add Sourced after a package was installed (e.g. with pkg add/pkg install) =item post-update Sourced after a package was updated (pkg pkg pull). It is also sourced when adding a package (after post-add) and when calling pkg refresh. =item pre-remove Sourced before a package is removed (pkg remove) =back =head1 COLLECTED PACKAGE FILES These files reside in F<$PKG_DIR/.collected> (subject to change). The directory is somewhat similar to F<~/bin> - it is automatically populated by pkg. However, this one does not contain symlinks. Currently, it only contains the directory F, which holds the "compiled" manual pages from the packages (extracted from F and F). This way, you can put F<.../.collected/man> into you MANPATH to access manuals provided by packages. =head1 GIT B uses git(1) as backend for storing and syncing package information. It is not recommended to use branches other than "master". While they should work if GIT_USE_ORIGIN is set to 1 (the default), they will most likely confuse pkg. =head1 AUTHOR Daniel Friesel Ederf@derf.homelinux.orgE =head1 SEE ALSO checklinks(1), pkg(1)