diff options
Diffstat (limited to 'usr.sbin')
| -rw-r--r-- | usr.sbin/pkg_add/pod/OpenBSD::PackingList.pod | 104 |
1 files changed, 103 insertions, 1 deletions
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::PackingList.pod b/usr.sbin/pkg_add/pod/OpenBSD::PackingList.pod index fd72cece141..24cb9f0a561 100644 --- a/usr.sbin/pkg_add/pod/OpenBSD::PackingList.pod +++ b/usr.sbin/pkg_add/pod/OpenBSD::PackingList.pod @@ -1,4 +1,4 @@ -$OpenBSD: OpenBSD::PackingList.pod,v 1.1 2005/02/28 13:08:41 espie Exp $ +$OpenBSD: OpenBSD::PackingList.pod,v 1.2 2005/03/02 20:10:25 espie Exp $ =head1 NAME @@ -6,4 +6,106 @@ OpenBSD::PackingList - C<pkg_add(1)> packing-list manipulations =head1 SYNOPSIS + use OpenBSD::PackingList; + # different methods to create packing-lists + my $p1 = OpenBSD::PackingList->new(); # empty + my $p2 = OpenBSD::PackingList->read($fh); + my $p3 = OpenBSD::PackingList->fromfile($filename); + my $p4 = OpenBSD::PackingList->from_installation($pkgname); + + # writing packing-lists + $p2->write($fh); + $p3->tofile($filename); + $p4->to_installation(); + $p4->to_cache(); + + # building up packing-lists + OpenBSD::PackingElement::SUBCLASS->add($plist, @args); + my $o = OpenBSD::PackingElement::SUBCLASS->new(@args); + $o->add_object($plist); + + # tests and access + $b = $p2->has($name); + $b = $p2->get($name); + # frequent accesses + print $p3->pkgname(), $p3->pkgbase(), "\n"; + + # processing packing-lists + $p4->visit('method', @args); + =head1 DESCRIPTION + +C<OpenBSD::PackingList> is the only supported interface for access to +packing-list information. It includes conversion methods from an external +textual representation (file) into an internal structured representation. +Basically, a packing-list is a collection of strongly-typed objects. Some +of these objects are just properties of the package (like the package name, +or dependencies), some objects have long lists of properties (files come +with MD5 checksums, sizes, or linknames), some objects represent state +information (like file modes) and must be kept in the proper order. +The C<OpenBSD::PackingList> class handles all that. + +Packing-lists can be obtained using the following methods: from an +opened file handle using C<OpenBSD::PackingList-E<gt>read($fh)>, from +an existing file using C<OpenBSD::PackingList-E<gt>fromfile($filename)>, +or from an installed package using +C<OpenBSD::PackingList-E<gt>from_installation($pkgname)>. + +Since building a full packing-list is a complex operation and can consume +a large amount of memory, those methods may take an extra argument in order to +obtain partial packing-lists with only some information: + +=over 16 + +=item SharedItemsOnly + +read only stuff that may be shared between packages, e.g., new users, +groups and directories. + +=item LibraryOnly + +read only shared library entries. + +=item FilesOnly + +read only files without the associated annotations like size of MD5. + +=item DependOnly + +read only dependency information. + +=item ExtraInfoOnly + +read only the extra information field. + +=back + +A complete packing-list C<$plist> may be written to disk using the +following methods: +C<$plist-E<gt>write($fh)> will write a packing-list to an +opened file handle C<$fh>, C<$plist-E<gt>tofile($filename)> will +write a packing-list to a file named C<$filename>, and +C<$plist-E<gt>to_installation()> will write a packing-list during +registration of a package. + +In addition C<$plist-E<gt>to_cache()> will register enough +information from a package to let the framework believe the package has +been installed. This is used for the simulation modes of C<pkg_add(1)> +and friends. + +Since a packing-list is structured information, reading a packing-list from +the disk and writing it back offers no guarantee the information will remain +in the same order. It is a good way to validate packing-lists and normalize +them, though. + +Building packing-lists entails cooperation with C<OpenBSD::PackingElement>. +Packing-lists are usually built by adding objects from an +C<OpenBSD::PackingElement> subclass to the packing-list, either with +the C<add> constructor: +C<OpenBSD::PackingElement::SUBCLASS-E<gt>add($plist, $args)>, which builds +a packing element and adds it to the packing-list in one operation, or with +the C<add_object> method, which takes an existing packing element and adds it +to the packing-list (note that C<add_object> only makes sense for subclasses +of C<OpenBSD::PackingElement::Object>). +See L<OpenBSD::PackingElement> for more details. + |