From 324568044af4287dd25a90dc143ea26df565d1e3 Mon Sep 17 00:00:00 2001 From: Daniel Friesel Date: Sat, 11 Jul 2009 01:17:18 +0200 Subject: Renamed pkg to caretaker --- man/7/caretaker.pod | 256 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 256 insertions(+) create mode 100644 man/7/caretaker.pod (limited to 'man/7/caretaker.pod') diff --git a/man/7/caretaker.pod b/man/7/caretaker.pod new file mode 100644 index 0000000..bbef02d --- /dev/null +++ b/man/7/caretaker.pod @@ -0,0 +1,256 @@ +=head1 NAME + +caretaker - distributed dotfile and script manager, package format + +=head1 INTRO + +(if you prefer technical infos over historical blah-blah, skip this section) + +Actually, caretaker 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 + +caretaker 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; caretaker 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 caretaker. + +=head1 THE PACKAGE ROOT + +The packages_root, in caretaker 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 caretaker 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 .caretaker.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 'caretaker add' completion relies on .list-remote, and back in the days when +caretaker 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: + + caretaker git 82d716d01dee0329af7df5e67b55558fe3ff1466 + +The package list is generated by the script set in the config var $PKGLIST_PATH, +by default F. Depending on $PKGLIST_LOCAL and $PKG_ROOT, it +is either executed on the local host or on the remote host containing the package +root. The script is always called with $PKG_PATH as the first argument. +Its output must only contain valid pkglist lines (see the example above). + +With $PKGLIST_LOCAL set to 1, there are some interesting possibilities. +For instance, your pkglist script could contain a line like +C<< curl -s http://example.org/cgi-bin/pkglist.cgi >> - so you can update your +remote package list without having to use ssh. + +=head1 WHAT IS A PACKAGE? + +Anything tracked with git can be used as package. However, as the purpose of caretaker +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 caretaker) 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. +caretaker 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/caretaker.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. See L + +=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 (ct 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 caretaker'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, caretaker 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 caretaker +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, caretaker will print the content of +these parameters and wait for confirmation. +It will also offer to install packages marked by B or +B. + +=head1 PROVIDES + +The F directory contains subdirectories with the names of the package +for which stuff is provided. Every time a package with a provides directory is +added, updated or removed, for each of the directories in F, the +respective package's post-update hook is exectued. It is the responsibility +of that hook to do something useful with the data in F. + +=head1 HOOKS + +Hooks are little zsh snippets residing in $PKG_DIR/hooks +which are sourced from within caretaker whenever needed. + +Currently, the following hooks exist: + +=over + +=item post-add + +Sourced after a package was installed (e.g. with ct add/ct install) + +=item post-update + +Sourced after a package was updated (ct pull). +It is also sourced when adding a package (after post-add) and +when calling ct refresh. + +=item pre-remove + +Sourced before a package is removed (ct 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 caretaker. 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 caretaker. + +=head1 AUTHOR + +Daniel Friesel Ederf@derf.homelinux.orgE + +=head1 SEE ALSO + +checklinks(1), ct(1) -- cgit v1.2.3