=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 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. 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 =item etc/ Configuration files, not threated specially though =item hooks/ Package hooks, see L =item include/ Scripts used by the package that don't belong into B. 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 =item links Sym- and hardlink descriptions. See checklinks(1) =item prereqs The package's prerequisites, mainly dependencies. See B =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 MAJOR INTERNAL FUNCTIONS =over =item B I Checks a package's prerequisites as defined in B. The prereqs file is a zsh script which is sourced by pkg when adding/updating a package. The following pkg-related functions are available: * B I Returns true if I is installed, otherwise false * B I Returns true if I can be used by perl, otherwise false * B I Returns true if I was found in the users PATH, otherwise false * B I Mark I for installation * 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 Additionally, the string parameter 'warn' can be used to soak up warnings. It's also used by B After completing the execution of B, pkg will offer to install all the packages added by B or B, and will print out the text stored in $warn =item B I This command does two things. First, it creates the appropiate symlinks in F<~/bin> to the files in B. Second, it runs podchecker(1) over the files in B and B 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 I Revert the actions of populate_collected. Called with pkg delete. =item B I Walks through the directories in B 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 HOOKS Hooks are little zsh-snippets residing in $PDIR/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 upgrade/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/pkg delete) =back =head1 AUTHOR Daniel Friesel =head1 SEE ALSO checklinks(1), pkg(1) =cut vim:ft=pod