tools/vergen

   1 #!/usr/bin/env perl
   2 #
   3 # Written by Martin Bartosch for the OpenXPKI project 2006
   4 # Copyright (c) 2006 by The OpenXPKI Project
   5 # $Revision: 589 $
   6 #
   7
   8 use warnings;
   9 use strict;
  10 use English;
  11
  12 use Data::Dumper;
  13
  14 use Pod::Usage;
  15 use Getopt::Long;
  16 use POSIX;
  17 use File::Spec;
  18 use Config::Std;
  19 use Cwd;
  20
  21 # use Smart::Comments;
  22
  23 my %params;
  24 my %config;
  25
  26
  27 my $svn = 'svn';
  28 my $git = 'git';
  29 my $git_svn = 'git-svn';
  30
  31 my $revision_info;
  32 my $mapping_of;
  33 my $format_of;
  34 my $saved_directory;
  35
  36 ###########################################################################
  37
  38 sub slurp {
  39     my $filename = shift;
  40
  41     return unless (defined $filename && -r $filename);
  42
  43     my $result = do {
  44         open my $HANDLE, '<', $filename or return;
  45         if (! $HANDLE) {
  46             die "Could not open file '$filename' for reading. Stopped";
  47         }
  48         # slurp mode
  49         local $INPUT_RECORD_SEPARATOR;     # long version of $/
  50         <$HANDLE>;
  51     };
  52     return $result;
  53 }
  54
  55
  56 sub get_revision_info {
  57     my $result = {};
  58
  59     # first get SVN revision information
  60     my $fh;
  61     if (! open $fh, "$svn info -R 2>/dev/null |") {
  62         return $result;
  63     }
  64
  65   SVN_INFO:
  66     while (<$fh>) {
  67         chomp;
  68         if (m{ \A Revision: \s* (\d+) }xms) {
  69             $result->{revision} = $1;
  70             next SVN_INFO;
  71         }
  72         if (m{ \A Last\ Changed\ Rev: \s* (\d+) }xms) {
  73             if (! exists $result->{'last-changed-revision'} ||
  74                 ($1 > $result->{'last-changed-revision'})) {
  75                 $result->{'last-changed-revision'} = $1;
  76             }
  77         }
  78     }
  79     close $fh;
  80
  81     # check if we are running in a git checkout
  82     # getting revision info from SVN did not work, try git
  83     if ( (`which $git 2>/dev/null`) && (`$git branch 2>/dev/null`) ) {
  84         # try via git-svn...
  85         if (! exists $result->{revision}) {
  86             # try to get revision from git-svn
  87             my $last_log = `$git_svn log --oneline --limit 1 2>/dev/null`;
  88             my ($revision) = ($last_log =~ m{\A r(\d+)\ \|\ .*}xms);
  89             if (defined $revision) {
  90                 $result->{revision} = $revision;
  91             }
  92         }
  93
  94         # ... and via plain git
  95         if (! exists $result->{revision}) {
  96             # revision could not be obtained by git-svn
  97             # reason may be that this repository does not rebase via git-svn,
  98             # but rather pulls from another repository. assume that the
  99             # svn revision information is available in git full text logs.
 100
 101             open $fh, qq{ $git log --pretty=email | };
 102           GITLOGLINE:
 103             while (my $line = <$fh>) {
 104                 chomp $line;
 105                 # first git-svn-id line encountered wins
 106                 if ($line =~ m{ \A git-svn-id: .*? @(\d+) \s+ }xms) {
 107                     $result->{revision} = $1;
 108                     last GITLOGLINE;
 109                 }
 110             }
 111             close $fh;
 112         }
 113         # fake last-changed-revision
 114         $result->{'last-changed-revision'} ||= $result->{revision};
 115
 116         # get git commit hashes
 117         $result->{'git-abbreviated-commit-hash'} = `$git show-ref -h -s --abbrev HEAD`;
 118         chomp $result->{'git-abbreviated-commit-hash'};
 119
 120         $result->{'git-commit-hash'} = `$git show-ref -h -s HEAD`;
 121         chomp $result->{'git-commit-hash'};
 122
 123         # get git tag information
 124         open $fh, qq{ $git name-rev --tags HEAD | };
 125       GITLOGLINE:
 126         while (my $line = <$fh>) {
 127             chomp $line;
 128             if ($line =~ m{ \A HEAD \s+ (?: .*?/)?(.*) }xms) {
 129                 if ($1 ne 'undefined') {
 130                     $result->{'git-tag'} ||= $1;
 131                 }
 132             }
 133         }
 134         close $fh;
 135     }
 136
 137     return $result;
 138 }
 139
 140
 141 sub upwards_find_file {
 142     my $filename = shift;
 143
 144     return undef unless defined $filename;
 145
 146     my $dir = getcwd;
 147
 148   DIRECTORY:
 149     while ($dir ne '/') {
 150         if (exists $params{verbose}) {
 151             print STDERR "* scanning $dir for $filename\n";
 152         }
 153
 154         my $absolute_filename = File::Spec->catfile($dir, $filename);
 155         if (-e $absolute_filename) {
 156             if (exists $params{verbose}) {
 157                 print STDERR "* found $absolute_filename\n";
 158             }
 159             return $absolute_filename;
 160         }
 161
 162         # one level up
 163         my @dirs = File::Spec->splitdir($dir);
 164         pop @dirs;
 165         $dir = File::Spec->catdir(@dirs);
 166     }
 167     return;
 168 }
 169
 170 sub expand_keyword {
 171     my $arg = shift;
 172
 173     my $last_arg = "";
 174     while ($last_arg ne $arg) {
 175         $last_arg = $arg;
 176         foreach my $keyword (keys %{$mapping_of->{keyword}}) {
 177             if ($arg =~ m{ $keyword }xms) {
 178                 my $value = $mapping_of->{keyword}->{$keyword}->{entry}->{value};
 179                 if (! defined $value) {
 180                     die "Could not get value for keyword '$keyword'. Stopped";
 181                 }
 182                 $arg =~ s{ $keyword }{$value}xmsg;
 183             }
 184         }
 185         $arg = strftime($arg, gmtime(time));
 186     }
 187
 188     return $arg;
 189 }
 190
 191 ###########################################################################
 192
 193 # make sure that system output is not localized
 194 $ENV{LANG} = 'C';
 195
 196 GetOptions(\%params,
 197            qw(
 198               help|?
 199               man
 200               verbose
 201               format=s
 202               directory=s
 203               dump
 204               dumpformat=s
 205               )) or pod2usage(-verbose => 0);
 206
 207 pod2usage(-exitstatus => 0, -verbose => 2) if $params{man};
 208 pod2usage(-verbose => 1) if ($params{help});
 209
 210 if (defined $params{directory}) {
 211     $saved_directory = getcwd;
 212     if (! chdir $params{directory}) {
 213         die "Could not change to directory $params{directory}. Stopped";
 214     }
 215 }
 216
 217 my $def_file = upwards_find_file('.VERSION_DEFINITION');
 218
 219 if (! defined $def_file) {
 220     die "Could not find version definition file anywhere. Stopped";
 221 }
 222 read_config($def_file, %config);
 223
 224 if (exists $config{FORMAT_DEFINITIONS}) {
 225     $format_of = $config{FORMAT_DEFINITIONS};
 226     delete $config{FORMAT_DEFINITIONS};
 227 }
 228
 229 ### %config
 230 ### $format_of
 231
 232 COMPONENT:
 233 foreach my $component (keys %config) {
 234     ### $component...
 235
 236     # coerce keyword into arrayref
 237     if (defined $config{$component}->{keyword}) {
 238         if (ref $config{$component}->{keyword} eq '') {
 239             $config{$component}->{keyword} = [ $config{$component}->{keyword} ];
 240         }
 241     } else {
 242         die "No keyword defined for component $component. Stopped";
 243     }
 244
 245     # built-in components
 246     if ($component =~ m{ \A (?: revision |
 247                                 last-changed-revision |
 248                                 git-commit-hash |
 249                                 git-abbreviated-commit-hash |
 250                                 git-tag
 251                             ) \z }xms) {
 252         $revision_info ||= get_revision_info();
 253
 254         if (! scalar keys %{$revision_info}) {
 255             die "Could not determine revision info. (Hint: is svn installed and in path?)";
 256         }
 257
 258         $mapping_of->{component}->{$component} = {
 259             keyword => $config{$component}->{keyword},
 260             value   => $revision_info->{$component},
 261             type    => 'built-in',
 262         };
 263         next COMPONENT;
 264     }
 265
 266     my $optional = (defined $config{$component}{optional}
 267                     && ($config{$component}{optional} =~ m{ \A (?:yes|true|1) \z }ixms));
 268     ### $optional
 269
 270     if (! defined $config{$component}{filename}) {
 271         die "No 'filename' defined for component '$component'. Stopped";
 272     }
 273
 274     my $file = upwards_find_file($config{$component}{filename});
 275     my $content = '';
 276
 277     if (defined $file) {
 278         $content = slurp($file);
 279         if (! defined $content) {
 280             $content = '';
 281         }
 282         chomp $content;
 283     } else {
 284         if (! $optional) {
 285             die "Could not find version file '$config{$component}{filename}' for component '$component' upwards from here. Stopped";
 286         }
 287         $content = '';
 288     }
 289
 290     $mapping_of->{component}->{$component} = {
 291         keyword => $config{$component}->{keyword},
 292         value   => $content,
 293         type    => 'component',
 294     }
 295 }
 296
 297 # remap entries
 298 foreach my $component (keys %{$mapping_of->{component}}) {
 299     ### $component
 300     my $entry = $mapping_of->{component}->{$component};
 301     foreach my $keyword (@{ $mapping_of->{component}->{$component}->{keyword} }) {
 302         $mapping_of->{keyword}->{$keyword}->{component} = $component,
 303         $mapping_of->{keyword}->{$keyword}->{entry} = $entry,
 304     }
 305 }
 306
 307 ### $mapping_of
 308
 309 if (defined $params{format}) {
 310     my $format = $params{format};
 311
 312     if (exists $format_of->{$format}) {
 313         $format = $format_of->{$format};
 314     }
 315     my $value = expand_keyword($format);
 316
 317     eval "printf('%s', qq($value));";
 318 }
 319
 320 if (defined $params{'dump'}) {
 321     foreach my $component (keys %{$mapping_of->{component}}) {
 322         my $dumpformat = 'KEYWORD=VALUE\n';
 323         if (defined $params{dumpformat}) {
 324             $dumpformat = $params{dumpformat};
 325         }
 326
 327         my $keyword = $mapping_of->{component}->{$component}->{keyword}->[0];
 328         my $value   = expand_keyword($mapping_of->{keyword}->{$keyword}->{entry}->{value});
 329         my %vars = (
 330             KEYWORD => $keyword,
 331             VALUE   => $value,
 332         );
 333
 334         my @values = ();
 335
 336        MAKEFORMAT:
 337         while (1) {
 338             my ($item) = ($dumpformat =~ m{ (KEYWORD|VALUE) }xms);
 339             last MAKEFORMAT if (! defined $item);
 340             $dumpformat =~ s{ $item }{%s}xms;
 341             push @values, $vars{$item};
 342         }
 343         ### $dumpformat
 344         ### @values
 345
 346         eval "printf(qq($dumpformat), \@values);";
 347     }
 348 }
 349
 350 exit 0;
 351
 352 __END__
 353
 354 =head1 NAME
 355
 356 vergen - Version management tool
 357
 358 =head1 USAGE
 359
 360 vergen [options] COMMAND
 361
 362  Options:
 363    --help                brief help message
 364    --man                 full documentation
 365    --format <arg>        print version using format 'arg'
 366    --directory <dir>     pretend to be in directory 'dir'
 367    --dump                dump keyword assignments
 368    --dumpformat <string> use <string> as dump format
 369                          (default: KEYWORD=VALUE\n)
 370    --verbose             show details about information obtained
 371
 372 =head1 DESCRIPTION
 373
 374 B<vergen> is a tool that can help to maintain consistent version numbers
 375 in a project. If desired it uses Subversion and/or Git to determine
 376 revision control information.
 377
 378 Starting from the current directory, vergen searches upwards for its
 379 configuration file '.VERSION_DEFINITION' and reads the first file found
 380 (see B<The .VERSION_DEFINITION File> for a detailed description.)
 381 After the configuration file has been read, vergen again traverses the
 382 directory tree upwards from the current directory and searches for all
 383 file names defined in the version definition file. Once a file is found,
 384 its content is read and stored as the value for the corresponding component.
 385
 386 Components can arbitrarily be combined to 'formats'. A format consists
 387 of a string that may contain any number of custom and built-in component
 388 names.
 389 It is then possible to print the resulting version string using
 390 the --format option.
 391
 392 When used within a directory hierarchy under revision control via
 393 Subversion and/or Git, B<vergen> is able to obtain and use information about
 394 the current checkout.
 395
 396
 397 =head1 OPTIONS
 398
 399 =over 8
 400
 401 =item B<--format> arg
 402
 403 Print format string, using the version numbers obtained by vergen. The
 404 output format is determined by 'arg' and may either be a symbolic name
 405 referencing a format string in the FORMAT_DEFINITIONS section of
 406 the corresponding .VERSION_DEFINITION file or a custom string specifying
 407 the version number. You may use all keywords defined in .VERSION_DEFINITION
 408 and all conversion specifications as defined by strftime(3).
 409
 410 =item B<--directory> dir
 411
 412 Makes it possible to simulate calling vergen in another directory.
 413 This is identical to calling
 414
 415   ( cd <dir> && vergen ... )
 416
 417 =item B<--dump>
 418
 419 Dump all keyword definitions in a format that can be sources by sh.
 420
 421 =item B<--dumpformat> string
 422
 423 Use specified string as template for keyword dump. Defaults to
 424 'KEYWORD=VALUE\n'.
 425 Useful dump formats:
 426
 427   --dumpformat 'KEYWORD="VALUE"\n'
 428   --dumpformat 'export KEYWORD="VALUE"\n'
 429
 430 =item B<--verbose>
 431
 432 Show which files are processed for determination of the version number
 433 components.
 434
 435 =back
 436
 437 =head1 The .VERSION_DEFINITION File
 438
 439 The version definition file contains format and version number component
 440 definitions. It is split in a number of sections that define the composition
 441 of version numbers.
 442
 443 =head2 Format definition
 444
 445 The format definition section is started by the [FORMAT_DEFINITIONS] tag.
 446
 447 Example:
 448   [FORMAT_DEFINITIONS]
 449   simple: MAJOR.MINOR
 450   advanced: MAJOR.MINOR.RELEASE
 451
 452 This configuration defines two named formats called 'simple' and 'advanced'
 453 that can be used with the --format option. The value following the colon
 454 is used as the output format in this case.
 455
 456 =head2 Custom component definitions
 457
 458 Section names are interpreted as a custom version component
 459 definition.
 460 In order to create a custom version number component you should define
 461 the following keys:
 462
 463 =head3 filename
 464
 465 File name to use. vergen searches upwards from the current directory
 466 until it finds the specified file.
 467 The file contents will be assigned as the component value.
 468
 469 =head3 keyword
 470
 471 Symbolic name(s) describing the version component that can be used
 472 to reference its value. More than one keyword can be used for
 473 aliasing the component. Each of these keyword can be used to reference
 474 the component value. It is possible to use the keyword in a format (--format)
 475 or even in the contents of the version component files. The program resolves
 476 recursive references to keywords properly.
 477
 478 Only the first keyword defined is used for --dump.
 479
 480 =head3 optional
 481
 482 If set to 'yes' or 'true', this component is not mandatory.
 483
 484 =head2 Revision control built-ins
 485
 486 When called within a directory tree that is under version control by
 487 Subversion and/or Git it is possible to obtain certain information from the
 488 revision control system.
 489
 490 B<vergen> support Subversion-only operation, Subversion with Git (using
 491 git-svn to rebase the Subversion repository) and Git-only. Git-only mode
 492 also tries to guess Subversion version numbers from the Git log (e. g.
 493 when pulling from a Git repository that uses git-svn to rebase from
 494 Subversion).
 495
 496 =head3 Subversion built-ins
 497
 498 The following named sections are hardcoded
 499 and can be used to access Subversion information.
 500
 501 =head4 revision
 502
 503 'revision' expands to the global SVN revision number
 504
 505 =head4 last-changed-revision
 506
 507 'last-changed-revision' determines the highest "Last Changed Rev"
 508 below the current directory (recursively).
 509
 510
 511 =head3 Git built-ins
 512
 513 The following named sections are hardcoded and can be used to access Git
 514 version information (if current directory is inside a Git repository).
 515
 516 =head4 git-commit-hash
 517
 518 'git-commit-hash' expands to the Git commit hash for the current HEAD.
 519
 520 =head4 git-abbreviated-commit-hash
 521
 522 'git-abbreviated-commit-hash' expands to the abbreviated commit hash.
 523
 524 =head4 git-tag
 525
 526 'git-tag' expands to the first Git tag name found for the current HEAD,
 527 undefined if the current HEAD is untagged.
 528
 529 =head1 Examples
 530
 531 =head2 .VERSION_DEFINITION
 532
 533   # Format definitions
 534   [FORMAT_DEFINITIONS]
 535   version: MAJOR.MINOR.RELEASESUFFIX\n
 536   daily_snapshot: %F-MAJOR.MINOR.RELEASESUFFIX\n
 537   git-commit: MAJOR.MINOR.GIT_TAG
 538
 539   # Built-in components
 540   [revision]
 541   keyword:          SVN_REVISION
 542
 543   [last-changed-revision]
 544   keyword:          SVN_LAST_CHANGED_REVISION
 545
 546   [git-commit-hash]
 547   keyword:          GIT_COMMIT_HASH
 548
 549   [git-abbreviated-commit-hash]
 550   keyword:          GIT_ABBREVIATED_COMMIT_HASH
 551
 552   [git-tag]
 553   keyword:          GIT_TAG
 554   optional:          yes
 555
 556   # Custom components
 557   [major]
 558   filename:         .VERSION_MAJOR
 559   keyword:          MAJOR
 560
 561   [minor]
 562   filename:         .VERSION_MINOR
 563   keyword:          MINOR
 564
 565   [release]
 566   filename:         .VERSION_RELEASE
 567   keyword:          RELEASE
 568
 569   [suffix]
 570   filename:         .VERSION_SUFFIX
 571   keyword:          SUFFIX
 572   optional:         yes
 573
 574
 575 =head2 Invocation
 576
 577 Using the above configuration file:
 578
 579   vergen --format daily_snapshot
 580   vergen --format MAJOR.MINOR
 581   vergen --dump