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