1$OpenBSD: PackingList.pod,v 1.1 2020/12/20 15:30:58 daniel Exp $
2
3=head1 NAME
4
5OpenBSD::PackingList - C<pkg_add(1)> packing-list manipulations
6
7=head1 SYNOPSIS
8
9    use OpenBSD::PackingList;
10    # different methods to create packing-lists
11    my $p1 = OpenBSD::PackingList->new;		# empty
12    my $p2 = OpenBSD::PackingList->read($fh);
13    my $p3 = OpenBSD::PackingList->fromfile($filename);
14    my $p4 = OpenBSD::PackingList->fromfile(\$scalar);
15    my $p5 = OpenBSD::PackingList->from_installation($pkgname);
16
17    # writing packing-lists
18    $p2->write($fh);
19    $p3->tofile($filename);
20    $p4->to_installation;
21    $p4->to_cache;
22
23    # building up packing-lists
24    OpenBSD::PackingElement::SUBCLASS->add($plist, @args);
25    my $o = OpenBSD::PackingElement::SUBCLASS->new(@args);
26    $o->add_object($plist);
27
28    # tests and access
29    $b = $p2->has($name);
30    $b = $p2->get($name);
31    # frequent accesses
32    print $p3->pkgname, $p3->localbase, "\n";
33
34    # processing packing-lists
35    $p4->visit('method', @args);
36
37    # auto visit
38    $p4->method(@args);
39
40    # signatures
41    if ($p3->signature eq $p4->signature) {
42    }
43
44=head1 DESCRIPTION
45
46C<OpenBSD::PackingList> is the only supported interface for access to
47packing-list information. It includes conversion methods from an external
48textual representation (file) into an internal structured representation.
49Basically, a packing-list is a collection of strongly-typed objects. Some
50of these objects are just properties of the package (like the package name,
51or dependencies), some objects have long lists of properties (files come
52with MD5 checksums, sizes, or linknames), some objects represent state
53information (like file modes) and must be kept in the proper order.
54The C<OpenBSD::PackingList> class handles all that.
55
56Packing-lists can be obtained using the following methods: from an
57opened file handle using C<OpenBSD::PackingList-E<gt>read($fh)>, from
58an existing file using C<OpenBSD::PackingList-E<gt>fromfile($filename)>,
59from a scalar in memory using C<OpenBSD::PackingList-E<gt>fromfile(\$scalar)>,
60or from an installed package using
61C<OpenBSD::PackingList-E<gt>from_installation($pkgname)>.
62
63Since building a full packing-list is a complex operation and can consume
64a large amount of memory, those methods may take an extra argument in order to
65obtain partial packing-lists with only some information:
66
67=over 16
68
69=item SharedItemsOnly
70
71read only stuff that may be shared between packages, e.g., new users,
72groups and directories.
73
74=item LibraryOnly
75
76read only shared library entries.
77
78=item FilesOnly
79
80read only files without the associated annotations like size or MD5.
81
82=item DependOnly
83
84read only dependency information.
85
86=item ExtraInfoOnly
87
88read only the extra information field.
89
90=item UpdateInfoOnly
91
92read only what is needed to decide to update a package.
93
94=item PrelinkStuffOnly
95
96read only what is need to figure out all binary/library information, e.g.,
97libraries, dependencies and binaries.
98
99=back
100
101A complete packing-list C<$plist> may be written to disk using the
102following methods:
103C<$plist-E<gt>write($fh)> will write a packing-list to an
104opened file handle C<$fh>, C<$plist-E<gt>tofile($filename)> will
105write a packing-list to a file named C<$filename>, and
106C<$plist-E<gt>to_installation> will write a packing-list during
107registration of a package.
108
109In addition C<$plist-E<gt>to_cache> will register enough
110information from a package to let the framework believe the package has
111been installed. This is used for the simulation modes of C<pkg_add(1)>
112and friends.
113
114Since a packing-list is structured information, reading a packing-list from
115the disk and writing it back offers no guarantee the information will remain
116in the same order.  It is a good way to validate packing-lists and normalize
117them, though.
118
119Building packing-lists entails cooperation with C<OpenBSD::PackingElement>.
120Packing-lists are usually built by adding objects from an
121C<OpenBSD::PackingElement> subclass to the packing-list, either with
122the C<add> constructor:
123C<OpenBSD::PackingElement::SUBCLASS-E<gt>add($plist, $args)>, which builds
124a packing element and adds it to the packing-list in one operation, or with
125the C<add_object> method, which takes an existing packing element and adds it
126to the packing-list (note that C<add_object> only makes sense for subclasses
127of C<OpenBSD::PackingElement::Object>).
128See L<OpenBSD::PackingElement> for more details.
129
130C<$plist-E<gt>pkgname> retrieves a packing-list name (mandatory).
131C<$plist-E<gt>signature> retrieves a packing-list full signature, composed
132of the package name and dependency information.
133
134C<$plist-E<gt>visit($method, @args)> is a visitor pattern, calling
135C<method(@args)> on each element of the packing-list in a specific order.
136
137As a feature, if C<OpenBSD::PackingElement-E<gt>can(method)>,
138C<$plist-E<gt>method(@args)> will be turned into a visitor call automatically.
139