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-setup.pod | 17 +++ man/7/caretaker.pod | 256 ++++++++++++++++++++++++++++++++++++++++++++++ man/7/pkg-setup.pod | 17 --- man/7/pkg.pod | 256 ---------------------------------------------- 4 files changed, 273 insertions(+), 273 deletions(-) create mode 100644 man/7/caretaker-setup.pod create mode 100644 man/7/caretaker.pod delete mode 100644 man/7/pkg-setup.pod delete mode 100644 man/7/pkg.pod (limited to 'man/7') diff --git a/man/7/caretaker-setup.pod b/man/7/caretaker-setup.pod new file mode 100644 index 0000000..d59a0a2 --- /dev/null +++ b/man/7/caretaker-setup.pod @@ -0,0 +1,17 @@ +=head1 NAME + +caretaker - Package root setup + +=head1 PACKAGE ROOT + +First, you'll need to create a root directory (from now on PKG_ROOT) on the +server which shall from now on host all your packages. +Then you need to put the caretaker git repository into F - it's recommended +to do this via git clone --bare. + +Copy the pkglist script (include/pkglist) to F. + +Now you can add your own packages as git repos in PKG_ROOT. + +To use caretaker with your packages on a machine, download and execute +the bootstrap script (include/bootstrap). 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) diff --git a/man/7/pkg-setup.pod b/man/7/pkg-setup.pod deleted file mode 100644 index 1c0d7bf..0000000 --- a/man/7/pkg-setup.pod +++ /dev/null @@ -1,17 +0,0 @@ -=head1 NAME - -pkg - Package root setup - -=head1 PACKAGE ROOT - -First, you'll need to create a root directory (from now on PKG_ROOT) on the -server which shall from now on host all your packages. -Then you need to put the pkg git repository into F - it's recommended -to do this via git clone --bare. - -Copy the pkglist script (include/pkglist) to F. - -Now you can add your own packages as git repos in PKG_ROOT. - -To use pkg with your packages on a machine, download and execute -the bootstrap script (include/bootstrap). diff --git a/man/7/pkg.pod b/man/7/pkg.pod deleted file mode 100644 index 8288b54..0000000 --- a/man/7/pkg.pod +++ /dev/null @@ -1,256 +0,0 @@ -=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 - -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 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. 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 (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 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 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) -- cgit v1.2.3