From bed8857b779b9896f6a3b54336feddb41c0a5b5a Mon Sep 17 00:00:00 2001 From: Daniel Friesel Date: Tue, 7 Jul 2009 13:10:07 +0200 Subject: pkg: Recommend to postfix manuals in man/ with .pod --- man/7/pkg.pod | 236 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 236 insertions(+) create mode 100644 man/7/pkg.pod (limited to 'man/7/pkg.pod') diff --git a/man/7/pkg.pod b/man/7/pkg.pod new file mode 100644 index 0000000..c9163d7 --- /dev/null +++ b/man/7/pkg.pod @@ -0,0 +1,236 @@ +=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 you 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 + +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: + + 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. + +Unless marked with [*], all files and directories 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 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.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 + +=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; in case of B, it will also 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 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 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, yuo 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 update. + +=head1 AUTHOR + +Daniel Friesel Ederf@derf.homelinux.orgE + +=head1 SEE ALSO + +checklinks(1), pkg(1) -- cgit v1.2.3