1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
=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<pkg> 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 PACKAGES 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<git clone>.
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 PACKAGES 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<populate_collected>
=item etc/
Configuration files, not threated specially though
=item include/
Scripts used by the package that don't belong into B<bin/>. 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<pkg info>
=item links
Sym- and hardlink descriptions. See checklinks(1)
=item prereqs
The package's prerequisites, mainly dependencies. See B<check_prereqs>
=item priority
Package priority as an [1;6] interval of integer numbers.
=back
=head1 MAJOR INTERNAL FUNCTIONS
=over
=item B<check_prereqs> I<package>
Checks a package's prerequisites as defined in B<prereqs>.
The prereqs file is a zsh script which is sourced by pkg.
The following pkg-related functions are available:
* B<is_installed> I<package>
Returns true if I<package> is installed, otherwise false
* B<perlmodule> I<perlmodule>
Returns true if I<perlmodule> can be used by perl, otherwise false
* B<file_in_path> I<commendname>
Returns true if I<commandname> was found in the users PATH, otherwise false
* B<offer_install> I<package>
After completing the execution of B<prereqs>,
pkg will offer to install all the packages added by this command.
Use in conjunction with B<is_installed>, like
is_installed brain || offer_install brain
=item B<populate_collected> I<package>
This command does two things.
First, it creates the appropiate symlinks in F<~/bin> to the files in B<bin/>.
Second, it runs podchecker(1) over the files in B<bin/> and B<man/> 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, pkg add and pkg push
=item B<genocide_collected> I<package>
Revert the actions of populate_collected. Called with pkg delete.
=item B<update_provides> I<package>
Walks through the directories in B<provides> and executes the post-update hooks
of the corresponding packages.
=back
=head1 AUTHOR
Daniel Friesel <derf@derf.homelinux.org>
=head1 LICENSE
0. You just DO WHAT THE FUCK YOU WANT TO.
=head1 SEE ALSO
checklinks(1), pkg(1)
=cut
vim:ft=pod
|
