Ticket #718: parrot_manifest_destiny_documentation.patch
File parrot_manifest_destiny_documentation.patch, 11.9 KB (added by wayland, 13 years ago) |
---|
-
tools/dev/install_dev_files.pl
46 46 47 47 =back 48 48 49 =head 2 See Also49 =head1 SEE ALSO 50 50 51 See F< tools/dev/install_files.pl> for a detailed description of the MANIFEST51 See F<lib/Parrot/Manifest.pm> for a detailed description of the MANIFEST 52 52 format. 53 53 54 54 =cut -
tools/dev/install_files.pl
46 46 47 47 =back 48 48 49 =head2 MANIFEST Format50 51 The format of the MANIFEST (currently MANIFEST and MANIFEST.generated52 are used) is:53 54 source_path <whitespace> [package]meta1,meta2,...55 56 or you may optionally specify a different destination path:57 58 source_path <whitespace> [package]meta1,meta2,... <whitespace> destination59 60 Additionally, there may be a * in front of the whole line to designate61 a generated file:62 63 source_path <whitespace> *[package]meta1,meta2,... <whitespace> destination64 65 The square brackets around C<package> are literal. C<package> gives66 the name of the RPM that the given file will be installed for, and is67 only used by this script to skip files that are not members of any68 package.69 70 The various meta flags recognized are:71 72 =over 473 74 =item C<doc>75 76 Tag this file with %doc in the RPM, and omit the leading path (because77 rpm will put it into a directory of its choosing)78 79 =item C<include>80 81 Write this file to the location given by the C<--includedir> option82 83 =item C<lib>84 85 Write this file to the location given by the C<--libdir> option86 87 =item C<bin>88 89 Write this file to the location given by the C<--bindir> option90 91 =back92 93 The optional C<destination> field provides a general way to change94 where a file will be written to. It will be applied before any95 metadata tags.96 97 Example: if this line is in the MANIFEST.generated file98 99 languages/snorkfest/snork-compile [main]bin100 101 and the --bindir=/usr/parroty/bin, then the generated102 parrot-<VERSION>-1.<arch>.rpm file will contain the file103 /usr/parroty/bin/snork-compile.104 105 49 =head1 SEE ALSO 106 50 51 See F<lib/Parrot/Manifest.pm> for a detailed description of the MANIFEST 52 format. 53 107 54 F<tools/dev/mk_manifests.pl> 108 55 109 56 =cut -
lib/Parrot/Manifest.pm
1 1 # $Id$ 2 2 # Copyright (C) 2007, Parrot Foundation. 3 3 4 =head1 NAME 5 6 Parrot::Manifest - Re-create MANIFEST and MANIFEST.SKIP 7 8 =head1 SYNOPSIS 9 10 use Parrot::Manifest; 11 12 $mani = Parrot::Manifest->new($0); 13 14 $manifest_lines_ref = $mani->prepare_manifest(); 15 $need_for_files = $mani->determine_need_for_manifest($manifest_lines_ref); 16 $mani->print_manifest($manifest_lines_ref) if $need_for_files; 17 18 $print_str = $mani->prepare_manifest_skip(); 19 $need_for_skip = $mani->determine_need_for_manifest_skip($print_str); 20 $mani->print_manifest_skip($print_str) if $need_for_skip; 21 22 $print_str = $mani->prepare_gitignore(); 23 $mani->print_gitignore($print_str) if $need_for_skip; 24 25 =cut 26 4 27 package Parrot::Manifest; 5 28 use strict; 6 29 use warnings; 7 30 use Carp; 8 31 32 =head1 METHODS 33 34 =head2 new 35 36 $mani = Parrot::Manifest->new({ 37 script => $0, 38 file => $filename, 39 skip => $skipfilename, 40 gitignore => $gitignoresfilename, 41 }) 42 43 Creates a Parrot::Manifest object by asking "svn status" for verbose output, and parsing 44 the results. 45 46 $filename is the name of the file that the manifest will eventually be written to, and 47 defaults to MANIFEST. $skipfilename is the name of the file that will hold the list of 48 files to be skipped, and defaults to MANIFEST.SKIP. gitignore contains the same 49 information as MANIFEST.SKIP in a different format. It defaults to '.gitignore'. The 50 script parameter is the name of the current script, for use in messages. 51 52 =cut 53 # ...the results go into $self->{dirs} and $self->{versioned_files} 9 54 sub new { 10 55 my $class = shift; 11 56 my $argsref = shift; … … 55 100 return $self; 56 101 } 57 102 103 =head2 prepare_manifest 104 105 $manifest_lines_ref = $mani->prepare_manifest(); 106 107 Prepares the manifest from the read in by the new() method, and returns a hash of the 108 files. The keys of the hash are the filenames, and the values are strings representing 109 the package and a list of the meta flags. 110 111 =cut 58 112 sub prepare_manifest { 59 113 my $self = shift; 60 114 … … 66 120 return \%manifest_lines; 67 121 } 68 122 123 =head2 determine_need_for_manifest 124 125 $need_for_files = $mani->determine_need_for_manifest($manifest_lines_ref); 126 127 Determines the need for the manifest. The checks are: 128 129 * If there's no manifest yet, we need one 130 * If there's a difference between what's already there and what's in the 131 list, we need a new one 132 133 The return value is 1 of needed, and undef otherwise. The value passed in is the hash 134 as returned from eg. prepare_manifest. 135 136 =cut 69 137 sub determine_need_for_manifest { 70 138 my $self = shift; 71 139 my $proposed_files_ref = shift; … … 84 152 $different_patterns_count ? return 1 : return; 85 153 } 86 154 155 =head2 print_manifest 156 157 $mani->print_manifest($manifest_lines_ref) if $need_for_files; 158 159 Writes the manifest to a file. The example above does it only if an update is needed. 160 161 =cut 162 87 163 my $text_file_coda = <<'CODA'; 88 164 # Local variables: 89 165 # mode: text … … 101 177 # 102 178 # generated by $self->{script} $self->{time} UT 103 179 # 104 # See tools/dev/install_files.pl for documentation on the105 # format of this file.180 # See below for documentation on the format of this file. 181 # 106 182 # See docs/submissions.pod on how to recreate this file after SVN 107 183 # has been told about new or deleted files. 108 184 END_HEADER … … 119 195 return 1; 120 196 } 121 197 198 # Gets the package and the meta flags for the given file. This function does it based on 199 # the directory the file is in. If a particular file is needed, then _get_special (below) 200 # provides that functionality. 122 201 sub _get_manifest_entry { 123 202 my $file = shift; 124 203 … … 156 235 return $loc; 157 236 } 158 237 238 # See comments for _get_manifest_entry, above 159 239 sub _get_special { 160 240 my %special = qw( 161 241 LICENSE [main]doc … … 190 270 return \%special; 191 271 } 192 272 273 # Gets files currently listed in manifest, and returns a hash 193 274 sub _get_current_files { 194 275 my $self = shift; 195 276 … … 211 292 return \%current_files; 212 293 } 213 294 295 =head2 prepare_manifest_skip 296 297 $print_str = $mani->prepare_manifest_skip(); 298 299 Gets a list of the files that SVN ignores, and returns a string that can be put into 300 MANIFEST.SKIP. 301 302 =cut 214 303 sub prepare_manifest_skip { 215 304 my $self = shift; 216 305 … … 219 308 return $self->_compose_manifest_skip($ignores_ref); 220 309 } 221 310 311 =head2 prepare_gitignore 312 313 $print_str = $mani->prepare_gitignore(); 314 315 Gets a list of the files that SVN ignores, and then writes it to the .gitignore file. 316 317 =cut 318 222 319 sub prepare_gitignore { 223 320 my $self = shift; 224 321 … … 227 324 return $self->_compose_gitignore($ignores_ref); 228 325 } 229 326 327 =head2 determine_need_for_manifest_skip 328 329 $need_for_skip = $mani->determine_need_for_manifest_skip($print_str); 330 331 Determines whether MANIFEST.SKIP is needed. The tests used are: 332 333 * If the file doesn't exist, we need one 334 * If the proposed and existing contents differ, we need one 335 336 =cut 337 230 338 sub determine_need_for_manifest_skip { 231 339 my $self = shift; 232 340 my $print_str = shift; … … 249 357 } 250 358 } 251 359 360 =head2 print_manifest_skip 361 362 $mani->print_manifest_skip($print_str) if $need_for_skip; 363 364 Writes MANIFEST.SKIP to a file. The example above does it only if needed. 365 366 =cut 252 367 sub print_manifest_skip { 253 368 my $self = shift; 254 369 my $print_str = shift; … … 263 378 return 1; 264 379 } 265 380 381 =head2 print_gitignore 382 383 $mani->print_gitignore($print_str) if $need_for_skip; 384 385 Writes the .gitignore file. The example above does so only if needed. 386 387 =cut 266 388 sub print_gitignore { 267 389 my $self = shift; 268 390 my $print_str = shift; … … 277 399 return 1; 278 400 } 279 401 402 # Gets a list of files that SVN ignores 280 403 sub _get_ignores { 281 404 my $self = shift; 282 405 … … 304 427 return \%ignores; 305 428 } 306 429 430 # Turns the list of ignored files into .gitignore format 307 431 sub _compose_gitignore { 308 432 my $self = shift; 309 433 my $ignores_ref = shift; … … 336 460 return $print_str; 337 461 } 338 462 463 # Turns list of ignored files into MANIFEST.SKIP format 339 464 sub _compose_manifest_skip { 340 465 my $self = shift; 341 466 my $ignore_ref = shift; … … 377 502 return $print_str; 378 503 } 379 504 505 # Gets a list of the currently skipped files from MANIFEST.SKIP 380 506 sub _get_current_skips { 381 507 my $self = shift; 382 508 … … 394 520 return \%current_skips; 395 521 } 396 522 523 # Gets list of files we're proposing to skip 397 524 sub _get_proposed_skips { 398 525 my $print_str = shift; 399 526 … … 410 537 411 538 1; 412 539 413 #################### DOCUMENTATION #################### 540 =head1 MANIFEST FORMAT 414 541 415 =head1 NAME 542 The format of the MANIFEST (currently MANIFEST and MANIFEST.generated 543 are used) is: 416 544 417 Parrot::Manifest - Re-create MANIFEST and MANIFEST.SKIP 545 source_path <whitespace> [package]meta1,meta2,... 418 546 419 =head1 SYNOPSIS 547 or you may optionally specify a different destination path: 420 548 421 use Parrot::Manifest;549 source_path <whitespace> [package]meta1,meta2,... <whitespace> destination 422 550 423 $mani = Parrot::Manifest->new($0); 551 Additionally, there may be a * in front of the whole line to designate 552 a generated file: 424 553 425 $manifest_lines_ref = $mani->prepare_manifest(); 426 $need_for_files = $mani->determine_need_for_manifest($manifest_lines_ref); 427 $mani->print_manifest($manifest_lines_ref) if $need_for_files; 554 source_path <whitespace> *[package]meta1,meta2,... <whitespace> destination 428 555 429 $print_str = $mani->prepare_manifest_skip(); 430 $need_for_skip = $mani->determine_need_for_manifest_skip($print_str); 431 $mani->print_manifest_skip($print_str) if $need_for_skip; 556 The square brackets around C<package> are literal. C<package> gives 557 the name of the RPM that the given file will be installed for, and is 558 only used by this script to skip files that are not members of any 559 package. 432 560 433 $print_str = $mani->prepare_gitignore(); 434 $mani->print_gitignore($print_str) if $need_for_skip; 561 The various meta flags recognized are: 435 562 563 =over 4 564 565 =item C<doc> 566 567 Tag this file with %doc in the RPM, and omit the leading path (because 568 rpm will put it into a directory of its choosing) 569 570 =item C<include> 571 572 Write this file to the location given by the C<--includedir> option 573 574 =item C<lib> 575 576 Write this file to the location given by the C<--libdir> option 577 578 =item C<bin> 579 580 Write this file to the location given by the C<--bindir> option 581 582 =back 583 584 The optional C<destination> field provides a general way to change 585 where a file will be written to. It will be applied before any 586 metadata tags. 587 588 Example: if this line is in the MANIFEST.generated file 589 590 languages/snorkfest/snork-compile [main]bin 591 592 and the --bindir=/usr/parroty/bin, then the generated 593 parrot-<VERSION>-1.<arch>.rpm file will contain the file 594 /usr/parroty/bin/snork-compile. 595 436 596 =head1 SEE ALSO 437 597 438 598 F<tools/dev/mk_manifest_and_skip.pl>. … … 449 609 450 610 =cut 451 611 452 # Local Variables:453 # mode: cperl454 # cperl-indent-level: 4455 # fill-column: 100456 # End:457 # vim: expandtab shiftwidth=4: