1$OpenBSD: PackingElement.pod,v 1.1 2020/12/20 15:30:58 daniel Exp $
2
3=head1 NAME
4
5OpenBSD::PackingElement - C<pkg_add(1)> packing-elements object hierarchy
6
7=head1 SYNOPSIS
8
9    package OpenBSD::PackingElement;
10    sub method
11    {
12    }
13
14    package OpenBSD::PackingElement::Depend;
15    sub method
16    {
17    	my ($self, @args) = @_;
18	# do something
19    }
20
21    package main;
22    use OpenBSD::PackingList;
23
24    $plist = OpenBSD::PackingList->fromfile($filename);
25    $plist->visit('method', @args);
26
27=head1 DESCRIPTION
28
29C<OpenBSD::PackingElement> is the base class for all elements in a
30packing-list (see L<OpenBSD::PackingList(3p)> and C<pkg_create(1)>).
31
32Manipulation of packing-lists mostly occurs through visitor patterns
33such as C<OpenBSD::PackingList::visit>: client code defines a method for
34each relevant class in the hierarchy and calls C<$plist-E<gt>visit('method')>
35to perform the processing.
36
37Most actual objects have one property: their C<name>.
38
39=over 4
40
41=item ::Meta
42
43base class for all meta information that can be reordered at will.
44
45=over 4
46
47=item ::Unique
48
49meta information with uniqueness properties.
50
51=over 4
52
53=item ::Arch
54
55architecture requirements.
56
57=item ::ExtraInfo
58
59some unique properties, like C<PKGPATH> and allowed-for-ftp status.
60
61=item ::Name
62
63the package name.
64
65=item ::LocalBase
66
67the local base for the package.
68
69=item ::NoDefaultConflict
70
71special annotation that package should not have any C<stem-*> conflict marker.
72
73=item ::SpecialFile
74
75special files like the package description or install script.
76
77=over 4
78
79=item ::FCONTENTS
80
81contents file.
82
83=item ::FDESC
84
85package description.
86
87=item ::DisplayFile
88
89abstract class for special files that can be displayed.
90provides method C<prepare($state)> to display the file.
91
92=over 4
93
94=item ::FDISPLAY
95
96message displayed during package install.
97
98=item ::FUNDISPLAY
99
100message displayed during package uninstall.
101
102=back
103
104=back
105
106=back
107
108=item ::Option
109
110factory for C<@option>
111
112=item ::Comment
113
114comments in the packing-lists. The constructor is actually a factory,
115since some comments evolve to some other class.
116
117=item ::CVSTag
118
119special class of comments that get reordered to the front of packing-lists.
120
121=item ::Depend
122
123all dependency information.
124
125=over 4
126
127=item ::Wantlib
128
129shared library needed for the package.
130
131=item ::Dependency
132
133package needed, with the following properties: C<pkgpath> is the path
134used to create the dependency, C<pattern> is the L<OpenBSD::PkgSpec(3p)>
135pattern used to match the dependency, C<def> is the default value of
136the dependency computed during build, to use for comparing package signatures
137and to fulfill default dependencies.
138
139=back
140
141=item ::Conflict
142
143conflict information.
144
145=back
146
147=item ::Annotation
148
149stuff that doesn't really exist as objects, but is used to add
150properties to objects.
151
152=over 4
153
154=item ::Ignore
155
156mark next object as ignored.
157
158=item ::sha
159
160mark last file with a checksum.
161
162=item ::size
163
164mark last file with a size.
165
166=item ::symlink
167
168mark last file as a symlink.
169
170=item ::hardlink
171
172mark last file as a hardlink.
173
174=item ::temp
175
176mark last file with a temporary name. Used during extraction of
177packages for replacement.
178
179=back
180
181=item ::Object
182
183somewhat concrete elements in packing-lists.
184This is the base class for objects with a location in the filesystem.
185It defineds method C<fullname>, to access the complete name of the object.
186
187Note that all objects with file names use relative names except for
188C<::Extra>, C<::Sample> and C<::Sampledir>
189
190=over 4
191
192=item ::FileObject
193
194abstract class corresponding to files and directories.
195Default constructor depends on a C<dirclass> property, that may
196create objects from another class if their name ends with a C</>.
197The full object name is normally computed relative to the current
198working directory as set in C<::State>.
199
200=over 4
201
202=item ::FileBase
203
204abstract class for files.
205
206=over 4
207
208=item ::File
209
210actual file objects present in the packing-list.
211
212=item ::InfoFile
213
214GNU info file objects.
215
216=item ::Shell
217
218files with shell properties.
219
220=item ::Manpage
221
222man pages.
223
224=item ::Lib
225
226shared library files.
227
228=item ::Sample
229
230file objects not present in the packing-list.
231
232=for comment  ::Extra and ::Extradir intentionally not documented yet.
233
234=back
235
236=item ::DirlikeObject
237
238abstract class for directories.
239
240=over 4
241
242=item ::DirRm
243
244deprecated.
245
246=item ::DirBase
247
248=over 4
249
250=item ::Dir
251
252normal directory, with specialized versions.
253
254=over 4
255
256=item ::Infodir
257
258directory holds GNU info files.
259
260=item ::Fontdir
261
262directory holds X11 fonts.
263
264=item ::Mandir
265
266directory is the root of a set of manpages.
267
268=item ::Sampledir
269
270directory is used to hold configuration files or similar objects.
271
272=back
273
274=back
275
276=back
277
278=back
279
280=item ::Action
281
282stuff that performs some action during addition/removal of package.
283
284=over 4
285
286=item ::NewAuth
287
288=over 4
289
290=item ::NewUser
291
292user that needs to be created for the package to work.
293
294=item ::NewGroup
295
296group that needs to be created for the package to work.
297
298=back
299
300=item ::ExeclikeAction
301
302escape mechanism for embedded code that needs to be run.
303
304=over 4
305
306=item ::Exec
307
308code to run during installation.
309
310=item ::Unexec
311
312code to run during deinstallation.
313
314=item ::Extraunexec
315
316extra code to run during deinstallation with -c.
317
318=back
319
320=back
321
322=item ::State
323
324annotation-like stuff that can't be easily moved around because it influences
325surrounding objects (mostly derived from C<::FileObject>).
326
327=over 4
328
329=item ::Cwd
330
331change the current working directory.
332
333=item ::Owner
334
335change the current file owner.
336
337=item ::Group
338
339change the current file group.
340
341=item ::Mode
342
343change the current file mode.
344
345=back
346
347=back
348
349=back
350
351=head1 CAVEATS
352
353Some aspects of this API are likely to change in the future, although the
354basic class hierarchy is now more or less worked out.
355