diff options
Diffstat (limited to 'code/unix')
| -rwxr-xr-x | code/unix/pcons-2.3.1 | 7911 |
1 files changed, 0 insertions, 7911 deletions
diff --git a/code/unix/pcons-2.3.1 b/code/unix/pcons-2.3.1 deleted file mode 100755 index 550297f..0000000 --- a/code/unix/pcons-2.3.1 +++ /dev/null @@ -1,7911 +0,0 @@ -#!/usr/bin/env perl - -# -# Revision history: -# ----------------- -# July 2001, Thomas Gleerup <tgl@oticon.dk> -# 1) pcons-1.6 (John Erickson, August 1999) merged into cons-2.3.0. -# 2) Added automatic insertion of && for multi-line commands. -# -# September 2001, Thomas Gleerup <tgl@oticon.dk> -# 1) Updated with Kevin Nolish's multi-line improvement. -# 2) Improved this so that single [perl] commands can still be used. -# - -# NOTE: Cons intentionally does not use the "perl -w" option or -# "use strict." Because Cons "configuration files" are actually -# Perl scripts, enabling those restrictions here would force them -# on every user's config files, wanted or not. Would users write -# "better" Construct and Conscript files if we forced "use strict" -# on them? Probably. But we want people to use Cons to get work -# done, not force everyone to become a Perl guru to use it, so we -# don't insist. -# -# That said, Cons' code is both "perl -w" and "use strict" clean. -# Regression tests keep the code honest by checking for warnings -# and "use strict" failures. - -use vars qw( $CVS_id $CVS_ver $ver_num $ver_rev $version ); - -# I hate those CVS tags -$CVS_id = 'pcons-2.3.1'; -$CVS_ver = (split (/\s+/, $CVS_id))[2]; - -$ver_num = "__VERSION__"; -$ver_rev = "__REVISION__"; - -#$version = "This is Cons $ver_num$ver_rev ($CVS_id)\n"; -$version = "This is parallel Cons (pcons) $ver_num$ver_rev ($CVS_id)\n"; - -# Cons: A Software Construction Tool. -# Copyright (c) 1996-2001 Free Software Foundation, Inc. -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; see the file COPYING. If not, write to -# the Free Software Foundation, Inc., 59 Temple Place - Suite 330, -# Boston, MA 02111-1307, USA. - -require 5.003; - -# See the NOTE above about why Cons doesn't "use strict". -use integer; -use Cwd; -use File::Copy; - -use vars qw( $_WIN32 $_a $_exe $_o $_so ); - -#------------------------------------------------------------------ -# Determine if running on win32 platform - either Windows NT or 95 -#------------------------------------------------------------------ - -use vars qw( $PATH_SEPARATOR $iswin32 $_WIN32 $usage $indent @targets ); - -BEGIN -{ - use Config; - - # if the version is 5.003, we can check $^O - if ($] < 5.003) - { - eval("require Win32"); - $_WIN32 = (!$@); - } - else - { - $_WIN32 = ($^O eq "MSWin32") ? 1 : 0; - } - - # Fetch the PATH separator from Config; - # provide our old defaults in case it's not set. - $PATH_SEPARATOR = $Config{path_sep}; - $PATH_SEPARATOR = $_WIN32 ? ';' : ':' if !defined $PATH_SEPARATOR; - - # Fetch file suffixes from Config, - # accomodating differences in the Config variables - # used by different Perl versions. - $_exe = $Config{_exe}; - $_exe = $Config{exe_ext} if !defined $_exe; - $_exe = $_WIN32 ? '.exe' : '' if !defined $_exe; - $_o = $Config{_o}; - $_o = $Config{obj_ext} if !defined $_o; - $_o = $_WIN32 ? '.obj' : '.o' if !defined $_o; - $_a = $Config{_a}; - $_a = $Config{lib_ext} if !defined $_a; - $_a = $_WIN32 ? '.lib' : '.a' if !defined $_a; - $_so = ".$Config{so}"; - $_so = $_WIN32 ? '.dll' : '.so' if !defined $_so; -} - -# Flush stdout each time. -$| = 1; - -# Seed random number generator. -srand(time . $$); # this works better than time ^ $$ in perlfunc manpage. - -$usage = q( -Usage: cons <arguments> -- <construct-args> - -Arguments can be any of the following, in any order: - - <targets> Build the specified targets. If <target> is a directory - recursively build everything within that directory. - - +<pattern> Limit the cons scripts considered to just those that - match <pattern>. Multiple + arguments are accepted. - - <name>=<val> Sets <name> to value <val> in the ARG hash passed to the - top-level Construct file. - - -cc Show command that would have been executed, when - retrieving from cache. No indication that the file - has been retrieved is given; this is useful for - generating build logs that can be compared with - real build logs. - - -cd Disable all caching. Do not retrieve from cache nor - flush to cache. - - -cr Build dependencies in random order. This is useful when - building multiple similar trees with caching enabled. - - -cs Synchronize existing build targets that are found to be - up-to-date with cache. This is useful if caching has - been disabled with -cc or just recently enabled with - UseCache. - - -d Enable dependency debugging. - - -f <file> Use the specified file instead of "Construct" (but first - change to containing directory of <file>). - - -h Show a help message local to the current build if - one such is defined, and exit. - - -k Keep going as far as possible after errors. - - -o <file> Read override file <file>. - - -p Show construction products in specified trees. - -pa Show construction products and associated actions. - -pw Show products and where they are defined. - - -q Be quiet; multiple -q flags increase quietness level: - 1: quiet about Installing and Removing targets - 2: quiet about build commands, up-to-date targets - - -r Remove construction products associated with <targets> - - -R <repos> Search for files in <repos>. Multiple -R <repos> - directories are searched in the order specified. - - -S <pkg> Use package sig::<pkg> to calculate file signatures. - Currently supported values are "md5" for MD5 - signatures (the default) and "md5::debug" for MD5 - signature debug information. - - -t Traverse up the directory hierarchy looking for a - Construct file, if none exists in the current directory. - (Targets will be modified to be relative to the - Construct file.) - - -v Show cons version and continue processing. - -V Show cons version and exit. - - -wf <file> Write all filenames considered into <file>. - - -x Show this message and exit. - - - Please report any suggestions through the cons-discuss@gnu.org mailing - list. - - To subscribe, send mail to cons-discuss-request@gnu.org with body - 'subscribe'. - - If you find a bug, please report it through the bug-cons@gnu.org - mailing list. - - Information about CONS can be obtained from the official cons web site - http://www.dsmit.com/cons/ or its mirrors (listed there). - - The cons maintainers can be contacted by email at cons-maintainers@gnu.org - - User documentation of cons is contained in cons and can be obtained - by doing 'perldoc /path/to/cons'. - -); -my $pcons = 1; - -# Simplify program name, if it is a path. -{ - my ($vol, $dir, $file) = File::Spec->splitpath(File::Spec->canonpath($0)); - $0 = $file; -} - -# Default parameters. -$param::topfile = 'Construct'; # Top-level construction file. -$param::install = 1; # Show installations -$param::build = 1; # Build targets - ### $param::show = 1; # Show building of targets. -$param::sigpro = 'md5'; # Signature protocol. -$param::depfile = ''; # Write all deps out to this file -$param::salt = ''; # Salt derived file signatures with this. -$param::sourcesig = ['*' => 'content']; # Source file signature calculation -$param::rep_sig_times_ok = 1; # Repository .consign times are in sync - # w/files. -$param::conscript_chdir = 0; # Change dir to Conscript directory -$param::quiet = 0; # should we show the command being executed. -$param::max_jobs = 1; # pcons - -@param::defaults = (); - -# -$indent = ''; - -# Display a command while executing or otherwise. This -# should be called by command builder action methods. -sub showcom -{ - print($indent . $_[0] . "\n") if ($param::quiet < 2); -} - -# Default environment. -# This contains only the completely platform-independent information -# we can figure out. Platform-specific information (UNIX, Win32) -# gets added below. -@param::base = ( - 'SIGNATURE' => ['*' => 'build'], - 'SUFEXE' => $_exe, # '' on UNIX systems - 'SUFLIB' => $_a, # '.a' on UNIX systems - 'SUFLIBS' => "$_so:$_a", # '.so:.a' on UNIX - 'SUFOBJ' => $_o, # '.o' on UNIX systems - 'SUFMAP' => { - '.c' => 'build::command::cc', - '.s' => 'build::command::cc', - '.S' => 'build::command::cc', - '.C' => 'build::command::cxx', - '.cc' => 'build::command::cxx', - '.cxx' => 'build::command::cxx', - '.cpp' => 'build::command::cxx', - '.c++' => 'build::command::cxx', - '.C++' => 'build::command::cxx', - }, - 'PERL' => $^X, - ); - -# pcons does not allow multi-line commands -my $ar_command = ($param::max_jobs <= 1) - ? # pcons - ['%AR %ARFLAGS %> %<', '%RANLIB %>'] - : # cons - '%AR %ARFLAGS %> %< && %RANLIB %>'; # pcons - -%param::rulesets = ( - - # Defaults for Win32. - # Defined for VC++ 6.0 by Greg Spencer <greg_spencer@acm.org> - # Your mileage may vary. - 'msvc' => [ - 'CC' => 'cl', - 'CFLAGS' => '/nologo', - 'CCCOM' => '%CC %CFLAGS %_IFLAGS /c %< /Fo%>', - 'CXX' => '%CC', - 'CXXFLAGS' => '%CFLAGS', - 'CXXCOM' => '%CXX %CXXFLAGS %_IFLAGS /c %< /Fo%>', - 'INCDIRPREFIX' => '/I', - 'INCDIRSUFFIX' => '', - 'LINK' => 'link', - 'LINKCOM' => '%LINK %LDFLAGS /out:%> %< %_LDIRS %LIBS', - 'LINKMODULECOM' => '%LD /r /o %> %<', - 'LIBDIRPREFIX' => '/LIBPATH:', - 'LIBDIRSUFFIX' => '', - 'AR' => 'lib', - 'ARFLAGS' => '/nologo ', - 'ARCOM' => "%AR %ARFLAGS /out:%> %<", - 'RANLIB' => '', - 'LD' => 'link', - 'LDFLAGS' => '/nologo ', - 'PREFLIB' => '', - ], - - # Defaults for a typical (?) UNIX platform. - # Your mileage may vary. - 'unix' => [ - 'CC' => 'cc', - 'CFLAGS' => '', - 'CCCOM' => '%CC %CFLAGS %_IFLAGS -c %< -o %>', - 'CXX' => '%CC', - 'CXXFLAGS' => '%CFLAGS', - 'CXXCOM' => '%CXX %CXXFLAGS %_IFLAGS -c %< -o %>', - 'INCDIRPREFIX' => '-I', - 'INCDIRSUFFIX' => '', - 'LINK' => '%CXX', - 'LINKCOM' => '%LINK %LDFLAGS -o %> %< %_LDIRS %LIBS', - 'LINKMODULECOM' => '%LD -r -o %> %<', - 'LIBDIRPREFIX' => '-L', - 'LIBDIRSUFFIX' => '', - 'AR' => 'ar', - 'ARFLAGS' => 'r', # rs? - 'ARCOM' => $ar_command, # pcons - 'RANLIB' => 'ranlib', - 'AS' => 'as', - 'ASFLAGS' => '', - 'ASCOM' => '%AS %ASFLAGS %< -o %>', - 'LD' => 'ld', - 'LDFLAGS' => '', - 'PREFLIB' => 'lib', - 'ENV' => {'PATH' => '/bin:/usr/bin'}, - ], - ); - -# Set the rules based on the platform. -script::DefaultRules(script::RuleSet($_WIN32 ? 'msvc' : 'unix')); - -# Handle command line arguments. -while (@ARGV) -{ - $_ = shift @ARGV; - last if /^--$/; # Argument passing to Construct. - &option, next if s/^-//; - push (@param::include, $_), next if s/^\+//; - &equate, next if /=/; - push (@targets, $_), next; -} - -sub option -{ - my %opt = ( - 'cc' => sub { $param::cachecom = 1; }, - 'cd' => sub { $param::cachedisable = 1; }, - 'cr' => sub { $param::random = 1; }, - 'cs' => sub { $param::cachesync = 1; }, - 'd' => sub { $param::depends = 1; }, - 'h' => sub { $param::localhelp = 1; }, - 'k' => sub { $param::kflag = 1; }, - 'p' => sub { - $param::pflag = 1; - $param::build = 0; - }, - 'pa' => sub { - $param::pflag = 1; - $param::aflag = 1; - $indent = "... "; - $param::build = 0; - }, - 'pw' => sub { - $param::pflag = 1; - $param::wflag = 1; - $param::build = 0; - }, - 'q' => sub { $param::quiet++; }, - 'r' => sub { - $param::rflag = 1; - $param::build = 0; - }, - 't' => sub { $param::traverse = 1; }, - 'v' => sub { print($version); }, - 'V' => sub { print($version), exit(0); }, - 'x' => sub { print($usage), exit 0; }, - ); - - my %opt_arg = ( - 'f' => sub { $param::topfile = $_[0]; }, - 'o' => sub { $param::overfile = $_[0]; }, - 'R' => sub { script::Repository($_[0]); }, - 'S' => sub { $param::sigpro = $_[0]; }, - 'wf' => sub { $param::depfile = $_[0]; }, - 'j' => sub { $param::max_jobs = $_[0]; }, # pcons - ); - - if (defined $opt{$_}) - { - &{$opt{$_}} (); - return; - } - while ($_) - { - $_ =~ m/(.)(.*)/; - if (defined $opt{$1}) - { - &{$opt{$1}} (); - $_ = $2; - next; - } - if (defined $opt_arg{$1}) - { - if (!$2) - { - $_ = shift @ARGV; - die ("$0: -$1 option requires an argument.\n") if !$_; - } - &{$opt_arg{$1}} ($2 || $_); - return; - } - $_ =~ m/(..)(.*)/; - if (defined $opt_arg{$1}) - { - if (!$2) - { - $_ = shift @ARGV; - die ("$0: -$1 option requires an argument.\n") if !$_; - } - &{$opt_arg{$1}} ($2 || $_); - return; - } - if ($_) - { - die - qq($0: unrecognized option "-$_". Use -x for a usage message.\n); - } - } -} - -# Process an equate argument (var=val). -sub equate -{ - my ($var, $val) = /([^=]*)=(.*)/; - $script::ARG{$var} = $val; -} - -# Define file signature protocol. -'sig'->select($param::sigpro); - -# Cleanup after an interrupt. -$SIG{INT} = $SIG{QUIT} = $SIG{TERM} = sub { - $SIG{PIPE} = $SIG{INT} = $SIG{QUIT} = $SIG{TERM} = 'IGNORE'; - $SIG{HUP} = $SIG{INT} if !$main::_WIN32; - warn("\n$0: killed\n"); - - # Call this first, to make sure that this processing - # occurs even if a child process does not die (and we - # hang on the wait). - sig::hash::END(); - wait(); - exit(1); -}; -$SIG{HUP} = $SIG{INT} if !$main::_WIN32; - -# Cleanup after a broken pipe (someone piped our stdout?) -$SIG{PIPE} = sub { - $SIG{PIPE} = $SIG{HUP} = $SIG{INT} = $SIG{QUIT} = $SIG{TERM} = 'IGNORE'; - warn("\n$0: broken pipe\n"); - sig::hash::END(); - wait(); - exit(1); -}; - -if ($param::depfile) -{ - open(main::DEPFILE, ">" . $param::depfile) - || die ("$0: couldn't open $param::depfile ($!)\n"); -} - -# If the supplied top-level Conscript file is not in the -# current directory, then change to that directory. -{ - my ($vol, $dir, $file) = - File::Spec->splitpath(File::Spec->canonpath($param::topfile)); - if ($vol || $dir) - { - my ($cd) = File::Spec->catpath($vol, $dir, undef); - chdir($cd) || die ("$0: couldn't change to directory $cd ($!)\n"); - $param::topfile = $file; - } -} - -# Walk up the directory hierarchy looking for a Conscript file (if -t set). -my ($target_top); -my (@targetdir) = (); -if ($param::traverse && !-f $param::topfile) -{ - my ($vol, $dirs, $file) = File::Spec->splitpath(cwd()); - my (@dirs) = (File::Spec->splitdir($dirs), $file); - while ( - !-f File::Spec->catpath($vol, File::Spec->catdir(@dirs), - $param::topfile)) - { - die ("$0: unable to find $param::topfile.\n") if !@dirs; - unshift (@targetdir, pop (@dirs)); - } - my ($cwd) = File::Spec->catpath($vol, File::Spec->catdir(@dirs), ''); - print "$0: Entering directory `$cwd'\n"; - chdir($cwd); - @targets = map { File::Spec->catdir(@targetdir, $_) } @targets; -} - -# Set up $dir::top and $dir::cwd, now that we are in the right directory. -dir::init(); - -# -if (@targetdir) -{ - $target_top = $dir::top->lookupdir(File::Spec->catdir(@targetdir)); -} - -# Now handle override file. -package override; -if ($param::overfile) -{ - my ($ov) = $param::overfile; - die qq($0: can\'t read override file "$ov" ($!)\n) if !-f $ov; #' - do $ov; - if ($@) - { - chop($@); - die qq($0: errors in override file "$ov" ($@)\n); - } -} - -# Provide this to user to setup override patterns. -sub Override -{ - my ($re, @env) = @_; - return if $param::overrides{$re}; # if identical, first will win. - $param::overrides = 1; - $param::overrides{$re} = \@env; - push (@param::overrides, $re); -} - -package main; - -use vars qw( %priority $errors ); - -# Check script inclusion regexps -my $re; -for $re (@param::include) -{ - if (!defined eval { "" =~ /$re/ }) - { - my ($err) = $@; - $err =~ s/in regexp at .*$//; - die ("$0: error in regexp $err"); - } -} - -# Read the top-level construct file and its included scripts. -doscripts($param::topfile); - -# Status priorities. This lets us aggregate status for directories -# and print an appropriate message (at the top-level). -%priority = - ('none' => 1, 'handled' => 2, 'built' => 3, 'unknown' => 4, 'errors' => 5); - -# If no targets were specified, supply default targets (if any). -@targets = @param::default_targets if !@targets; - -$errors = 0; - -# Build the supplied target patterns. -my $tgt; -for $tgt (map($dir::top->lookup($_), @targets)) -{ - if ($target_top && !$tgt->is_under($target_top)) - { - - # A -t option was used, and this target is not underneath - # the directory where we were invoked via -t. - # If the target is a directory and the -t directory - # is underneath it, then build the -t directory. - if (ref $tgt ne "dir" || !$target_top->is_under($tgt)) - { - next; - } - $tgt = $target_top; - } - buildtoptarget($tgt); -} - -exit 0 + ($errors != 0); - -sub buildtoptarget -{ - my ($tgt) = @_; - return if !$tgt; - my ($status) = buildtarget($tgt); - if ($status ne 'built') - { - my ($path) = $tgt->path; - if ($status eq "errors") - { - print qq($0: "$path" not remade because of errors.\n); - $errors++; - } - elsif ($status eq "handled") - { - print qq($0: "$path" is up-to-date.\n) if ($param::quiet < 2); - } - elsif ($status eq "unknown") - { - - # cons error already reported. - $errors++; - } - elsif ($status eq "none") - { - - # search for targets that may be linked to the given path. - my @linked = dir::linked_targets($tgt) if $target_top; - if (@linked) - { - my @names = map($_->path, @linked); - print "Linked targets: @names\n" if ($param::quiet < 1); - map(buildtoptarget($_), @linked); - } - else - { - print qq($0: nothing to be built in "$path".\n) - if $param::build && ($param::quiet < 2); - } - } - else - { - print qq($0: don\'t know how to construct "$path".\n); #' - $errors++; - } - } -} - -# Build the supplied target directory or files. Return aggregated status. -sub buildtarget -{ - my ($tgt) = @_; - if (ref($tgt) eq "dir") - { - my ($result) = "none"; - my ($priority) = $priority{$result}; - if (exists $tgt->{member}) - { - my ($members) = $tgt->{member}; - my $entry; - for $entry (sort keys %$members) - { - next if $entry eq $dir::CURDIR || $entry eq $dir::UPDIR; - my ($tgt) = $members->{$entry}; - next if ref($tgt) ne "dir" && !exists($tgt->{builder}); - my ($stat) = buildtarget($members->{$entry}); - my ($pri) = $priority{$stat}; - if ($pri > $priority) - { - $priority = $pri; - $result = $stat; - } - } - } - return $result; - } - if ($param::depends) - { - my ($path) = $tgt->path; - if ($tgt->{builder}) - { - my (@dep) = (@{$tgt->{dep}}, @{$tgt->{sources}}); - my ($dep) = join (' ', map($_->path, @dep)); - print("Target $path: $dep\n"); - } - else - { - print("Target $path: not a derived file\n"); - } - } - if ($param::build) - { - return build $tgt; - } - elsif ($param::pflag || $param::wflag || $param::aflag) - { - if ($tgt->{builder}) - { - if ($param::wflag) - { - print qq(${\$tgt->path}: $tgt->{script}\n); - } - elsif ($param::pflag) - { - print qq(${\$tgt->path}:\n) if $param::aflag; - print qq(${\$tgt->path}\n) if !$param::aflag; - } - if ($param::aflag) - { - $tgt->{builder}->action($tgt); - } - } - } - elsif ($param::rflag && $tgt->{builder}) - { - my ($path) = $tgt->path; - if (-f $path) - { - if (unlink($path)) - { - print("Removed $path\n") if ($param::quiet < 1); - } - else - { - warn("$0: couldn't remove $path\n"); - } - } - } - - return "none"; -} - -package NameSpace; - -# Return a hash that maps the name of symbols in a namespace to an -# array of refs for all types for which the name has a defined value. -# A list of symbols may be specified; default is all symbols in the -# name space. -sub save -{ - my $package = shift; - my (%namerefs, $var, $type); - no strict 'refs'; - @_ = keys %{$package . "::"} if !@_; - foreach $var (@_) - { - $namerefs{$var} = []; - my $fqvar = $package . "::" . $var; - - # If the scalar for this variable name doesn't already - # exist, *foo{SCALAR} will autovivify the reference - # instead of returning undef, so unlike the other types, - # we have to dereference to find out if it exists. - push (@{$namerefs{$var}}, *{$fqvar}{SCALAR}) - if defined ${*{$fqvar}{SCALAR}}; - foreach $type (qw(ARRAY HASH CODE IO)) - { - push (@{$namerefs{$var}}, *{$fqvar}{$type}) - if defined *{$fqvar}{$type}; - } - } - return \%namerefs; -} - -# Remove the specified symbols from the namespace. -# Default is to remove all. -sub remove -{ - my $package = shift; - my (%namerefs, $var); - no strict 'refs'; - @_ = keys %{$package . "::"} if !@_; - foreach $var (@_) - { - delete ${$package . "::"}{$var}; - } -} - -# Restore values to symbols specified in a hash as returned -# by NameSpace::save. -sub restore -{ - my ($package, $namerefs) = @_; - my ($var, $ref); - no strict 'refs'; - foreach $var (keys %$namerefs) - { - my $fqvar = $package . "::" . $var; - foreach $ref (@{$namerefs->{$var}}) - { - *{$fqvar} = $ref; - } - } -} - -# Support for "building" scripts, importing and exporting variables. -# With the exception of the top-level routine here (invoked from the -# main package by cons), these are all invoked by user scripts. -package script; - -use vars qw( $ARG $caller_dir_path %special_var ); - -BEGIN -{ - - # We can't Export or Import the following variables because Perl always - # treats them as part of the "main::" package (see perlvar(1)). - %special_var = map { $_ => 1 } qw(ENV INC ARGV ARGVOUT SIG - STDIN STDOUT STDERR); -} - -# This is called from main to interpret/run the top-level Construct -# file, passed in as the single argument. -sub main::doscripts -{ - my ($script) = @_; - Build($script); - - # Now set up the includes/excludes (after the Construct file is read). - $param::include = join ('|', @param::include); - - # Save the original variable names from the script package. - # These will stay intact, but any other "script::" variables - # defined in a Conscript file will get saved, deleted, - # and (when necessary) restored. - my (%orig_script_var) = map { $_ => 1 } keys %script::; - $caller_dir_path = undef; - my $cwd = Cwd::cwd(); - my (@scripts) = pop (@priv::scripts); - while ($priv::self = shift (@scripts)) - { - my ($path) = $priv::self->{script}->rsrcpath; - if (-f $path) - { - $dir::cwd = $priv::self->{script}->{dir}; - - # Handle chdir to the Conscript file directory, if necessary. - my ($vol, $dir, $file); - if ($param::conscript_chdir) - { - ($vol, $dir, $file) = - File::Spec->splitpath(File::Spec->canonpath($path)); - if ($vol ne '' || $dir ne '') - { - $caller_dir_path = File::Spec->catpath($vol, $dir, undef); - chdir($caller_dir_path) - || die "Could not chdir to $caller_dir_path: $!\n"; - } - } - else - { - $file = $path; - } - - # Actually process the Conscript file. - do $file; - - # Save any variables defined by the Conscript file - # so we can restore them later, if needed; - # then delete them from the script:: namespace. - my (@del) = grep(!$orig_script_var{$_}, keys %script::); - if (@del) - { - $priv::self->{script}->{pkgvars} = - NameSpace::save('script', @del); - NameSpace::remove('script', @del); - } - if ($caller_dir_path) - { - chdir($cwd); - $caller_dir_path = undef; - } - if ($@) - { - chomp($@); - my $err = ($@ =~ /\n/ms) ? ":\n$@" : " ($@)"; - print qq($0: error in file "$path"$err\n); - $run::errors++; - } - else - { - - # Only process subsidiary scripts if no errors in parent. - unshift (@scripts, @priv::scripts); - } - undef @priv::scripts; - } - else - { - my $where = ''; - my $cref = $priv::self->{script}->creator; - if (defined $cref) - { - my ($_foo, $script, $line, $sub) = @$cref; - $where = " ($sub in $script, line $line)"; - } - warn qq(Ignoring missing script "$path"$where); - } - } - die ("$0: script errors encountered: construction aborted\n") - if $run::errors; -} - -# Return caller info about the method being invoked. -# This is everything from the Perl "caller" builtin function, -# including which Construct/Conscript file, line number, -# subroutine name, etc. -sub caller_info -{ - my ($lev) = 1; - my (@frame); - do - { - @frame = caller ++$lev; - if (defined($frame[3]) && $frame[3] eq '(eval)') - { - @frame = caller --$lev; - if ($caller_dir_path) - { - $frame[1] = File::Spec->catfile($caller_dir_path, $frame[1]); - } - return @frame; - } - } while ($frame[3]); - return; -} - -# Link a directory to another. This simply means set up the *source* -# for the directory to be the other directory. -sub Link -{ - dir::link(@_); -} - -# Add directories to the repository search path for files. -# Strip our current directory from the list so Repository -# (or -R options) can be used from within the repository. -sub Repository -{ - my ($my_dir) = Cwd::cwd(); - my $dir; - foreach $dir (@_) - { - - # The following more direct call isn't available in - # Cwd.pm until some time after 5.003... - # my($d) = Cwd::abs_path($dir); - chdir($dir); - my ($d) = Cwd::cwd(); - chdir($my_dir); - - # - next if !$d || !-d $d || $d eq $my_dir; - - # We know we can get away with passing undef to lookupdir - # as the directory because $dir is an absolute path. - push (@param::rpath, dir::lookupdir(undef, $dir)); - push @INC, $d; - } -} - -# Return the list of Repository directories specified. -sub Repository_List -{ - map($_->path, @param::rpath); -} - -# Specify whether the .consign signature times in repository files are, -# in fact, consistent with the times on the files themselves. -sub Repository_Sig_Times_OK -{ - $param::rep_sig_times_ok = shift; -} - -sub SourceSignature -{ - $param::sourcesig = [@_]; -} - -# Specify whether we should chdir to the containing directories -# of Conscript files. -sub Conscript_chdir -{ - $param::conscript_chdir = shift; -} - -# Specify files/targets that must be present and built locally, -# even if they exist already-built in a Repository. -sub Local -{ - my (@files) = map($dir::cwd->lookupfile($_), @_); - map($_->local(1), @files); -} - -# Export variables to any scripts invoked from this one. -sub Export -{ - my (@illegal) = grep($special_var{$_}, @_); - if (@illegal) - { - die qq($0: cannot Export special Perl variables: @illegal\n); - } - @{$priv::self->{exports}} = grep(!defined $special_var{$_}, @_); -} - -# Import variables from the export list of the caller -# of the current script. -sub Import -{ - my (@illegal) = grep($special_var{$_}, @_); - if (@illegal) - { - die qq($0: cannot Import special Perl variables: @illegal\n); - } - my ($parent) = $priv::self->{parent}; - my ($imports) = $priv::self->{imports}; - @{$priv::self->{exports}} = keys %$imports; - my ($var); - foreach $var (grep(!defined $special_var{$_}, @_)) - { - if (!exists $imports->{$var}) - { - my ($path) = $parent->{script}->path; - die qq($0: variable "$var" not exported by file "$path"\n); - } - if (!defined $imports->{$var}) - { - my $path = $parent->{script}->path; - my $err = - "$0: variable \"$var\" exported but not " - . "defined by file \"$path\"\n"; - die $err; - } - ${"script::$var"} = $imports->{$var}; - } -} - -# Build an inferior script. That is, arrange to read and execute -# the specified script, passing to it any exported variables from -# the current script. -sub Build -{ - my (@files) = map($dir::cwd->lookupfile($_), @_); - my (%imports) = map { $_ => ${"script::$_"} } @{$priv::self->{exports}}; - my $file; - for $file (@files) - { - next if $param::include && $file->path !~ /$param::include/o; - my ($self) = { - 'script' => $file, - 'parent' => $priv::self, - 'imports' => \%imports - }; - bless $self; # may want to bless into class of parent in future - push (@priv::scripts, $self); - } -} - -# Set up regexps dependencies to ignore. Should only be called once. -sub Ignore -{ - die ("Ignore called more than once\n") if $param::ignore; - $param::ignore = join ("|", map("($_)", @_)) if @_; -} - -# Specification of default targets. -sub Default -{ - push (@param::default_targets, map($dir::cwd->lookup($_)->path, @_)); -} - -# Local Help. Should only be called once. -sub Help -{ - if ($param::localhelp) - { - print "@_\n"; - exit 2; - } -} - -# For windows platforms which use unix tool sets, the msvc defaults may -# not be useful. Also, in the future, other platforms (Mac?) may have the -# same problem. -sub RuleSet -{ - my $style = shift; - my @rulesets = sort keys %param::rulesets; - die "Unknown style for rules: $style.\n" - . "Supported rules are: (" - . join (" ", @rulesets) . ")" - unless eval(join ("||", map("\$style eq '$_'", @rulesets))); - return @param::base, @{$param::rulesets{$style}}; -} - -sub DefaultRules -{ - @param::defaults = (); - push @param::defaults, @_; -} - -# Return the build name(s) of a file or file list. -sub FilePath -{ - wantarray - ? map($dir::cwd->lookupfile($_)->path, @_) - : $dir::cwd->lookupfile($_[0])->path; -} - -# Return the build name(s) of a directory or directory list. -sub DirPath -{ - wantarray - ? map($dir::cwd->lookupdir($_)->path, @_) - : $dir::cwd->lookupdir($_[0])->path; -} - -# Split the search path provided into components. Look each up -# relative to the current directory. -# The usual path separator problems abound; for now we'll use : -sub SplitPath -{ - my ($dirs) = @_; - if (ref($dirs) ne "ARRAY") - { - $dirs = [split (/$main::PATH_SEPARATOR/o, $dirs)]; - } - map { DirPath($_) } @$dirs; -} - -# Return true if the supplied path is available as a source file -# or is buildable (by rules seen to-date in the build). -sub ConsPath -{ - my ($path) = @_; - my ($file) = $dir::cwd->lookup($path); - return $file->accessible; -} - -# Return the source path of the supplied path. -sub SourcePath -{ - wantarray - ? map($dir::cwd->lookupfile($_)->rsrcpath, @_) - : $dir::cwd->lookupfile($_[0])->rsrcpath; -} - -# Search up the tree for the specified cache directory, starting with -# the current directory. Returns undef if not found, 1 otherwise. -# If the directory is found, then caching is enabled. The directory -# must be readable and writable. If the argument "mixtargets" is provided, -# then targets may be mixed in the cache (two targets may share the same -# cache file--not recommended). -sub UseCache($@) -{ - my ($dir, @args) = @_; - - # NOTE: it's important to process arguments here regardless of whether - # the cache is disabled temporarily, since the mixtargets option affects - # the salt for derived signatures. - for (@args) - { - if ($_ eq "mixtargets") - { - - # When mixtargets is enabled, we salt the target signatures. - # This is done purely to avoid a scenario whereby if - # mixtargets is turned on or off after doing builds, and - # if cache synchronization with -cs is used, then - # cache files may be shared in the cache itself (linked - # under more than one name in the cache). This is not bad, - # per se, but simply would mean that a cache cleaning algorithm - # that looked for a link count of 1 would never find those - # particular files; they would always appear to be in use. - $param::salt = 'M' . $param::salt; - $param::mixtargets = 1; - } - else - { - die qq($0: UseCache unrecognized option "$_"\n); - } - } - if ($param::cachedisable) - { - warn("Note: caching disabled by -cd flag\n"); - return 1; - } - my ($depth) = 15; - while ($depth-- && !-d $dir) - { - $dir = File::Spec->catdir($dir::UPDIR, $dir); - } - if (-d $dir) - { - $param::cache = $dir; - return 1; - } - return undef; -} - -# Salt the signature generator. The salt (a number of string) is added -# into the signature of each derived file. Changing the salt will -# force recompilation of all derived files. -sub Salt($) -{ - - # We append the value, so that UseCache and Salt may be used - # in either order without changing the signature calculation. - $param::salt .= $_[0]; -} - -# Mark files (or directories) to not be removed before building. -sub Precious -{ - map($_->{precious} = 1, map($dir::cwd->lookup($_), @_)); -} - -# These methods are callable from Conscript files, via a cons -# object. Procs beginning with _ are intended for internal use. -package cons; - -use vars qw( %envcache ); - -# This is passed the name of the base environment to instantiate. -# Overrides to the base environment may also be passed in -# as key/value pairs. -sub new -{ - my ($package) = shift; - my ($env) = {@param::defaults, @_}; - @{$env->{_envcopy}} = %$env; # Note: we never change PATH - $env->{_cwd} = $dir::cwd; # Save directory of environment for - bless $env, $package; # any deferred name interpretation. -} - -# Clone an environment. -# Note that the working directory will be the initial directory -# of the original environment. -sub clone -{ - my ($env) = shift; - my $clone = {@{$env->{_envcopy}}, @_}; - @{$clone->{_envcopy}} = %$clone; # Note: we never change PATH - $clone->{_cwd} = $env->{_cwd}; - bless $clone, ref $env; -} - -# Create a flattened hash representing the environment. -# It also contains a copy of the PATH, so that the path -# may be modified if it is converted back to a hash. -sub copy -{ - my ($env) = shift; - (@{$env->{_envcopy}}, 'ENV' => {%{$env->{ENV}}}, @_); -} - -# Resolve which environment to actually use for a given -# target. This is just used for simple overrides. -sub _resolve -{ - return $_[0] if !$param::overrides; - my ($env, $tgt) = @_; - my ($path) = $tgt->path; - my $re; - for $re (@param::overrides) - { - next if $path !~ /$re/; - - # Found one. Return a combination of the original environment - # and the override. - my ($ovr) = $param::overrides{$re}; - return $envcache{$env, $re} if $envcache{$env, $re}; - my ($newenv) = {@{$env->{_envcopy}}, @$ovr}; - @{$newenv->{_envcopy}} = %$env; - $newenv->{_cwd} = $env->{_cwd}; - return $envcache{$env, $re} = bless $newenv, ref $env; - } - return $env; -} - -# Substitute construction environment variables into a string. -# Internal function/method. -sub _subst -{ - my ($env, $str) = @_; - if (!defined $str) - { - return undef; - } - elsif (ref($str) eq "ARRAY") - { - return [map($env->_subst($_), @$str)]; - } - else - { - - # % expansion. %% gets converted to % later, so expand any - # %keyword construction that doesn't have a % in front of it, - # modulo multiple %% pairs in between. - # In Perl 5.005 and later, we could actually do this in one regex - # using a conditional expression as follows, - # while ($str =~ s/($pre)\%(\{)?([_a-zA-Z]\w*)(?(2)\})/"$1". - # $env->{$3}/ge) {} - # The following two-step approach is backwards-compatible - # to (at least) Perl5.003. - my $pre = '^|[^\%](?:\%\%)*'; - while (($str =~ s/($pre)\%([_a-zA-Z]\w*)/$1.($env->{$2}||'')/ge) - || ($str =~ s/($pre)\%\{([_a-zA-Z]\w*)\}/$1.($env->{$2}||'')/ge)) - { - } - return $str; - } -} - -sub AfterBuild -{ - my ($env) = shift; - my ($perl_eval_str) = pop (@_); - my $file; - for $file (map($dir::cwd->lookup($_), @_)) - { - $file->{after_build_func} = $perl_eval_str; - - } -} - -sub Install -{ - my ($env) = shift; - my ($tgtdir) = $dir::cwd->lookupdir($env->_subst(shift)); - my $file; - for $file (map($dir::cwd->lookupfile($env->_subst($_)), @_)) - { - my ($tgt) = $tgtdir->lookupfile($file->{entry}); - $tgt->bind(find build::install($env), $file); - } -} - -sub InstallAs -{ - my $env = shift; - my $tgt = shift; - my $src = shift; - my @sources = (); - my @targets = (); - - if (ref $tgt) - { - die "InstallAs: Source is a file and target is a list!\n" - if (!ref($src)); - @sources = @$src; - @targets = @$tgt; - } - elsif (ref $src) - { - die "InstallAs: Target is a file and source is a list!\n"; - } - else - { - push @sources, $src; - push @targets, $tgt; - } - - if ($#sources != $#targets) - { - my $tn = $#targets + 1; - my $sn = $#sources + 1; - die "InstallAs: Source file list ($sn) and target file list ($tn) " - . "are inconsistent in length!\n"; - } - else - { - foreach (0 .. $#sources) - { - my $tfile = $dir::cwd->lookupfile($env->_subst($targets[$_])); - my $sfile = $dir::cwd->lookupfile($env->_subst($sources[$_])); - $tfile->bind(find build::install($env), $sfile); - } - } -} - -# Installation in a local build directory, -# copying from the repository if it's already built there. -# Functionally equivalent to: -# Install $env $dir, $file; -# Local "$dir/$file"; -sub Install_Local -{ - my ($env) = shift; - my ($tgtdir) = $dir::cwd->lookupdir($env->_subst(shift)); - my $file; - for $file (map($dir::cwd->lookupfile($env->_subst($_)), @_)) - { - my ($tgt) = $tgtdir->lookupfile($file->{entry}); - $tgt->bind(find build::install($env), $file); - $tgt->local(1); - } -} - -sub Objects -{ - my ($env) = shift; - map($dir::cwd->relpath($_), $env->_Objects(@_)); -} - -# Called with multiple source file references (or object files). -# Returns corresponding object files references. -sub _Objects -{ - my ($env) = shift; - my ($suffix) = $env->{SUFOBJ}; - map($env->_Object($_, $_->{dir}->lookupfile($_->base_suf($suffix))), - map { ref $_ ? $_ : $dir::cwd->lookupfile($env->_subst($_)) } - grep(defined $_, @_)); -} - -# Called with an object and source reference. If no object reference -# is supplied, then the object file is determined implicitly from the -# source file's extension. Sets up the appropriate rules for creating -# the object from the source. Returns the object reference. -sub _Object -{ - my ($env, $src, $obj) = @_; - return $obj if $src eq $obj; # don't need to build self from self. - my ($objenv) = $env->_resolve($obj); - my ($suffix) = $src->suffix; - - my ($builder) = $env->{SUFMAP}{$suffix}; - - if ($builder) - { - $obj->bind((find $builder($objenv)), $src); - } - else - { - die ("don't know how to construct ${\$obj->path} from " - . "${\$src->path}.\n"); - } - $obj; -} - -sub Program -{ - my ($env) = shift; - my ($tgt) = - $dir::cwd->lookupfile( - file::addsuffix($env->_subst(shift), $env->{SUFEXE})); - my ($progenv) = $env->_resolve($tgt); - $tgt->bind(find build::command::link($progenv, $progenv->{LINKCOM}), - $env->_Objects(@_)); -} - -sub Module -{ - my ($env) = shift; - my ($tgt) = $dir::cwd->lookupfile($env->_subst(shift)); - my ($modenv) = $env->_resolve($tgt); - my ($com) = pop (@_); - $tgt->bind(find build::command::link($modenv, $com), $env->_Objects(@_)); -} - -sub LinkedModule -{ - my ($env) = shift; - my ($tgt) = $dir::cwd->lookupfile($env->_subst(shift)); - my ($progenv) = $env->_resolve($tgt); - $tgt->bind( - find build::command::linkedmodule($progenv, - $progenv->{LINKMODULECOM}), - $env->_Objects(@_)); -} - -sub Library -{ - my ($env) = shift; - my ($lib) = - $dir::cwd->lookupfile( - file::addsuffix($env->_subst(shift), $env->{SUFLIB})); - my ($libenv) = $env->_resolve($lib); - $lib->bind(find build::command::library($libenv), $env->_Objects(@_)); -} - -# Simple derivation: you provide target, source(s), command. -# Special variables substitute into the rule. -# Target may be a reference, in which case it is taken -# to be a multiple target (all targets built at once). -sub Command -{ - my ($env) = shift; - my ($tgt) = $env->_subst(shift); - my ($builder) = find build::command::user($env, pop (@_), 'script'); - my (@sources) = map($dir::cwd->lookupfile($env->_subst($_)), @_); - if (ref($tgt)) - { - - # A multi-target command. - my (@tgts) = map($dir::cwd->lookupfile($_), @$tgt); - die ("empty target list in multi-target command\n") if !@tgts; - $env = $env->_resolve($tgts[0]); - my ($multi) = build::multiple->new($builder, \@tgts); - for $tgt (@tgts) - { - $tgt->bind($multi, @sources); - } - } - else - { - $tgt = $dir::cwd->lookupfile($tgt); - $env = $env->_resolve($tgt); - $tgt->bind($builder, @sources); - } -} - -sub Depends -{ - my ($env) = shift; - my ($tgt) = $env->_subst(shift); - my (@deps) = map($dir::cwd->lookup($env->_subst($_)), @_); - if (!ref($tgt)) - { - $tgt = [$tgt]; - } - my ($t); - foreach $t (map($dir::cwd->lookupfile($_), @$tgt)) - { - push (@{$t->{dep}}, @deps); - } -} - -# Setup a quick scanner for the specified input file, for the -# associated environment. Any use of the input file will cause the -# scanner to be invoked, once only. The scanner sees just one line at -# a time of the file, and is expected to return a list of -# dependencies. -sub QuickScan -{ - my ($env, $code, $file, $path) = @_; - $dir::cwd->lookup($env->_subst($file))->{'srcscan', $env} = - find scan::quickscan($code, $env, $env->_subst($path)); -} - -# Generic builder module. Just a few default methods. Every derivable -# file must have a builder object of some sort attached. Usually -# builder objects are shared. -package build; - -use vars qw( %builder ); - -# Every builder must now have at least an associated environment, -# so we can find its sigarray and calculate the proper signature. -sub find -{ - my ($class, $env) = @_; - $builder{$env} || do - { - my $self = {env => $env}; - $builder{$env} = bless $self, $class; - } -} - -# Null signature for dynamic includes. -sub includes { () } - -# Null signature for build script. -sub scriptsig { () } - -# Not compatible with any other builder, by default. -sub compatible { 0 } - -# Builder module for the Install command. -package build::install; - -use vars qw( @ISA ); - -BEGIN { @ISA = qw(build) } - -# Caching not supported for Install: generally install is trivial anyway, -# and we don't want to clutter the cache. -sub cachin { undef } -sub cachout { } - -# Do the installation. -sub action -{ - my ($self, $tgt) = @_; - my ($src) = $tgt->{sources}[0]; - main::showcom("Install ${\$src->rpath} as ${\$tgt->path}") - if ($param::install && $param::quiet < 1); - return unless $param::build; - futil::install($src->rpath, $tgt); - return 1; -} - -# Builder module for generic UNIX commands. -package build::command; - -use vars qw( @ISA %com ); - -BEGIN { @ISA = qw(build) } - -sub find -{ - my ($class, $env, $cmd, $package) = @_; - my ($act) = action::new($env, $cmd); - $package ||= ''; - $com{$env, $act, $package} || do - { - my $self = {env => $env, act => $act, 'package' => $package}; - $com{$env, $act, $package} = bless $self, $class; - } -} - -# Default cache in function. -sub cachin -{ - my ($self, $tgt, $sig) = @_; - if (cache::in($tgt, $sig)) - { - if ($param::cachecom) - { - $self->{act}->show($self->{env}, $tgt); - } - else - { - printf("Retrieved %s from cache\n", $tgt->path) - if ($param::quiet < 1); - } - return 1; - } - return undef; -} - -# Default cache out function. -sub cachout -{ - my ($self, $tgt, $sig) = @_; - cache::out($tgt, $sig); -} - -# Build the target using the previously specified commands. -sub action -{ - my ($self, $tgt) = @_; - $self->{act}->execute($self->{env}, $tgt, $self->{'package'}); -} - -# Return script signature. -sub scriptsig -{ - $_[0]->{act}->scriptsig; -} - -# Create a linked module. -package build::command::link; - -use vars qw( @ISA ); - -BEGIN { @ISA = qw(build::command) } - -# Find an appropriate linker. -sub find -{ - my ($class, $env, $command) = @_; - if (!exists $env->{_LDIRS}) - { - my ($ldirs) = ''; - my ($wd) = $env->{_cwd}; - my ($pdirs) = $env->{LIBPATH}; - if (!defined $pdirs) - { - $pdirs = []; - } - elsif (ref($pdirs) ne 'ARRAY') - { - $pdirs = [split (/$main::PATH_SEPARATOR/o, $pdirs)]; - } - my ($dir, $dpath); - for $dir (map($wd->lookupdir($env->_subst($_)), @$pdirs)) - { - $dpath = $dir->path; - - # Add the (presumably local) directory to the -L flags - # if we're not using repositories, the directory exists, - # or it's Linked to a source directory (that is, it *will* - # exist by the time the link occurs). - $ldirs .= " " . $env->{LIBDIRPREFIX} . $dpath . $env->{LIBDIRSUFFIX} - if !@param::rpath || -d $dpath || $dir->is_linked; - next if File::Spec->file_name_is_absolute($dpath); - if (@param::rpath) - { - my $d; - if ($dpath eq $dir::CURDIR) - { - foreach $d (map($_->path, @param::rpath)) - { - $ldirs .= " " - . $env->{LIBDIRPREFIX} . $d - . $env->{LIBDIRSUFFIX}; - } - } - else - { - my ($rpath); - foreach $d (map($_->path, @param::rpath)) - { - $rpath = File::Spec->catfile($d, $dpath); - $ldirs .= " " - . $env->{LIBDIRPREFIX} . $rpath - . $env->{LIBDIRSUFFIX} - if -d $rpath; - } - } - } - } - $env->{_LDIRS} = "%($ldirs%)"; - } - - # Introduce a new magic _LIBS symbol which allows to use the - # Unix-style -lNAME syntax for Win32 only. -lNAME will be replaced - # with %{PREFLIB}NAME%{SUFLIB}. <schwarze@isa.de> 1998-06-18 - - if ($main::_WIN32 && !exists $env->{_LIBS}) - { - my $libs; - my $name; - for $name (split (' ', $env->_subst($env->{LIBS} || ''))) - { - if ($name =~ /^-l(.*)/) - { - $name = "$env->{PREFLIB}$1$env->{SUFLIB}"; - } - $libs .= ' ' . $name; - } - $env->{_LIBS} = $libs ? "%($libs%)" : ''; - } - bless find build::command($env, $command); -} - -# Called from file::build. Make sure any libraries needed by the -# environment are built, and return the collected signatures -# of the libraries in the path. -sub includes -{ - return $_[0]->{'bsig'} if exists $_[0]->{'bsig'}; - my ($self, $tgt) = @_; - my ($env) = $self->{env}; - my ($ewd) = $env->{_cwd}; - my $ldirs = $env->{LIBPATH}; - if (!defined $ldirs) - { - $ldirs = []; - } - elsif (ref($ldirs) ne 'ARRAY') - { - $ldirs = [split (/$main::PATH_SEPARATOR/o, $ldirs)]; - } - my @lpath = map($ewd->lookupdir($_), @$ldirs); - my (@sigs); - my (@names); - - # Pass %LIBS symbol through %-substituition - # <schwarze@isa.de> 1998-06-18 - @names = split (' ', $env->_subst($env->{LIBS} || '')); - my $name; - for $name (@names) - { - my ($lpath, @allnames); - if ($name =~ /^-l(.*)/) - { - - # -l style names are looked up on LIBPATH, using all - # possible lib suffixes in the same search order the - # linker uses (according to SUFLIBS). - # Recognize new PREFLIB symbol, which should be 'lib' on - # Unix, and empty on Win32. TODO: What about shared - # library suffixes? <schwarze@isa.de> 1998-05-13 - @allnames = - map("$env->{PREFLIB}$1$_", split (/:/, $env->{SUFLIBS})); - $lpath = \@lpath; - } - else - { - @allnames = ($name); - - # On Win32, all library names are looked up in LIBPATH - # <schwarze@isa.de> 1998-05-13 - if ($main::_WIN32) - { - $lpath = [$dir::top, @lpath]; - } - else - { - $lpath = [$dir::top]; - } - } - my $dir; - DIR: for $dir (@$lpath) - { - my $n; - for $n (@allnames) - { - my ($lib) = $dir->lookup_accessible($n); - if ($lib) - { - last DIR if $lib->ignore; - if ((build $lib) eq 'errors') - { - $tgt->{status} = 'errors'; - return undef; - } - push (@sigs, 'sig'->signature($lib)); - last DIR; - } - } - } - } - $self->{'bsig'} = 'sig'->collect(@sigs); -} - -# Always compatible with other such builders, so the user -# can define a single program or module from multiple places. -sub compatible -{ - my ($self, $other) = @_; - ref($other) eq "build::command::link"; -} - -# Link a program. -package build::command::linkedmodule; - -use vars qw( @ISA ); - -BEGIN { @ISA = qw(build::command) } - -# Always compatible with other such builders, so the user -# can define a single linked module from multiple places. -sub compatible -{ - my ($self, $other) = @_; - ref($other) eq "build::command::linkedmodule"; -} - -# Builder for a C module -package build::command::cc; - -use vars qw( @ISA ); - -BEGIN { @ISA = qw(build::command) } - -sub find -{ - $_[1]->{_cc} || do - { - my ($class, $env) = @_; - my ($cpppath) = $env->_subst($env->{CPPPATH}); - my ($cscanner) = find scan::cpp($env->{_cwd}, $cpppath); - $env->{_IFLAGS} = "%(" . $cscanner->iflags($env) . "%)"; - my ($self) = find build::command($env, $env->{CCCOM}); - $self->{scanner} = $cscanner; - bless $env->{_cc} = $self; - } -} - -# Invoke the associated C scanner to get signature of included files. -sub includes -{ - my ($self, $tgt) = @_; - $self->{scanner}->includes($tgt, $tgt->{sources}[0]); -} - -# Builder for a C++ module -package build::command::cxx; - -use vars qw( @ISA ); - -BEGIN { @ISA = qw(build::command) } - -sub find -{ - $_[1]->{_cxx} || do - { - my ($class, $env) = @_; - my ($cpppath) = $env->_subst($env->{CPPPATH}); - my ($cscanner) = find scan::cpp($env->{_cwd}, $cpppath); - $env->{_IFLAGS} = "%(" . $cscanner->iflags($env) . "%)"; - my ($self) = find build::command($env, $env->{CXXCOM}); - $self->{scanner} = $cscanner; - bless $env->{_cxx} = $self; - } -} - -# Invoke the associated C scanner to get signature of included files. -sub includes -{ - my ($self, $tgt) = @_; - $self->{scanner}->includes($tgt, $tgt->{sources}[0]); -} - -# Builder for a user command (cons::Command). We assume that a user -# command might be built and implement the appropriate dependencies on -# the command itself (actually, just on the first word of the command -# line). -package build::command::user; - -use vars qw( @ISA ); - -BEGIN { @ISA = qw(build::command) } - -sub includes -{ - my ($self, $tgt) = @_; - my ($sig) = ''; - - # Check for any quick scanners attached to source files. - my $dep; - for $dep (@{$tgt->{dep}}, @{$tgt->{sources}}) - { - my ($scanner) = $dep->{'srcscan', $self->{env}}; - if ($scanner) - { - $sig .= $scanner->includes($tgt, $dep); - } - } - - # XXX Optimize this to not use ignored paths. - if (!exists $self->{_comsig}) - { - my ($env) = $self->{env}; - $self->{_comsig} = ''; - my ($com, $dir); - com: - for $com ($self->{act}->commands) - { - my ($pdirs) = $env->{ENV}->{PATH}; - if (!defined $pdirs) - { - $pdirs = []; - } - elsif (ref($pdirs) ne 'ARRAY') - { - $pdirs = [split (/$main::PATH_SEPARATOR/o, $pdirs)]; - } - for $dir (map($dir::top->lookupdir($_), @$pdirs)) - { - my ($prog) = $dir->lookup_accessible($com); - if ($prog) - { # XXX Not checking execute permission. - if ((build $prog) eq 'errors') - { - $tgt->{status} = 'errors'; - return $sig; - } - next com if $prog->ignore; - $self->{_comsig} .= 'sig'->signature($prog); - next com; - } - } - } - } - - return $self->{_comsig} . $sig; -} - -# Builder for a library module (archive). -# We assume that a user command might be built and implement the -# appropriate dependencies on the command itself. -package build::command::library; - -use vars qw( @ISA ); - -BEGIN { @ISA = qw(build::command) } - -sub find -{ - my ($class, $env) = @_; - bless find build::command($env, $env->{ARCOM}); -} - -# Always compatible with other library builders, so the user -# can define a single library from multiple places. -sub compatible -{ - my ($self, $other) = @_; - ref($other) eq "build::command::library"; -} - -# A multi-target builder. -# This allows multiple targets to be associated with a single build -# script, without forcing all the code to be aware of multiple targets. -package build::multiple; - -sub new -{ - my ($class, $builder, $tgts) = @_; - bless {'builder' => $builder, 'env' => $builder->{env}, 'tgts' => $tgts}; -} - -sub scriptsig -{ - my ($self, $tgt) = @_; - $self->{builder}->scriptsig($tgt); -} - -sub includes -{ - my ($self, $tgt) = @_; - $self->{builder}->includes($tgt); -} - -sub compatible -{ - my ($self, $tgt) = @_; - $self->{builder}->compatible($tgt); -} - -sub cachin -{ - my ($self, $tgt, $sig) = @_; - $self->{builder}->cachin($tgt, $sig); -} - -sub cachout -{ - my ($self, $tgt, $sig) = @_; - $self->{builder}->cachout($tgt, $sig); -} - -sub action -{ - my ($self, $invoked_tgt) = @_; - return $self->{built} if exists $self->{built}; - - # Make sure all targets in the group are unlinked before building any. - my ($tgts) = $self->{tgts}; - my $tgt; - for $tgt (@$tgts) - { - futil::mkdir($tgt->{dir}); - unlink($tgt->path) if !$tgt->precious; - } - - # Now do the action to build all the targets. For consistency - # we always call the action on the first target, just so that - # $> is deterministic. - if ($param::max_jobs <= 1) - { # pcons - $self->{built} = $self->{builder}->action($tgts->[0]); - } - else - { - { - - # action now is non-blocking, so we must kludge blocking for this - # explicit call - local ($file::child_queue) = {parent => $tgts->[0]}; # pcons - $self->{built} = $self->{builder}->action($tgts->[0]); # pcons - &file::wait_on_all_children(); # pcons - } - } - - # Now "build" all the other targets (except for the one - # we were called with). This guarantees that the signature - # of each target is updated appropriately. We force the - # targets to be built even if they have been previously - # considered and found to be OK; the only effect this - # has is to make sure that signature files are updated - # correctly. - for $tgt (@$tgts) - { - if ($tgt ne $invoked_tgt) - { - delete $tgt->{status}; - 'sig'->invalidate($tgt); - build $tgt; - } - } - - # Status of action. - $self->{built}; -} - -package action; - -sub new -{ - my ($env, $act) = @_; - if (ref($act) eq 'CODE') - { - return action::perl->new($act); - } - else - { - return action::command->new($env, $act); - } -} - -package action::command; - -use vars qw( @ISA %cmd %_varopts $_varletters ); - -BEGIN -{ - @ISA = $main::_WIN32 ? 'action::command::win32' : 'action::command::unix'; - - # Internal hash for processing variable options. - # f: return file part - # d: return directory part - # F: return file part, but strip any suffix - # b: return full path, but strip any suffix (a.k.a. return basename) - # s: return only the suffix (or an empty string, if no suffix is there) - # a: return the absolute path to the file - # S: return the absolute path to a Linked source file - %_varopts = ( - 'f' => sub { return $_[0]->{entry}; }, - 'd' => sub { return $_[0]->{dir}->path; }, - 'F' => sub { - my $subst = $_[0]->{entry}; - $subst =~ s/\.[^\.]+$//; - return $subst; - }, - 'b' => sub { - my $subst = $_[0]->path; - $subst =~ s/\.[^\.]+$//; - return $subst; - }, - 's' => sub { - my $subst = $_[0]->{entry}; - $subst =~ m/(\.[^\.]+)$/; - return $1; - }, - 'a' => sub { - my $path = $_[0]->path; - if (!File::Spec->file_name_is_absolute($path)) - { - $path = File::Spec->catfile(Cwd::cwd(), $path); - } - return $path; - }, - 'S' => sub { - my $path = $_[0]->srcpath; - if (!File::Spec->file_name_is_absolute($path)) - { - my $cwd = File::Spec->canonpath(Cwd::cwd()); - $path = File::Spec->catfile($cwd, $path); - } - return $path; - }, - ); - - $_varletters = join ('', keys %_varopts); -} - -# Internal routine for processing variable options. -# Options are specified in hash in the BEGIN block above. -# no option: return path to file (relative to top, -# or absolute if it's outside) -sub _variant -{ - my ($opt, $file) = @_; - $opt = '' if !defined $opt; - if (defined $_varopts{$opt}) - { - return &{$_varopts{$opt}} ($file); - } - return $file->path; -} - -sub new -{ - my ($class, $env, $cmd) = @_; - $cmd = $env->_subst($cmd); - $cmd{$env, $cmd} || do - { - - # Remove unwanted bits from signature -- those bracketed by %( ... %) - my $sigs = $cmd; - my $sig = ''; - if (ref($sigs) eq 'ARRAY') - { - - # This is an array of commands.. - my $f; - foreach $f (@$sigs) - { - $sig .= _strip($f); - } - } - else - { - $sig = _strip($sigs); - } - my $self = {cmd => $cmd, cmdsig => 'sig'->cmdsig($sig)}; - $cmd{$env, $cmd} = bless $self, $class; - }; -} - -sub _strip -{ - my $sig = shift; - $sig =~ s/^\@\s*//mg; - while ($sig =~ s/%\(([^%]|%[^\(])*?%\)//g) { } - $sig; -} - -sub scriptsig -{ - $_[0]->{cmdsig}; -} - -# Return an array of all the commands (first word on each line). -sub commands -{ - my ($self) = @_; - my (@cmds) = (); - my $com; - my $cmd = $self->{'cmd'}; - my @allcoms; - - push @allcoms, ref $cmd ? @{$cmd} : split (/\n/, $cmd); - - for $com (@allcoms) - { - $com =~ s/^\s*//; - $com =~ s/\s.*//; - next if !$com; # blank line - push @cmds, $com; - } - @cmds; -} - -# For the signature of a basic command, we don't bother -# including the command itself. This is not strictly correct, -# and if we wanted to be rigorous, we might want to insist -# that the command was checked for all the basic commands -# like gcc, etc. For this reason we don't have an includes -# method. - -# Call this to get the command line script: an array of -# fully substituted commands. -sub getcoms -{ - my ($self, $env, $tgt) = @_; - my (@coms); - my $com; - my @allcoms = (); - my $cmd = $self->{'cmd'}; - - push @allcoms, ref $cmd ? @{$cmd} : split (/\n/, $cmd); - - for $com (@allcoms) - { - my (@src) = (undef, @{$tgt->{sources}}); - my (@src1) = @src; - - next if $com =~ /^\s*$/; - - # NOTE: we used to have a more elegant s//.../e solution - # for the items below, but this caused a bus error... - - # Remove %( and %) -- those are only used to bracket parts - # of the command that we don't depend on. - $com =~ s/%[()]//g; - - # Deal with %n, n=1,9 and variants. - while ($com =~ /%([1-9])(:([$_varletters]?))?/o) - { - my ($match) = $&; - my ($src) = $src1[$1]; - my ($subst) = _variant($3, $src1[$1]->rfile); - undef $src[$1]; - $com =~ s/$match/$subst/; - } - - # Deal with %0 aka %> and variants. - while ($com =~ /%[0>](:([$_varletters]?))?/o) - { - my ($match) = $&; - my ($subst) = _variant($2, $tgt); - $com =~ s/$match/$subst/; - } - - # Deal with %< (all sources except %n's already used) - while ($com =~ /%<(:([$_varletters]?))?/o) - { - my ($match) = $&; - my @list = (); - foreach (@src) - { - push (@list, _variant($2, $_->rfile)) if $_; - } - my ($subst) = join (' ', @list); - $com =~ s/$match/$subst/; - } - - # Deal with %[ %]. - $com =~ s{%\[(.*?)%\]}{ - my($func, @args) = grep { $_ ne '' } split(/\s+/, $1); - die("$0: \"$func\" is not defined.\n") - unless ($env->{$func}); - &{$env->{$func}}(@args); - }gex; - - # Convert left-over %% into %. - $com =~ s/%%/%/g; - - # White space cleanup. XXX NO WAY FOR USER TO HAVE QUOTED SPACES - $com = join (' ', split (' ', $com)); - next if $com =~ /^:/ && $com !~ /^:\S/; - push (@coms, $com); - } - @coms; -} - -# Build the target using the previously specified commands. -sub execute -{ - my ($self, $env, $tgt, $package) = @_; - - if ($param::build) - { - futil::mkdir($tgt->{dir}); - unlink($tgt->path) if !$tgt->precious; - } - - # Set environment. - map(delete $ENV{$_}, keys %ENV); - %ENV = %{$env->{ENV}}; - - # Handle multi-line commands. - - my @cmds = $self->getcoms($env, $tgt); # pcons - if ($param::max_jobs > 1) - { # pcons - if ($#cmds > 0) - { - for ($i = 0 ; $i < @cmds ; $i++) - { #pcons -kn - $cmds[$i] = "( " . $cmds[$i] . " )"; #pcons -kn - } #pcons -kn - @cmds = join (" && ", @cmds); # pcons - } # pcons - } # pcons - - my $com; # pcons - for $com (@cmds) - { # pcons - if ($com !~ s/^\@\s*//) - { - main::showcom($com); - } - next if !$param::build; - - if ($com =~ /^\[perl\]\s*/) - { - my $perlcmd = $'; - my $status; - { - - # Restore the script package variables that were defined - # in the Conscript file that defined this [perl] build, - # so the code executes with the expected variables. - # Then actually execute (eval) the [perl] command to build - # the target, followed by cleaning up the name space - # by deleting the package variables we just restored. - my ($pkgvars) = $tgt->{conscript}->{pkgvars}; - NameSpace::restore($package, $pkgvars) if $pkgvars; - $status = eval "package $package; $perlcmd"; - NameSpace::remove($package, keys %$pkgvars) if $pkgvars; - } - if (!defined($status)) - { - warn "$0: *** Error during perl command eval: $@.\n"; - return undef; - } - elsif ($status == 0) - { - warn "$0: *** Perl command returned $status " - . "(this indicates an error).\n"; - return undef; - } - next; - } - if (!$self->do_command($com, $tgt->path, $tgt)) - { - return undef; - } - } - - # success. - return 1; -} - -sub show -{ - my ($self, $env, $tgt) = @_; - my $com; - for $com ($self->getcoms($env, $tgt)) - { - if ($com !~ /^\@\s*/) - { - main::showcom($com); - } - } -} - -package action::command::unix; - -sub do_command -{ - my ($class, $com, $path) = @_; # cons - my ($class, $com, $path, $tgt) = @_; # pcons - - if ($param::max_jobs > 1) - { # pcons - &file::wait_on_max_jobs(); # pcons - } # pcons - my ($pid) = fork(); - die ("$0: unable to fork child process ($!)\n") if !defined $pid; - if (!$pid) - { - - # This is the child. We eval the command to suppress -w - # warnings about not reaching the statements afterwards. - eval 'exec($com)'; - $com =~ s/\s.*//; - die qq($0: failed to execute "$com" ($!). ) - . qq(Is this an executable on path "$ENV{PATH}"?\n); - } - if ($param::max_jobs <= 1) - { # pcons - for (; ;) - { - do { } until wait() == $pid; - my ($b0, $b1) = ($? & 0xFF, $? >> 8); - - # Don't actually see 0177 on stopped process; is this necessary? - next if $b0 == 0177; # process stopped; we can wait. - if ($b0) - { - my ($core, $sig) = ($b0 & 0200, $b0 & 0177); - my ($coremsg) = $core ? "; core dumped" : ""; - $com =~ s/\s.*//; - my $err = - "$0: *** \[$path\] $com terminated by signal " - . "$sig$coremsg\n"; - warn $err; - return undef; - } - if ($b1) - { - warn qq($0: *** [$path] Error $b1\n); # trying to be like make. - return undef; - } - last; - } - } - else - { # pcons - $file::child_queue->{$pid}->{com} = $com; # pcons - $file::child_queue->{$pid}->{tgt} = $tgt; # pcons - - } # pcons - - return 1; -} - -package action::command::win32; - -sub do_command -{ - my ($class, $com, $path, $tgt) = @_; - system($com); - if ($?) - { - my ($b0, $b1) = ($? & 0xFF, $? >> 8); - my $err = $b1 || $?; - my $warn = qq($0: *** [$path] Error $err); - $warn .= " (executable not found in path?)" if $b1 == 0xFF; - warn "$warn\n"; - return undef; - } - return 1; -} - -package action::perl; - -# THIS IS AN EXPERIMENTAL PACKAGE. It's entirely possible that the -# interface may change as this gets completed, so use at your own risk. -# -# There are (at least) two issues that need to be solved before blessing -# this as a real, fully-supported feature: -# -# -- We need to calculate a signature value for a Perl code ref, in -# order to rebuild the target if there's a change to the Perl code -# used to generate it. -# -# This is not straightforward. A B::Deparse package exists that -# decompiles a coderef into text. It's reportedly not completely -# reliable for closures; it misses which variables are global, and -# the values of private lexicals. Nevertheless, it'd probably -# be perfect for our purposes, except that it wasn't added until -# some time between Perl 5.00502 and 5.00554, and doesn't seem to -# really work until Perl 5.6.0, so by relying on it, we'd lose -# support for Perl versions back to 5.003*. -# -# -- Ideally, a code ref should be able to use something like -# $env->_subst to fetch values from the construction environment -# to modify its behavior without having to cut-and-paste code. -# (Actually, since we pass the environment to the executed code -# ref, there's no reason you can't do this with the code as it -# stands today.) But this REALLY complicates the signature -# calculation, because now the actual signature would depend not -# just on the code contents, but on the construction variables (or -# maybe just the environment). -# -# A potentially valid workaround would be to use the contents of the -# Conscript file in which the code reference is defined as the code -# ref's signature. This has the drawback of causing a recompilation of -# the target file even in response to unrelated changes in the Conscript -# file, but it would ensure correct builds without having to solve the -# messy issues of generating a signature directly from a code ref. -# -# Nevertheless, this seemed a useful enough skeleton of a feature that -# it made sense to release it in hopes that some practical experience -# will encourage someone to figure out how to solve the signature -# issues. Or maybe we'll discover these aren't big issues in practice -# and end up blessing it as is. - -use vars qw( %code ); - -sub new -{ - my ($class, $cref) = @_; - $code{$cref} || do - { - my $sig = ''; - - # Generating a code signature using B::Deparse doesn't really - # work for us until Perl 5.6.0. Here's the code in case - # someone wants to use it. - #use B::Deparse; - #my $deparse = B::Deparse->new(); - #my $body = $deparse->coderef2text($cref); - #$sig = $body; # should be an MD5 sig - my ($self) = {cref => $cref, crefsig => $sig}; - $code{$cref} = bless $self, $class; - } -} - -sub scriptsig -{ - $_[0]->{crefsig}; -} - -sub execute -{ - my ($self, $env, $tgt) = @_; - if ($param::build) - { - futil::mkdir($tgt->{dir}); - unlink($tgt->path) if !$tgt->precious; - my ($cref) = $self->{cref}; - &$cref($env, $tgt->path, map($_->rpath, @{$tgt->{sources}})); - } -} - -sub commands -{ - return (); -} - -# Generic scanning module. -package scan; - -# Returns the signature of files included by the specified files on -# behalf of the associated target. Any errors in handling the included -# files are propagated to the target on whose behalf this processing -# is being done. Signatures are cached for each unique file/scanner -# pair. -sub includes -{ - my ($self, $tgt, @files) = @_; - my (%files, $file); - my ($inc) = $self->{includes} || ($self->{includes} = {}); - while ($file = pop @files) - { - next if exists $files{$file}; - if ($inc->{$file}) - { - push (@files, @{$inc->{$file}}); - $files{$file} = 'sig'->signature($file->rfile); - } - else - { - if ((build $file) eq 'errors') - { - $tgt->{status} = 'errors'; # tgt inherits build status - return (); - } - $files{$file} = 'sig'->signature($file->rfile); - my (@includes) = $self->scan($file); - $inc->{$file} = \@includes; - push (@files, @includes); - } - } - 'sig'->collect(sort values %files); -} - -# A simple scanner. This is used by the QuickScanfunction, to setup -# one-time target and environment-independent scanning for a source -# file. Only used for commands run by the Command method. -package scan::quickscan; - -use vars qw( @ISA %scanner ); - -BEGIN { @ISA = qw(scan) } - -sub find -{ - my ($class, $code, $env, $pdirs) = @_; - if (!defined $pdirs) - { - $pdirs = []; - } - elsif (ref($pdirs) ne 'ARRAY') - { - $pdirs = [split (/$main::PATH_SEPARATOR/o, $pdirs)]; - } - my (@path) = map { $dir::cwd->lookupdir($_) } @$pdirs; - my ($spath) = "@path"; - $scanner{$code, $env, $spath} || do - { - my ($self) = {code => $code, env => $env, path => \@path}; - $scanner{$code, $env, $spath} = bless $self; - } -} - -# Scan the specified file for included file names. -sub scan -{ - my ($self, $file) = @_; - my ($code) = $self->{code}; - my (@includes); - - # File should have been built by now. If not, we'll ignore it. - return () unless open(SCAN, $file->rpath); - while (<SCAN>) - { - push (@includes, grep($_ ne '', &$code)); - } - close(SCAN); - my ($wd) = $file->{dir}; - my (@files); - my $name; - for $name (@includes) - { - my $dir; - for $dir ($file->{dir}, @{$self->{path}}) - { - my ($include) = $dir->lookup_accessible($name); - if ($include) - { - push (@files, $include) unless $include->ignore; - last; - } - } - } - @files; -} - -# CPP (C preprocessor) scanning module -package scan::cpp; - -use vars qw( @ISA %scanner ); - -BEGIN { @ISA = qw(scan) } - -# For this constructor, provide the include path argument (colon -# separated). Each path is taken relative to the provided directory. - -# Note: a particular scanning object is assumed to always return the -# same result for the same input. This is why the search path is a -# parameter to the constructor for a CPP scanning object. We go to -# some pains to make sure that we return the same scanner object -# for the same path: otherwise we will unecessarily scan files. -sub find -{ - my ($class, $dir, $pdirs) = @_; - if (!defined $pdirs) - { - $pdirs = []; - } - elsif (ref($pdirs) ne 'ARRAY') - { - $pdirs = [split (/$main::PATH_SEPARATOR/o, $pdirs)]; - } - my @path = map($dir->lookupdir($_), @$pdirs); - my ($spath) = "@path"; - $scanner{$spath} || do - { - my ($self) = {'path' => \@path}; - $scanner{$spath} = bless $self; - } -} - -# Scan the specified file for include lines. -sub scan -{ - my ($self, $file) = @_; - my ($angles, $quotes); - - if (exists $file->{angles}) - { - $angles = $file->{angles}; - $quotes = $file->{quotes}; - } - else - { - my (@anglenames, @quotenames); - return () unless open(SCAN, $file->rpath); - while (<SCAN>) - { - next unless /^\s*#/; - if (/^\s*#\s*include\s*([<"])(.*?)[>"]/) - { - if ($1 eq "<") - { - push (@anglenames, $2); - } - else - { - push (@quotenames, $2); - } - } - } - close(SCAN); - $angles = $file->{angles} = \@anglenames; - $quotes = $file->{quotes} = \@quotenames; - } - - my (@shortpath) = @{$self->{path}}; # path for <> style includes - my (@longpath) = ($file->{dir}, @shortpath); # path for "" style includes - - my (@includes); - - my $name; - for $name (@$angles) - { - my $dir; - for $dir (@shortpath) - { - my ($include) = $dir->lookup_accessible($name); - if ($include) - { - push (@includes, $include) unless $include->ignore; - last; - } - } - } - - for $name (@$quotes) - { - my $dir; - for $dir (@longpath) - { - my ($include) = $dir->lookup_accessible($name); - if ($include) - { - push (@includes, $include) unless $include->ignore; - last; - } - } - } - - return @includes; -} - -# Return the include flags that would be used for a C Compile. -sub iflags -{ - my ($self, $env) = @_; - my ($iflags) = ''; - my ($dir, $dpath); - for $dir (@{$self->{path}}) - { - $dpath = $dir->path; - - # Add the (presumably local) directory to the -I flags - # if we're not using repositories, the directory exists, - # or it's Linked to a source directory (that is, it *will* - # exist by the time the compilation occurs). - $iflags .= " " . $env->{INCDIRPREFIX} . $dpath . $env->{INCDIRSUFFIX} - if !@param::rpath || -d $dpath || $dir->is_linked; - next if File::Spec->file_name_is_absolute($dpath); - if (@param::rpath) - { - my $d; - if ($dpath eq $dir::CURDIR) - { - foreach $d (map($_->path, @param::rpath)) - { - $iflags .= - " " . $env->{INCDIRPREFIX} . $d . $env->{INCDIRSUFFIX}; - } - } - else - { - my ($rpath); - foreach $d (map($_->path, @param::rpath)) - { - $rpath = File::Spec->catfile($d, $dpath); - $iflags .= - " " . $env->{INCDIRPREFIX} . $rpath . $env->{INCDIRSUFFIX} - if -d $rpath; - } - } - } - } - $iflags; -} - -package File::Spec; - -use vars qw( $_SEP $_MATCH_SEP $_MATCH_VOL ); - -# Cons is migrating to using File::Spec for portable path name -# manipulation. This is the right long-term direction, but there are -# some problems with making the transition: -# -# For multi-volume support, we need to use newer interfaces -# (splitpath, catpath, splitdir) that are only available in -# File::Spec 0.8. -# -# File::Spec 0.8 doesn't work with Perl 5.00[34] due to -# regular expression incompatibilities (use of \z). -# -# Forcing people to use a new version of a module is painful -# because (in the workplace) their administrators aren't -# always going to agree to install it everywhere. -# -# As a middle ground, we provide our own versions of all the File::Spec -# methods we use, supporting both UNIX and Win32. Some of these methods -# are home brew, some are cut-and-pasted from the real File::Spec methods. -# This way, we're not reinventing the whole wheel, at least. -# -# We can (and should) get rid of this class whenever 5.00[34] and -# versions of File::Spec prior to 0.9 (?) have faded sufficiently. -# We also may need to revisit whenever someone first wants to use -# Cons on some platform other than UNIX or Win32. - -BEGIN -{ - if ($main::_WIN32) - { - $_SEP = '\\'; - $_MATCH_SEP = "[\Q/$_SEP\E]"; - $_MATCH_VOL = "([a-z]:)?$_MATCH_SEP"; - } - else - { - $_SEP = '/'; - $_MATCH_SEP = "\Q$_SEP\E"; - $_MATCH_VOL = $_MATCH_SEP; - } -} - -sub canonpath -{ - my ($self, $path) = @_; - if ($main::_WIN32) - { - $path =~ s/^([a-z]:)/\u$1/s; - $path =~ s|/|\\|g; - $path =~ s|([^\\])\\+|$1\\|g; # xx////xx -> xx/xx - $path =~ s|(\\\.)+\\|\\|g; # xx/././xx -> xx/xx - $path =~ s|^(\.\\)+||s unless $path eq ".\\"; # ./xx -> xx - $path =~ s|\\$|| unless $path =~ m#^([A-Z]:)?\\$#s; # xx/ -> xx - } - else - { - $path =~ s|/+|/|g unless ($^O eq 'cygwin'); # xx////xx -> xx/xx - $path =~ s|(/\.)+/|/|g; # xx/././xx -> xx/xx - $path =~ s|^(\./)+||s unless $path eq "./"; # ./xx -> xx - $path =~ s|^/(\.\./)+|/|s; # /../../xx -> xx - $path =~ s|/$|| unless $path eq "/"; # xx/ -> xx - } - return $path; -} - -sub catdir -{ - my $self = shift; - my @args = @_; - foreach (@args) - { - - # append a slash to each argument unless it has one there - $_ .= $_SEP if $_ eq '' || substr($_, -1) ne $_SEP; - } - return $self->canonpath(join ('', @args)); -} - -sub catfile -{ - my $self = shift; - my $file = pop @_; - return $file unless @_; - my $dir = $self->catdir(@_); - $dir .= $_SEP unless substr($dir, -1) eq $_SEP; - $file = '' if !defined($file); - return $dir . $file; -} - -sub catpath -{ - my $path = $_[1] . $_[0]->catfile(@_[2 .. $#_]); - $path =~ s/(.)$_MATCH_SEP*$/$1/; - $path; -} - -sub curdir -{ - '.'; -} - -sub file_name_is_absolute -{ - my ($self, $file) = @_; - return scalar($file =~ m{^$_MATCH_VOL}is); -} - -sub splitdir -{ - my @dirs = split (/$_MATCH_SEP/, $_[1], -1); - push (@dirs, '') if $dirs[$#dirs]; - @dirs; -} - -sub splitpath -{ - my ($self, $path) = @_; - my $vol = ''; - my $sep = $_SEP; - if ($main::_WIN32) - { - if ($path =~ s#^([A-Za-z]:|(?:\\\\|//)[^\\/]+[\\/][^\\/]+)([\\/])#$2#) - { - $vol = $1; - $sep = $2; - } - } - my (@path) = split (/$_MATCH_SEP/, $path, -1); - my $file = pop @path; - my $dirs = join ($sep, @path, ''); - return ($vol, $dirs, $file); -} - -sub updir -{ - '..'; -} - -sub case_tolerant -{ - return $main::_WIN32; -} - -# Directory and file handling. Files/dirs are represented by objects. -# Other packages are welcome to add component-specific attributes. -package dir; - -use vars qw( $SEPARATOR $MATCH_SEPARATOR $CURDIR $UPDIR - $cwd_vol %root $top $cwd ); - -BEGIN -{ - - # A portable way of determing our directory separator. - $SEPARATOR = File::Spec->catdir('', ''); - - # A fast-path regular expression to match a directory separator - # anywhere in a path name. - if ($SEPARATOR eq '/') - { - $MATCH_SEPARATOR = "\Q$SEPARATOR\E"; - } - else - { - $MATCH_SEPARATOR = "[\Q/$SEPARATOR\E]"; - } - - # Cache these values so we don't have to make a method call - # every time we need them. - $CURDIR = File::Spec->curdir; # '.' on UNIX - $UPDIR = File::Spec->updir; # '..' on UNIX - # - $cwd_vol = ''; -} - -# Annotate a node (file or directory) with info about the -# method that created it. -sub creator -{ - my ($self, @frame) = @_; - $self->{'creator'} = \@frame if @frame; - $self->{'creator'}; -} - -# Handle a file|dir type exception. We only die if we find we were -# invoked by something in a Conscript/Construct file, because -# dependencies created directly by Cons' analysis shouldn't cause -# an error. -sub _type_exception -{ - my ($e) = @_; - my ($line, $sub); - (undef, undef, $line, $sub) = script::caller_info; - if (defined $line) - { - my $err = - "\"${\$e->path}\" already in use as a " - . ref($e) - . " before $sub on line $line"; - if ($e->{'creator'}) - { - my $script; - (undef, $script, $line, $sub) = @{$e->{'creator'}}; - $err = - "\t" . $err . ",\n\t\tdefined by $sub in $script, line $line"; - } - $err .= "\n"; - die $err; - } -} - -# This wraps up all the common File::Spec logic that we use for parsing -# directory separators in a path and turning it into individual -# subdirectories that we must create, as well as creation of root -# nodes for any new file system volumes we find. File::Spec doesn't have -# intuitively obvious interfaces, so this is heavily commented. -# -# Note: This is NOT an object or class method; -# it's just a utility subroutine. -sub _parse_path -{ - my ($dir, $path) = @_; - - # Convert all slashes to the native directory separator. - # This allows Construct files to always be written with good - # old POSIX path names, regardless of what we're running on. - $path = File::Spec->canonpath($path); - - # File::Spec doesn't understand the Cons convention of - # an initial '#' for top-relative files. Strip it. - my ($toprel) = $path =~ s/^#//; - - # Let File::Spec do the heavy lifting of parsing the path name. - my ($vol, $directories, $entry) = File::Spec->splitpath($path); - my @dirs = File::Spec->splitdir($directories); - - # If there was a file entry on the end of the path, then the - # last @dirs element is '' and we don't need it. If there - # wasn't a file entry on the end (File::Spec->splitpath() knew - # the last component was a directory), then the last @dirs - # element becomes the entry we want to look up. - my ($e) = pop @dirs; - $entry = $e if $entry eq ''; - - if (File::Spec->file_name_is_absolute($path)) - { - - # An absolute path name. If no volume was supplied, - # use the volume of our current directory. - $vol = $cwd_vol if $vol eq ''; - $vol = uc($vol) if File::Spec->case_tolerant; - if (!defined $root{$vol}) - { - - # This is our first time looking up a path name - # on this volume, so create a root node for it. - # (On UNIX systems, $vol is always '', so '/' - # always maps to the $root{''} node.) - $root{$vol} = { - path => $vol . $SEPARATOR, - prefix => $vol . $SEPARATOR, - srcpath => $vol . $SEPARATOR, - 'exists' => 1 - }; - $root{$vol}->{'srcdir'} = $root{$vol}; - bless $root{$vol}; - } - - # We're at the top, so strip the blank entry from the front of - # the @dirs array since the initial '/' it represents will now - # be supplied by the root node we return. - shift @dirs; - $dir = $root{$vol}; - } - elsif ($toprel) - { - $dir = $dir::top; - } - ($dir, \@dirs, $entry); -} - -# Common subroutine for creating directory nodes. -sub _create_dirs -{ - my ($dir, @dirs) = @_; - my $e; - foreach $e (@dirs) - { - my $d = $dir->{member}->{$e}; - if (!defined $d) - { - bless $d = {'entry' => $e, 'dir' => $dir,}, 'dir'; - $d->creator(script::caller_info); - $d->{member}->{$dir::CURDIR} = $d; - $d->{member}->{$dir::UPDIR} = $dir; - $dir->{member}->{$e} = $d; - } - elsif (ref $d eq 'entry') - { - bless $d, 'dir'; - $d->{member}->{$dir::CURDIR} = $d; - $d->{member}->{$dir::UPDIR} = $dir; - } - elsif (ref $d eq 'file') - { - - # This clause is to supply backwards compatibility, - # with a warning, for anyone that's used FilePath - # to refer to a directory. After people have using - # 1.8 have had time to adjust (sometime in version - # 1.9 or later), we should remove this entire clause. - my ($script, $line, $sub); - (undef, $script, $line, $sub) = @{$d->{'creator'}}; - if ($sub eq 'script::FilePath') - { - print STDERR - "$0: Warning: $sub used to refer to a directory\n" - . "\tat line $line of $script. Use DirPath instead.\n"; - bless $d, 'dir'; - } - else - { - _type_exception($d); - } - } - elsif (ref $d ne 'dir') - { - _type_exception($d); - } - $dir = $d; - } - $dir; -} - -# Look up an entry in a directory. This method is for when we don't -# care whether a file or directory is returned, so if the entry already -# exists, it will simply be returned. If not, we create it as a -# generic "entry" which can be later turned into a file or directory -# by a more-specific lookup. -# -# The file entry may be specified as relative, absolute (starts with /), -# or top-relative (starts with #). -sub lookup -{ - my ($dir, $entry) = @_; - - if ($entry !~ m#$MATCH_SEPARATOR#o) - { - - # Fast path: simple entry name in a known directory. - if ($entry =~ s/^#//) - { - - # Top-relative names begin with #. - $dir = $dir::top; - } - elsif ($entry =~ s/^!//) - { - $dir = $dir::cwd->srcdir; - } - } - else - { - my $dirsref; - ($dir, $dirsref, $entry) = _parse_path($dir, $entry); - $dir = _create_dirs($dir, @$dirsref) if @$dirsref; - return if !defined $dir; - return $dir if $entry eq ''; - } - - my $e = $dir->{member}->{$entry}; - if (!defined $e) - { - bless $e = {'entry' => $entry, 'dir' => $dir,}, 'entry'; - $e->creator(script::caller_info); - $dir->{member}->{$entry} = $e; - } - - $e; -} - -# Look up a file entry in a directory. -# -# The file entry may be specified as relative, absolute (starts with /), -# or top-relative (starts with #). -sub lookupfile -{ - my ($dir, $entry) = @_; - - if ($entry !~ m#$MATCH_SEPARATOR#o) - { - - # Fast path: simple entry name in a known directory. - if ($entry =~ s/^#//) - { - - # Top-relative names begin with #. - $dir = $dir::top; - } - elsif ($entry =~ s/^!//) - { - $dir = $dir::cwd->srcdir; - } - } - else - { - my $dirsref; - ($dir, $dirsref, $entry) = _parse_path($dir, $entry); - $dir = _create_dirs($dir, @$dirsref) if @$dirsref; - return undef if $entry eq ''; - } - - my $f = $dir->{member}->{$entry}; - if (!defined $f) - { - bless $f = {'entry' => $entry, 'dir' => $dir,}, 'file'; - $f->creator(script::caller_info); - $dir->{member}->{$entry} = $f; - } - elsif (ref $f eq 'entry') - { - bless $f, 'file'; - } - elsif (ref $f ne 'file') - { - _type_exception($f); - } - - $f; -} - -# Look up a (sub-)directory entry in a directory. -# -# The (sub-)directory entry may be specified as relative, absolute -# (starts with /), or top-relative (starts with #). -sub lookupdir -{ - my ($dir, $entry) = @_; - - my $dirsref; - if ($entry !~ m#$MATCH_SEPARATOR#o) - { - - # Fast path: simple entry name in a known directory. - if ($entry =~ s/^#//) - { - - # Top-relative names begin with #. - $dir = $dir::top; - } - elsif ($entry =~ s/^!//) - { - $dir = $dir::cwd->srcdir; - } - } - else - { - ($dir, $dirsref, $entry) = _parse_path($dir, $entry); - } - push (@$dirsref, $entry) if $entry ne ''; - _create_dirs($dir, @$dirsref); -} - -# Look up a file entry and return it if it's accessible. -sub lookup_accessible -{ - my $file = $_[0]->lookupfile($_[1]); - return ($file && $file->accessible) ? $file : undef; -} - -# Return the parent directory without doing a lookupdir, -# which would create a parent if it doesn't already exist. -# A return value of undef (! $dir->up) indicates a root directory. -sub up -{ - $_[0]->{member}->{$dir::UPDIR}; -} - -# Return whether this is an entry somewhere underneath the -# specified directory. -sub is_under -{ - my $dir = $_[0]; - while ($dir) - { - return 1 if $_[1] == $dir; - $dir = $dir->up; - } - return undef; -} - -# Return the relative path from the calling directory ($_[1]) -# to the object. If the object is not under the directory, then -# we return it as a top-relative or absolute path name. -sub relpath -{ - my ($dir, $obj) = @_; - my @dirs; - my $o = $obj; - while ($o) - { - if ($dir == $o) - { - if (@dirs < 2) - { - return $dirs[0] || ''; - } - else - { - return File::Spec->catdir(@dirs); - } - } - unshift (@dirs, $o->{entry}); - $o = $o->up; - } - - # The object was not underneath the specified directory. - # Use the node's cached path, which is either top-relative - # (in which case we append '#' to the beginning) or - # absolute. - my $p = $obj->path; - $p = '#' . $p if !File::Spec->file_name_is_absolute($p); - return $p; -} - -# Return the path of the directory (file paths implemented -# separately, below). -sub path -{ - $_[0]->{path} || ($_[0]->{path} = $_[0]->{dir}->prefix . $_[0]->{entry}); -} - -# Return the pathname as a prefix to be concatenated with an entry. -sub prefix -{ - return $_[0]->{prefix} if exists $_[0]->{prefix}; - $_[0]->{prefix} = $_[0]->path . $SEPARATOR; -} - -# Return the related source path prefix. -sub srcprefix -{ - return $_[0]->{srcprefix} if exists $_[0]->{srcprefix}; - my ($srcdir) = $_[0]->srcdir; - $srcdir->{srcprefix} = - $srcdir eq $_[0] ? $srcdir->prefix : $srcdir->srcprefix; -} - -# Return the related source directory. -sub srcdir -{ - $_[0]->{'srcdir'} - || ($_[0]->{'srcdir'} = $_[0]->{dir}->srcdir->lookupdir($_[0]->{entry})); -} - -# Return if the directory is linked to a separate source directory. -sub is_linked -{ - return $_[0]->{is_linked} if defined $_[0]->{is_linked}; - $_[0]->{is_linked} = $_[0]->path ne $_[0]->srcdir->path; -} - -sub link -{ - my (@paths) = @_; - my ($srcdir) = $dir::cwd->lookupdir(pop @paths)->srcdir; - map($dir::cwd->lookupdir($_)->{'srcdir'} = $srcdir, @paths); - - # make a reverse lookup for the link. - $srcdir->{links} = [] if !$srcdir->{links}; - push @{$srcdir->{links}}, @paths; -} - -use vars qw( @tail ); # TODO: Why global ???? - -sub linked_targets -{ - my $tgt = shift; - my @targets = (); - my $dir; - if (ref $tgt eq 'dir') - { - $dir = $tgt; - } - else - { - push @tail, $tgt; - $dir = $tgt->{dir}; - } - while ($dir) - { - if (defined $dir->{links} && @{$dir->{links}}) - { - push @targets, map(File::Spec->catdir($_, @tail), @{$dir->{links}}); - - #print STDERR "Found Link: ${\$dir->path} -> @{\$dir->{links}}\n"; - } - unshift @tail, $dir->{entry}; - $dir = $dir->up; - } - - return map($dir::top->lookupdir($_), @targets); -} - -sub accessible -{ - my $path = $_[0]->path; - my $err = - "$0: you have attempted to use path \"$path\" both as a file " - . "and as a directory!\n"; - die $err; -} - -sub init -{ - my $path = Cwd::cwd(); - - # We know we can get away with passing undef to lookupdir - # as the directory because $dir is an absolute path. - $top = lookupdir(undef, $path); - $top->{'path'} = $top->{srcpath} = $dir::CURDIR; - $top->{'prefix'} = ''; - $top->{'srcdir'} = $top; - - $cwd = $top; - - ($cwd_vol, undef, undef) = File::Spec->splitpath($path); - $cwd_vol = '' if !defined $cwd_vol; - $cwd_vol = uc($cwd_vol) if File::Spec->case_tolerant; -} - -package file; - -use vars qw( @ISA $level ); - -BEGIN { @ISA = qw(dir); $level = 0 } - -# Return the pathname of the file. -# Define this separately from dir::path because we don't want to -# cache all file pathnames (just directory pathnames). -sub path -{ - $_[0]->{dir}->prefix . $_[0]->{entry}; -} - -# Return the related source file path. -sub srcpath -{ - $_[0]->{dir}->srcprefix . $_[0]->{entry}; -} - -# Return if the file is (should be) linked to a separate source file. -sub is_linked -{ - $_[0]->{dir}->is_linked; -} - -# Repository file search. If the local file exists, that wins. -# Otherwise, return the first existing same-named file under a -# Repository directory. If there isn't anything with the same name -# under a Repository directory, return the local file name anyway -# so that some higher layer can try to construct it. -sub rfile -{ - return $_[0]->{rfile} if exists $_[0]->{rfile}; - my ($self) = @_; - my ($rfile) = $self; - if (@param::rpath) - { - my ($path) = $self->path; - if (!File::Spec->file_name_is_absolute($path) && !-f $path) - { - my ($dir); - foreach $dir (@param::rpath) - { - my ($t) = $dir->prefix . $path; - if (-f $t) - { - $rfile = $_[0]->lookupfile($t); - $rfile->{'lfile'} = $self; - last; - } - } - } - } - $self->{rfile} = $rfile; -} - -# Returns the local file for a repository file; -# returns self if it's already a local file. -sub lfile -{ - $_[0]->{'lfile'} || $_[0]; -} - -# returns the "precious" status of this file. -sub precious -{ - return $_[0]->{precious}; -} - -# "Erase" reference to a Repository file, -# making this a completely local file object -# by pointing it back to itself. -sub no_rfile -{ - $_[0]->{'rfile'} = $_[0]; -} - -# Return a path to the first existing file under a Repository directory, -# implicitly returning the current file's path if there isn't a -# same-named file under a Repository directory. -sub rpath -{ - $_[0]->{rpath} || ($_[0]->{rpath} = $_[0]->rfile->path); -} - -# Return a path to the first linked srcpath file under a Repositoy -# directory, implicitly returning the current file's srcpath if there -# isn't a same-named file under a Repository directory. -sub rsrcpath -{ - return $_[0]->{rsrcpath} if exists $_[0]->{rsrcpath}; - my ($self) = @_; - my ($path) = $self->{rsrcpath} = $self->srcpath; - if (@param::rpath && !File::Spec->file_name_is_absolute($path) && !-f $path) - { - my ($dir); - foreach $dir (@param::rpath) - { - my ($t) = $dir->prefix . $path; - if (-f $t) - { - $self->{rsrcpath} = $t; - last; - } - } - } - $self->{rsrcpath}; -} - -# Return if a same-named file source file exists. -# This handles the interaction of Link and Repository logic. -# As a side effect, it will link a source file from its Linked -# directory (preferably local, but maybe in a repository) -# into a build directory from its proper Linked directory. -sub source_exists -{ - return $_[0]->{source_exists} if defined $_[0]->{source_exists}; - my ($self) = @_; - my ($path) = $self->path; - my ($mtime, $ctime) = (stat($path))[9, 10]; - if ($self->is_linked) - { - - # Linked directory, local logic. - my ($srcpath) = $self->srcpath; - my ($src_mtime, $src_ctime) = (stat($srcpath))[9, 10]; - if ($src_mtime) - { - if (!$mtime || $src_mtime != $mtime || $src_ctime != $ctime) - { - futil::install($srcpath, $self); - } - return $self->{source_exists} = 1; - } - - # Linked directory, repository logic. - if (@param::rpath) - { - if ($self != $self->rfile) - { - return $self->{source_exists} = 1; - } - my ($rsrcpath) = $self->rsrcpath; - if ($path ne $rsrcpath) - { - my ($rsrc_mtime, $rsrc_ctime) = (stat($rsrcpath))[9, 10]; - if ($rsrc_mtime) - { - if (!$mtime - || $rsrc_mtime != $mtime - || $rsrc_ctime != $ctime) - { - futil::install($rsrcpath, $self); - } - return $self->{source_exists} = 1; - } - } - } - - # There was no source file in any Linked directory - # under any Repository. If there's one in the local - # build directory, it no longer belongs there. - if ($mtime) - { - unlink($path) || die ("$0: couldn't unlink $path ($!)\n"); - } - return $self->{source_exists} = ''; - } - else - { - if ($mtime) - { - return $self->{source_exists} = 1; - } - if (@param::rpath && $self != $self->rfile) - { - return $self->{source_exists} = 1; - } - return $self->{source_exists} = ''; - } -} - -# Return if a same-named derived file exists under a Repository directory. -sub derived_exists -{ - $_[0]->{derived_exists} - || ($_[0]->{derived_exists} = ($_[0] != $_[0]->rfile)); -} - -# Return if this file is somewhere under a Repository directory. -sub is_on_rpath -{ - defined $_[0]->{'lfile'}; -} - -sub local -{ - my ($self, $arg) = @_; - if (defined $arg) - { - $self->{'local'} = $arg; - } - $self->{'local'}; -} - -# Return the entry name of the specified file with the specified -# suffix appended. Leave it untouched if the suffix is already there. -# Differs from the addsuffix function, below, in that this strips -# the existing suffix (if any) before appending the desired one. -sub base_suf -{ - my ($entry) = $_[0]->{entry}; - if ($entry !~ m/$_[1]$/) - { - $entry =~ s/\.[^\.]*$//; - $entry .= $_[1]; - } - $entry; -} - -# Return the suffix of the file; everything including and to the -# right of the last dot. -sub suffix -{ - my @pieces = split (/\./, $_[0]->{entry}); - my $suffix = pop (@pieces); - return ".$suffix"; -} - -# Called as a simple function file::addsuffix(name, suffix) -sub addsuffix -{ - my ($name, $suffix) = @_; - - if ($suffix && substr($name, -length($suffix)) ne $suffix) - { - return $name .= $suffix; - } - $name; -} - -# Return true if the file is (or will be) accessible. -# That is, if we can build it, or if it is already present. -sub accessible -{ - (exists $_[0]->{builder}) || ($_[0]->source_exists); -} - -# Return true if the file should be ignored for the purpose -# of computing dependency information (should not be considered -# as a dependency and, further, should not be scanned for -# dependencies). -sub ignore -{ - return 0 if !$param::ignore; - return $_[0]->{ignore} if exists $_[0]->{ignore}; - $_[0]->{ignore} = $_[0]->path =~ /$param::ignore/o; -} - -# Build the file, if necessary. -sub build -{ - return $_[0]->{status} if $_[0]->{status}; - my ($status) = &file::_build; - if ($_[0]->{after_build_func}) - { - - #print STDERR "DEBUG: after_build_func=$_[0]->{after_build_func}\n"; - my ($pkgvars) = $_[0]->{conscript}->{pkgvars}; - NameSpace::restore('script', $pkgvars) if $pkgvars; - eval("package script; " . $_[0]->{after_build_func}); - print "Error running AfterBuild for ${\$_[0]->path}: $@\n" if ($@); - NameSpace::remove('script', keys %$pkgvars) if $pkgvars; - } - return $status; -} - -sub _build -{ - my @args = @_; - - if ($param::max_jobs <= 1) - { # pcons - my ($self) = @args; - print main::DEPFILE $self->path, "\n" if $param::depfile; - print((' ' x $level), "Checking ", $self->path, "\n") - if $param::depends; - if (!exists $self->{builder}) - { - - # We don't know how to build the file. This is OK, if - # the file is present as a source file, under either the - # local tree or a Repository. - if ($self->source_exists) - { - return $self->{status} = 'handled'; - } - else - { - my ($name) = $self->path; - print("$0: don't know how to construct \"$name\"\n"); - exit(1) unless $param::kflag; - return $self->{status} = 'errors'; # xxx used to be 'unknown' - } - } - - # An associated build object exists, so we know how to build - # the file. We first compute the signature of the file, based - # on its dependendencies, then only rebuild the file if the - # signature has changed. - my ($builder) = $self->{builder}; - $level += 2; - - my (@deps) = (@{$self->{dep}}, @{$self->{sources}}); - my ($rdeps) = \@deps; - - if ($param::random) - { - - # If requested, build in a random order, instead of the - # order that the dependencies were listed. - my (%rdeps); - map { $rdeps{$_, '*' x int(rand 10)} = $_ } @deps; - $rdeps = [values(%rdeps)]; - } - - $self->{status} = ''; - - my $dep; - for $dep (@$rdeps) - { - if ((build $dep) eq 'errors') - { - - # Propagate dependent errors to target. - # but try to build all dependents regardless of errors. - $self->{status} = 'errors'; - } - } - - # If any dependents had errors, then we abort. - if ($self->{status} eq 'errors') - { - $level -= 2; - return 'errors'; - } - - # Compute the final signature of the file, based on - # the static dependencies (in order), dynamic dependencies, - # output path name, and (non-substituted) build script. - my ($sig) = - 'sig'->collect(map('sig'->signature($_->rfile), @deps), - $builder->includes($self), $builder->scriptsig); - - # May have gotten errors during computation of dynamic - # dependency signature, above. - $level -= 2; - return 'errors' if $self->{status} eq 'errors'; - - if (@param::rpath && $self->derived_exists) - { - - # There is no local file of this name, but there is one - # under a Repository directory. - - if ('sig'->current($self->rfile, $sig)) - { - - # The Repository copy is current (its signature matches - # our calculated signature). - if ($self->local) - { - - # ...but they want a local copy, so provide it. - main::showcom("Local copy of ${\$self->path} from " - . "${\$self->rpath}"); - futil::install($self->rpath, $self); - 'sig'->bsig($self, $sig); - } - return $self->{status} = 'handled'; - } - - # The signatures don't match, implicitly because something - # on which we depend exists locally. Get rid of the reference - # to the Repository file; we'll build this (and anything that - # depends on it) locally. - $self->no_rfile; - } - - # Then check for currency. - if (!'sig'->current($self, $sig)) - { - - # We have to build/derive the file. - print((' ' x $level), "Rebuilding ", $self->path, - ": out of date.\n") - if $param::depends; - - # First check to see if the built file is cached. - if ($builder->cachin($self, $sig)) - { - 'sig'->bsig($self, $sig); - return $self->{status} = 'built'; - } - elsif ($builder->action($self)) - { - $builder->cachout($self, $sig); - 'sig'->bsig($self, $sig); - return $self->{status} = 'built'; - } - else - { - die ("$0: errors constructing ${\$self->path}\n") - unless $param::kflag; - return $self->{status} = 'errors'; - } - } - else - { - - # Push this out to the cache if we've been asked to (-C option). - # Don't normally do this because it slows us down. - # In a fully built system, no accesses to the cache directory - # are required to check any files. This is a win if cache is - # heavily shared. Enabling this option puts the directory in the - # loop. Useful only when you wish to recreate a cache from a build. - if ($param::cachesync) - { - $builder->cachout($self, $sig); - 'sig'->bsig($self, $sig); - } - return $self->{status} = 'handled'; - } - } - else - { # pcons - my ($tgt) = @args; # pcons - local ($file::child_queue) = {parent => $tgt}; # pcons - _pbuild($tgt); # pcons - wait_on_all_children(); # pcons - return $tgt->{status}; # pcons - } -} - -######################################## -# pcons only BEGIN -# - -sub pbuild -{ - $_[0]->{status} || &file::_pbuild; -} - -sub _pbuild -{ - my ($self) = @_; - $self->{status} = ''; # tgl - print main::DEPFILE $self->path, "\n" if param::depfile; - print((' ' x $level), $self->path, "\n") if $param::depends; - if (!exists $self->{builder}) - { - - # We don't know how to build the file. This is OK, if - # the file is present as a source file, under either the - # local tree or a Repository. - if ($self->source_exists) - { - return $self->{status} = 'handled'; - } - else - { - my ($name) = $self->path; - print("$0: don't know how to construct \"$name\"\n"); - exit(1) unless $param::kflag; - return $self->{status} = 'errors'; # xxx used to be 'unknown' - } - } - - # An associated build object exists, so we know how to build - # the file. We first compute the signature of the file, based - # on its dependendencies, then only rebuild the file if the - # signature has changed. - my ($builder) = $self->{'builder'}; - $level += 2; - - my (@deps) = (@{$self->{dep}}, @{$self->{sources}}); - my ($rdeps) = \@deps; - - if ($param::random) - { - - # If requested, build in a random order, instead of the - # order that the dependencies were listed. - my (%rdeps); - - # FIX map { $rdeps{$_,'*' x int(rand(0,10))} = $_ } @deps; - map { $rdeps{$_, '*' x int(rand(10))} = $_ } @deps; - $rdeps = [values(%rdeps)]; - } - - $self->{status} = ''; - - my $sig; - { - - # print "in ", $self->path, "\n"; - local ($file::child_queue) = {parent => $self}; - for my $dep (@$rdeps) - { - if ((pbuild $dep) eq 'errors') - { - - # Propagate dependent errors to target. - # but try to build all dependents regardless of errors. - $self->{status} = 'errors'; - } - } - wait_on_all_children(); - - } - - # If any dependents had errors, then we abort. - if ($self->{'status'} eq 'errors') - { - $level -= 2; - return 'errors'; - } - - # Compute the final signature of the file, based on - # the static dependencies (in order), dynamic dependencies, - # output path name, and (non-substituted) build script. - - # my($sig) = $self->{'sign'} = sig->collect(map(sig->signature($_->rfile), @deps), - # $builder->includes($self), - ## FIX $builder->script); - # $builder->scriptsig); - - my ($sig) = 'sig'->collect( - map('sig'->signature($_->rfile), @deps), # from cons-2.3.0 - $builder->includes($self), # from cons-2.3.0 - $builder->scriptsig - ); # from cons-2.3.0 - $self->{sign} = $sig; - - # May have gotten errors during computation of dynamic - # dependency signature, above. - $level -= 2; - return 'errors' if $self->{status} eq 'errors'; - - if (@param::rpath && $self->derived_exists) - { - - # There is no local file of this name, but there is one - # under a Repository directory. - - if ('sig'->current($self->rfile, $sig)) - { - - # The Repository copy is current (its signature matches - # our calculated signature). - if ($self->local) - { - - # ...but they want a local copy, so provide it. - main::showcom( - "Local copy of ${\$self->path} from ${\$self->rpath}"); - futil::install($self->rpath, $self); - - #'sig'->set($self, $sig); - 'sig'->bsig($self, $sig); # pcons - } - return $self->{status} = 'handled'; - } - - # The signatures don't match, implicitly because something - # on which we depend exists locally. Get rid of the reference - # to the Repository file; we'll build this (and anything that - # depends on it) locally. - $self->no_rfile; - } - - # Then check for currency. - if (!'sig'->current($self, $sig)) - { - - # We have to build/derive the file. - # First check to see if the built file is cached. - if ($builder->cachin($self, $sig)) - { - - #'sig'->set($self, $sig); - 'sig'->bsig($self, $sig); # pcons - return $self->{status} = 'built'; - - # action no longer blocks (for most actions), so this returns - # immediately, before any commands are actually run. The - # signature and return status should be overridden later in - # wait_on_child if a process was forked, but they are still set - # here in case a non-spawning action was called - } - elsif ($builder->action($self)) - { - $builder->cachout($self, $sig); - - #'sig'->set($self, $sig); - 'sig'->bsig($self, $sig); # pcons - return $self->{status} = 'built'; - } - else - { - die ("$0: errors constructing ${\$self->path}\n") - unless $param::kflag; - return $self->{status} = 'errors'; - } - } - else - { - - # Push this out to the cache if we've been asked to (-C option). - # Don't normally do this because it slows us down. - # In a fully built system, no accesses to the cache directory - # are required to check any files. This is a win if cache is - # heavily shared. Enabling this option puts the directory in the - # loop. Useful only when you wish to recreate a cache from a build. - if ($param::cachesync) - { - $builder->cachout($self, $sig); - - #'sig'->set($self, $sig); - 'sig'->bsig($self, $sig); - } - return $self->{status} = 'handled'; - } -} - -my @finished; # pcons //fix -Mstrict - -sub wait_on_max_jobs -{ - while (grep(/\d+/, keys %{$file::child_queue}) >= $param::max_jobs) - { - wait_on_child(); - } -} - -sub wait_on_all_children -{ - - while (grep(/\d+/, keys %{$file::child_queue}) != 0) - { - wait_on_child(); - } -} - -sub wait_on_child -{ - my ($queue) = $file::child_queue; - my ($parent) = $queue->{parent}; - - my $n = grep(/\d+/, keys %{$file::child_queue}); - - # printf "Waiting to build (%s): %s\n", $n, $parent->path if ref($parent) eq 'file'; - my $pid = undef; - - # first check for jobs that have already been collected from child - # targets - for my $p (@finished) - { - if ($queue->{$p}) - { - $pid = $p; - last; - } - } - - while (!$queue->{$pid}) - { - $pid = wait(); - if ($pid < 1) - { - die "wait returned invalid pid $pid"; - } - else - { - - # this job was meant for a parent, save it so that it can be - # found later - if (!$queue->{$pid}) - { - push @finished, $pid; - } - } - } - - my $child = $queue->{$pid}; - my $tgt = $queue->{$pid}->{'tgt'}; - my $com = $child->{'com'}; - $tgt->{status} = 'built'; - - #print "waited: ", $tgt->path; - #print "on: ", keys %{$queue}, "\n"; - - my ($b0, $b1) = ($? & 0xFF, $? >> 8); - - # Don't actually see 0177 on stopped process; is this necessary? - # next if $b0 == 0177; # process stopped; we can wait. - if ($b0) - { - my ($core, $sig) = ($b0 & 0200, $b0 & 0177); - my ($coremsg) = $core ? "; core dumped" : ""; - $com =~ s/\s.*//; - my ($path) = $tgt->path; - warn qq($0: *** [$path] $com terminated by signal $sig$coremsg\n); - $parent->{status} = $tgt->{status} = 'errors'; - } - if ($b1) - { - my ($path) = $tgt->path; - warn qq($0: *** [$path] Error $b1\n); # trying to be like make. - $parent->{status} = $tgt->{status} = 'errors'; - } - if ($tgt->{status} eq 'built') - { - $tgt->{builder}->cachout($tgt, $tgt->{sign}); - - #'sig'->set($tgt, $tgt->{sign}); - 'sig'->bsig($tgt, $tgt->{sign}); - } - else - { - die ("$0: errors constructing ${\$tgt->path}\n") unless $param::kflag; - } - delete $queue->{$pid}; - -} - -# -# pcons END -######################################## - -# Bind an action to a file, with the specified sources. No return value. -sub bind -{ - my ($self, $builder, @sources) = @_; - if ($self->{builder} && !$self->{builder}->compatible($builder)) - { - - # Even if not "compatible", we can still check to see if the - # derivation is identical. It should be identical if the builder is - # the same and the sources are the same. - if ("$self->{builder} @{$self->{sources}}" ne "$builder @sources") - { - $main::errors++; - my ($_foo1, $script1, $line1, $sub1) = @{$self->creator}; - my ($_foo2, $script2, $line2, $sub2) = script::caller_info; - my $err = - "\t${\$self->path}\n" - . "\tbuilt (at least) two different ways:\n" - . "\t\t$script1, line $line1: $sub1\n" - . "\t\t$script2, line $line2: $sub2\n"; - die $err; - } - return; - } - if ($param::wflag) - { - my ($script, $line, $sub); - (undef, $script, $line, $sub) = script::caller_info; - $self->{script} = '' if !defined $self->{script}; - $self->{script} .= "; " if $self->{script}; - $self->{script} .= qq($sub in "$script", line $line); - } - $self->{builder} = $builder; - push (@{$self->{sources}}, @sources); - @{$self->{dep}} = () if !defined $self->{dep}; - $self->{conscript} = $priv::self->{script}; -} - -sub is_under -{ - $_[0]->{dir}->is_under($_[1]); -} - -sub relpath -{ - my $dirpath = $_[0]->relpath($_[1]->{dir}); - if (!$dirpath) - { - return $_[1]->{entry}; - } - else - { - File::Spec->catfile($dirpath, $_[1]->{entry}); - } -} - -# Return the signature array for this file. -# This probably belongs in its own "sigarray" package, -# which would make it easier to optimize performance. -sub sigarray -{ - if ($_[0]->{sigaref}) - { - return @{$_[0]->{sigaref}}; - } - my $self = shift; - - # glob2pat based on The Perl Cookbook, p. 180. - sub glob2pat - { - my $globstr = shift; - my %patmap = ( - '*' => '.*', - '?' => '.', - '[' => '[', - ']' => ']', - '/' => "\Q$dir::SEPARATOR", # Cons-specific modification - ); - $globstr =~ s{(.)} { $patmap{$1} || "\Q$1" }ge; - return '^' . $globstr . '$'; - } - my @sigarray; - my $default; - my $builder = $self->lfile->{builder}; - if (!$builder) - { - @sigarray = @$param::sourcesig; - $default = [qw(content)]; - } - else - { - if ($builder->{env} && $builder->{env}->{SIGNATURE}) - { - @sigarray = @{$builder->{env}->{SIGNATURE}}; - } - else - { - my $class = ref $builder; - my $path = $self->path; - warn qq($0: Warning: Builder package $class did not record\n) - . qq(\tthe calling environment for '$path'.\n) - . qq(\tUnable to use any %SIGNATURE construction variable\n) - . qq(\tfor signature configuration.\n); - } - $default = [qw(build)]; - } - my $path = $self->path; - while (@sigarray) - { - my ($glob, $aref) = splice(@sigarray, 0, 2); - my $re = glob2pat($glob); - if ($path =~ /$re/) - { - $aref = [split (/\s+/, $aref)] if !ref $aref; - $self->{sigaref} = $aref; - return @$aref; - } - } - $self->{sigaref} = $default; - return @{$self->{sigaref}}; -} - -# Decide if this file's signature should be the content or build signature. -sub sigtype -{ - if ($_[0]->{sigtype}) - { - return $_[0]->{sigtype}; - } - my $self = shift; - my @sigarray = $self->sigarray; - my $sigtype; - if (grep($_ eq "build", @sigarray)) - { - $sigtype = 'bsig'; - } - elsif (grep($_ =~ /content$/, @sigarray)) - { - $sigtype = 'csig'; - } - return $self->{sigtype} = $sigtype; -} - -# Return whether this file is configured to use stored -# signature values from the .consign file. -sub stored -{ - if (!defined $_[0]->{stored}) - { - $_[0]->{stored} = grep($_ eq "stored-content", $_[0]->sigarray); - } - return $_[0]->{stored}; -} - -# Generic entry (file or directory) handling. -# This is an empty subclass for nodes that haven't -# quite decided whether they're files or dirs. -# Use file methods until someone blesses them one way or the other. -package entry; - -use vars qw( @ISA ); - -BEGIN { @ISA = qw(file) } - -# File utilities -package futil; - -# Install one file as another. -# Links them if possible (hard link), otherwise copies. -# Don't ask why, but the source is a path, the tgt is a file obj. -sub install -{ - my ($sp, $tgt) = @_; - my ($tp) = $tgt->path; - return 1 if $tp eq $sp; - return 1 if eval { link($sp, $tp) }; - unlink($tp); - if (!futil::mkdir($tgt->{dir})) - { - return undef; - } - return 1 if eval { link($sp, $tp) }; - futil::copy($sp, $tp); -} - -# Copy one file to another. Arguments are actual file names. -# Returns undef on failure. Preserves mtime and mode. -sub copy -{ - my ($sp, $tp) = @_; - my ($mode, $length, $atime, $mtime) = (stat($sp))[2, 7, 8, 9]; - - # Use Perl standard library module for file copying, which handles - # binary copies. <schwarze@isa.de> 1998-06-18 - if (!File::Copy::copy($sp, $tp)) - { - warn qq($0: can\'t install "$sp" to "$tp" ($!)\n); #' - return undef; - } - - # The file has been created, so try both the chmod and utime, - # first making sure the copy is writable (because permissions - # affect the ability to modify file times on some operating - # systems), and then changing permissions back if necessary. - my $ret = 1; - my $wmode = $mode | 0700; - if (!chmod $wmode, $tp) - { - warn qq($0: can\'t set mode $wmode on file "$tp" ($!)\n); #' - $ret = undef; - } - if (!utime $atime, $mtime, $tp) - { - warn qq($0: can\'t set modification time for file "$tp" ($!)\n); #' - $ret = undef; - } - if ($mode != $wmode && !chmod $mode, $tp) - { - warn qq($0: can\'t set mode $mode on file "$tp" ($!)\n); #' - $ret = undef; - } - return $ret; -} - -# Ensure that the specified directory exists. -# Aborts on failure. -sub mkdir -{ - return 1 if $_[0]->{'exists'}; - if (!futil::mkdir($_[0]->{dir})) - { # Recursively make parent. - return undef; - } - my ($path) = $_[0]->path; - if (!-d $path && !mkdir($path, 0777)) - { - warn qq($0: can't create directory $path ($!).\n); #' - return undef; - } - $_[0]->{'exists'} = 1; -} - -# Signature package. -package sig::hash; - -use vars qw( $called ); - -sub init -{ - my ($dir) = @_; - my ($consign) = $dir->prefix . ".consign"; - my ($dhash) = $dir->{consign} = {}; - if (-f $consign) - { - open(CONSIGN, $consign) || die ("$0: can't open $consign ($!)\n"); - while (<CONSIGN>) - { - chop; - my ($file, $sig) = split (/:/, $_); - $dhash->{$file} = $sig; - } - close(CONSIGN); - } - $dhash; -} - -# Read the hash entry for a particular file. -sub in -{ - my ($dir) = $_[0]->{dir}; - ($dir->{consign} || init($dir))->{$_[0]->{entry}}; -} - -# Write the hash entry for a particular file. -sub out -{ - my ($file, $sig) = @_; - my ($dir) = $file->{dir}; - ($dir->{consign} || init($dir))->{$file->{entry}} = $sig; - $sig::hash::dirty{$dir} = $dir; -} - -# Eliminate the hash entry for a particular file. -sub clear -{ - my ($file) = @_; - my ($dir) = $file->{dir}; - delete $dir->{consign}->{$file->{entry}} if $dir->{consign}; - $sig::hash::dirty{$dir} = $dir; -} - -# Flush hash entries. Called at end or via ^C interrupt. -sub END -{ - return if $called++; # May be called twice. - close(CONSIGN); # in case this came in via ^C. - my $dir; - for $dir (values %sig::hash::dirty) - { - my ($consign) = $dir->prefix . ".consign"; - my ($constemp) = $consign . ".$$"; - if (!open(CONSIGN, ">$constemp")) - { - die ("$0: can't create $constemp ($!)\n"); - } - my ($entry, $sig); - while (($entry, $sig) = each %{$dir->{consign}}) - { - if (!print CONSIGN "$entry:$sig\n") - { - die ("$0: error writing to $constemp ($!)\n"); - } - } - close(CONSIGN); - if (!rename($constemp, $consign)) - { - if (futil::copy($constemp, $consign)) - { - unlink($constemp); - } - else - { - die ("$0: couldn't rename or copy $constemp to $consign " - . "($!)\n"); - } - } - } -} - -# Derived file caching. -package cache; - -# Find a file in the cache. Return non-null if the file is in the cache. -sub in -{ - return undef unless $param::cache; - my ($file, $sig) = @_; - - # Add the path to the signature, to make it unique. - $sig = 'sig'->collect($sig, $file->path) unless $param::mixtargets; - my ($dir) = substr($sig, 0, 1); - my ($cp) = File::Spec->catfile($param::cache, $dir, $sig); - return -f $cp && futil::install($cp, $file); -} - -# Try to flush a file to the cache, if not already there. -# If it doesn't make it out, due to an error, then that doesn't -# really matter. -sub out -{ - return unless $param::cache; - my ($file, $sig) = @_; - - # Add the path to the signature, to make it unique. - $sig = 'sig'->collect($sig, $file->path) unless $param::mixtargets; - my ($dir) = substr($sig, 0, 1); - my ($sp) = $file->path; - my ($cp) = File::Spec->catfile($param::cache, $dir, $sig); - my ($cdir) = File::Spec->catfile($param::cache, $dir); - if (!-d $cdir) - { - mkdir($cdir, 0777) - || die ("$0: can't create cache directory $cdir ($!).\n"); - } - elsif (-f $cp) - { - - # Already cached: try to use that instead, to save space. - # This can happen if the -cs option is used on a previously - # uncached build, or if two builds occur simultaneously. - my ($lp) = ".$sig"; - unlink($lp); - return if !eval { link($cp, $lp) }; - rename($lp, $sp); - - # Unix98 says, "If the old argument and the new argument both - # [refer] to the same existing file, the rename() function - # returns successfully and performs no other action." So, if - # $lp and $sp are links (i.e., $cp and $sp are links), $lp is - # left, and we must unlink it ourselves. If the rename failed - # for any reason, it is also good form to unlink the temporary - # $lp. Otherwise $lp no longer exists and, barring some race, - # the unlink fails silently. - unlink($lp); - return; - } - - return if eval { link($sp, $cp) }; - return if !-f $sp; # if nothing to cache. - if (futil::copy($sp, "$cp.new")) - { - rename("$cp.new", $cp); - } -} - -# Generic signature handling package. -# This handles the higher-layer distinction between content and build -# signatures, relying on an underlying calculation package like -# "sig::md5"" to provide the signature values themselves. -package sig; - -use vars qw( @ISA ); - -# Select the underlying package to be used for signature calculation. -# We play a few namespace games here. Specifically, we append -# "sig::" to the beginning of the subclass we're passed. Then, -# if the package ends in "::debug", we actually subclass the -# "sig::debug" package and as a wrapper around the underlying -# (e.g.) "sig::md5" package that's doing the real calculation. -sub select -{ - my ($package, $subclass) = @_; - my $p = $package . "::" . $subclass; - my $sigpkg = $p; - if ($p =~ /(.*)::debug$/) - { - $sigpkg = $1; - $p = 'sig::debug'; - } - @ISA = ($p); - $p->init($sigpkg); -}; - -# Set or return the build signature of a file. -# This is computed elsewhere and passed in to us. -sub bsig -{ - my ($self, $file, $sig) = @_; - if (defined $sig) - { - $file->{'bsig'} = $sig; - $self->set($file); - } - elsif (!defined $file->{'bsig'}) - { - $file->{'bsig'} = ''; - } - $file->{'bsig'}; -} - -# Determine the content signature of a file. -# This also sets the .consign entry unless the file is in a -# repository; we don't write into repositories, only read from them. -sub csig -{ - my ($self, $file) = @_; - if (!$file->{'csig'}) - { - $file->{'csig'} = $self->srcsig($file->path); - $self->set($file) if !$file->is_on_rpath; - } - $_[1]->{'csig'}; -} - -# Determine the current signature of an already-existing or -# non-existant file. Unless a specific signature type (bsig -# or csig) is requested, this consults the file's signature -# array to decide whether to return content or build signature, -# and whether to use a cached value from a .consign file. -sub signature -{ - my ($self, $file, $sigtype) = @_; - $sigtype = $file->sigtype if !$sigtype; - - #open(TTY, ">/dev/tty"); - #print TTY $file->path, ": $sigtype\n"; - #close(TTY); - my ($path) = $file->path; - my ($time) = (stat($path))[9]; - if ($time) - { - if ($file->{$sigtype}) - { - return $file->{$sigtype}; - } - if ($file->is_on_rpath || $file->stored) - { - if ('sig'->fetch($file) && $file->{$sigtype}) - { - if ($file->{'sigtime'} == $time - || !$param::rep_sig_times_ok && $file->is_on_rpath) - { - return $file->{$sigtype}; - } - } - $file->{$sigtype} = undef; - } - if ($file->is_on_rpath || !File::Spec->file_name_is_absolute($path)) - { - my $sig = ''; - if ($sigtype eq 'bsig') { $sig = $self->bsig($file); } - elsif ($sigtype eq 'csig') { $sig = $self->csig($file); } - return $sig; - } - - # This file is not in a repository or under the local directory - # structure. In the canonical case, it's a utility that will be - # executed by a command. Historically, Cons has returned the - # name of the command concatenated with the modification time. - # Note that this is *not* the path ("cc" not "/bin/cc"), so it - # would lose in the unlikely event that a different copy of the - # utility was used that happened to have the same modification - # time (due to living in a different directory on the PATH, for - # example). The obvious "fix" of using the path like so, however: - # return $path . $time; - # is wrong. In a multi-machine build environment, different - # systems may have the same utility in different locations (due - # to different NFS mount points, for example), which would - # cause a lot of unnecessary builds if we used the full path. - # A better solution to strengthen this signature would be to - # also concatenate the size of the file, but that would cause - # unnecessary rebuilds when coming from .consign files that used - # the old scheme. All of which is to merely explain why we're - # leaving this as it has been, but documenting it here in case - # there's reason to change it in the future. - return $file->{entry} . $time; - } - return $file->{$sigtype} = ''; -} - -sub bsignature -{ - my ($self, $file) = @_; - my ($path) = $file->path; - my ($time) = (stat($path))[9]; - if ($time) - { - if ($file->{'bsig'}) - { - return $file->{'bsig'}; - } - if ('sig'->fetch($file, 'bsig') && $file->{'bsig'}) - { - if ($file->{'sigtime'} == $time - || !$param::rep_sig_times_ok && $file->is_on_rpath) - { - return $file->{'bsig'}; - } - } - if ($file->is_on_rpath || !File::Spec->file_name_is_absolute($path)) - { - return $self->bsig($file); - } - return $path . $time; - } - return $file->{'bsig'} = ''; -} - -# Invalidate a file's signature, also clearing its .consign entry. -sub invalidate -{ - my ($self, $file) = @_; - delete $file->{'sigtime'}; - delete $file->{'bsig'}; - delete $file->{'csig'}; - sig::hash::clear($file); -} - -# Store the signature for a file. -sub set -{ - my ($self, $file) = @_; - my $sig = (stat($file->path))[9]; - $sig .= " " . ($file->{'bsig'} || '-'); - $sig .= " " . $file->{'csig'} if $file->{'csig'}; - sig::hash::out($file, $sig); -} - -# Fetch the signature(s) for a file. -# Returns whether there was a signature to fetch. -sub fetch -{ - my ($self, $file, @kw) = @_; - @kw = ('bsig', 'csig') if !@kw; - my $sig = sig::hash::in($file) || ''; - my ($sigtime, $bsig, $csig) = split (/ /, $sig); - $file->{'sigtime'} = $sigtime; - $file->{'bsig'} = $bsig || '' if grep($_ eq 'bsig', @kw); - $file->{'csig'} = $csig || '' if grep($_ eq 'csig', @kw); - $file->{'bsig'} = '' if $file->{'bsig'} eq '-'; - return $sig ne ''; -} - -# MD5-based signature package. -package sig::md5; - -use vars qw( $md5 ); - -# Initialize MD5 signature calculation by finding an appropriate -# module and creating the proper object. -sub init -{ - my $self = shift; - my @md5_modules = qw(Digest::MD5 MD5 Digest::Perl::MD5); - - # We used to find the right module more simply, using $_ as the - # loop iterator and just doing: - # - # eval "use $_"; - # $module = $_, $last if ! $@; - # - # in the loop. Empirically, though, this doesn't pass back the - # right value in $module on some ActiveState versions. (Maybe - # it's something to do with the eval in a for loop, I dunno.) - # Work around it by using $_ to pass the value out of the loop, - # which seems to work everywhere. - my $module; - for $module (@md5_modules) - { - eval "use $module"; - $_ = $module, last if !$@; - } - $module = $_; - die "Cannot find any MD5 module from: @md5_modules" if $@; - - $md5 = new $module; -} - -# Is the provided signature equal to the signature of the current -# instantiation of the target (and does the target exist)? -sub current -{ - my ($self, $file, $sig, $sigtype) = @_; - $self->bsignature($file) eq $sig; -} - -# Return an aggregate signature for a list of signature values. -sub collect -{ - my ($self, @sigs) = @_; - - # The following sequence is faster than calling the hex interface. - $md5->reset(); - $md5->add(join ('', $param::salt, @sigs)); - unpack("H*", $md5->digest()); -} - -# Directly compute a file signature as the MD5 checksum of the -# bytes in the file. -sub srcsig -{ - my ($self, $path) = @_; - $md5->reset(); - open(FILE, $path) || return ''; - binmode(FILE); - $md5->addfile(\*FILE); - close(FILE); - unpack("H*", $md5->digest()); -} - -# Compute the signature of a command string. -# For MD5, this is just the string itself, since MD5 will condense -# the string contents into the ultimate signature. Other signature -# schemes may need to figure this out differently. -sub cmdsig -{ - my ($self, $sig) = @_; - return $sig; -} - -# Generic debug package for signature calculation. -# Because of the way we're called by sig::select() and then use -# the specified value to set up @ISA, this package is essentially a -# factory that creates packages like sig::md5::debug, etc., on the fly. -package sig::debug; - -use vars qw( @ISA $sigpkg $outfh ); - -local *FH; - -sub init -{ - my $self = shift; - $sigpkg = shift; - @ISA = ($sigpkg); - $sigpkg->init(); - my $file = $ENV{CONS_SIG_DEBUG}; - if ($file) - { - if (!open(FH, ">$file")) - { - die "Cannot open $file: $!"; - } - $outfh = \*FH; - } - else - { - $outfh = \*STDOUT; - } -} - -sub current -{ - my ($self, $file, $sig, $sigtype) = @_; - my $fsig = $self->bsignature($file); - my $sub = "${sigpkg}::current"; - my $sep = "\n" . ' ' x (length($sub) + 1 - 3); - print $outfh "$sub(|$fsig|${sep}eq |$sig|)\n"; - return $fsig eq $sig; -} - -sub collect -{ - my ($self, @sigs) = @_; - my $sig = $sigpkg->collect(@sigs); - my $sub = "${sigpkg}::collect"; - my $sep = ",\n" . ' ' x (length($sub) + 1); - my $buf = join ($sep, @sigs); - $buf = $param::salt . $sep . $buf if $param::salt; - print $outfh "$sub($buf)\n\t=> |$sig|\n"; - return $sig; -} - -sub srcsig -{ - my ($self, $path) = @_; - my $sig = $sigpkg->srcsig($path); - print $outfh "${sigpkg}::srcsig($path)\n\t=> |$sig|\n"; - return $sig; -} - -__END__; - -=head1 NAME - -Cons - A Software Construction System - -=head1 DESCRIPTION - -A guide and reference for version __VERSION____REVISION__ - -Copyright (c) 1996-2001 Free Software Foundation, Inc. - -This program is free software; you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation; either version 2 of the License, or -(at your option) any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program; see the file COPYING. If not, write to -the Free Software Foundation, Inc., 59 Temple Place - Suite 330, -Boston, MA 02111-1307, USA. - -=head1 Introduction - -B<Cons> is a system for constructing, primarily, software, but is quite -different from previous software construction systems. Cons was designed -from the ground up to deal easily with the construction of software spread -over multiple source directories. Cons makes it easy to create build scripts -that are simple, understandable and maintainable. Cons ensures that complex -software is easily and accurately reproducible. - -Cons uses a number of techniques to accomplish all of this. Construction -scripts are just Perl scripts, making them both easy to comprehend and very -flexible. Global scoping of variables is replaced with an import/export -mechanism for sharing information between scripts, significantly improving -the readability and maintainability of each script. B<Construction -environments> are introduced: these are Perl objects that capture the -information required for controlling the build process. Multiple -environments are used when different semantics are required for generating -products in the build tree. Cons implements automatic dependency analysis -and uses this to globally sequence the entire build. Variant builds are -easily produced from a single source tree. Intelligent build subsetting is -possible, when working on localized changes. Overrides can be setup to -easily override build instructions without modifying any scripts. MD5 -cryptographic B<signatures> are associated with derived files, and are used -to accurately determine whether a given file needs to be rebuilt. - -While offering all of the above, and more, Cons remains simple and easy to -use. This will, hopefully, become clear as you read the remainder of this -document. - - -=head1 Why Cons? Why not Make? - -Cons is a B<make> replacement. In the following paragraphs, we look at a few -of the undesirable characteristics of make--and typical build environments -based on make--that motivated the development of Cons. - -=head2 Build complexity - -Traditional make-based systems of any size tend to become quite complex. The -original make utility and its derivatives have contributed to this tendency -in a number of ways. Make is not good at dealing with systems that are -spread over multiple directories. Various work-arounds are used to overcome -this difficulty; the usual choice is for make to invoke itself recursively -for each sub-directory of a build. This leads to complicated code, in which -it is often unclear how a variable is set, or what effect the setting of a -variable will have on the build as a whole. The make scripting language has -gradually been extended to provide more possibilities, but these have -largely served to clutter an already overextended language. Often, builds -are done in multiple passes in order to provide appropriate products from -one directory to another directory. This represents a further increase in -build complexity. - - -=head2 Build reproducibility - -The bane of all makes has always been the correct handling of -dependencies. Most often, an attempt is made to do a reasonable job of -dependencies within a single directory, but no serious attempt is made to do -the job between directories. Even when dependencies are working correctly, -make's reliance on a simple time stamp comparison to determine whether a -file is out of date with respect to its dependents is not, in general, -adequate for determining when a file should be rederived. If an external -library, for example, is rebuilt and then ``snapped'' into place, the -timestamps on its newly created files may well be earlier than the last -local build, since it was built before it became visible. - - -=head2 Variant builds - -Make provides only limited facilities for handling variant builds. With the -proliferation of hardware platforms and the need for debuggable -vs. optimized code, the ability to easily create these variants is -essential. More importantly, if variants are created, it is important to -either be able to separate the variants or to be able to reproduce the -original or variant at will. With make it is very difficult to separate the -builds into multiple build directories, separate from the source. And if -this technique isn't used, it's also virtually impossible to guarantee at -any given time which variant is present in the tree, without resorting to a -complete rebuild. - - -=head2 Repositories - -Make provides only limited support for building software from code that -exists in a central repository directory structure. The VPATH feature of -GNU make (and some other make implementations) is intended to provide this, -but doesn't work as expected: it changes the path of target file to the -VPATH name too early in its analysis, and therefore searches for all -dependencies in the VPATH directory. To ensure correct development builds, -it is important to be able to create a file in a local build directory and -have any files in a code repository (a VPATH directory, in make terms) that -depend on the local file get rebuilt properly. This isn't possible with -VPATH, without coding a lot of complex repository knowledge directly into -the makefiles. - - -=head1 Keeping it simple - -A few of the difficulties with make have been cited above. In this and -subsequent sections, we shall introduce Cons and show how these issues are -addressed. - -=head2 Perl scripts - -Cons is Perl-based. That is, Cons scripts--F<Conscript> and F<Construct> -files, the equivalent to F<Makefile> or F<makefile>--are all written in -Perl. This provides an immediate benefit: the language for writing scripts -is a familiar one. Even if you don't happen to be a Perl programmer, it -helps to know that Perl is basically just a simple declarative language, -with a well-defined flow of control, and familiar semantics. It has -variables that behave basically the way you would expect them to, -subroutines, flow of control, and so on. There is no special syntax -introduced for Cons. The use of Perl as a scripting language simplifies -the task of expressing the appropriate solution to the often complex -requirements of a build. - - -=head2 Hello, World! - -To ground the following discussion, here's how you could build the B<Hello, -World!> C application with Cons: - - - - $env = new cons(); - Program $env 'hello', 'hello.c'; - -If you install this script in a directory, naming the script F<Construct>, -and create the F<hello.c> source file in the same directory, then you can -type C<cons hello> to build the application: - - - - % cons hello - cc -c hello.c -o hello.o - cc -o hello hello.o - - -=head2 Construction environments - -A key simplification of Cons is the idea of a B<construction environment>. A -construction environment is an B<object> characterized by a set of key/value -pairs and a set of B<methods>. In order to tell Cons how to build something, -you invoke the appropriate method via an appropriate construction -environment. Consider the following example: - - - - $env = new cons( - CC => 'gcc', - LIBS => 'libworld.a' - ); - - Program $env 'hello', 'hello.c'; - -In this case, rather than using the default construction environment, as is, -we have overridden the value of C<CC> so that the GNU C Compiler equivalent -is used, instead. Since this version of B<Hello, World!> requires a library, -F<libworld.a>, we have specified that any program linked in this environment -should be linked with that library. If the library exists already, well and -good, but if not, then we'll also have to include the statement: - - - - Library $env 'libworld', 'world.c'; - -Now if you type C<cons hello>, the library will be built before the program -is linked, and, of course, C<gcc> will be used to compile both modules: - - - - % cons hello - gcc -c hello.c -o hello.o - gcc -c world.c -o world.o - ar r libworld.a world.o - ar: creating libworld.a - ranlib libworld.a - gcc -o hello hello.o libworld.a - - -=head2 Automatic and complete dependency analysis - -With Cons, dependencies are handled automatically. Continuing the previous -example, note that when we modify F<world.c>, F<world.o> is recompiled, -F<libworld.a> recreated, and F<hello> relinked: - - - - % vi world.c - [EDIT] - % cons hello - gcc -c world.c -o world.o - ar r libworld.a world.o - ar: creating libworld.a - ranlib libworld.a - gcc -o hello hello.o libworld.a - -This is a relatively simple example: Cons ``knows'' F<world.o> depends upon -F<world.c>, because the dependency is explicitly set up by the C<Library> -method. It also knows that F<libworld.a> depends upon F<world.o> and that -F<hello> depends upon F<libworld.a>, all for similar reasons. - -Now it turns out that F<hello.c> also includes the interface definition -file, F<world.h>: - - - - % emacs world.h - [EDIT] - % cons hello - gcc -c hello.c -o hello.o - gcc -o hello hello.o libworld.a - -How does Cons know that F<hello.c> includes F<world.h>, and that F<hello.o> -must therefore be recompiled? For now, suffice it to say that when -considering whether or not F<hello.o> is up-to-date, Cons invokes a scanner -for its dependency, F<hello.c>. This scanner enumerates the files included -by F<hello.c> to come up with a list of further dependencies, beyond those -made explicit by the Cons script. This process is recursive: any files -included by included files will also be scanned. - -Isn't this expensive? The answer is--it depends. If you do a full build of a -large system, the scanning time is insignificant. If you do a rebuild of a -large system, then Cons will spend a fair amount of time thinking about it -before it decides that nothing has to be done (although not necessarily more -time than make!). The good news is that Cons makes it very easy to -intelligently subset your build, when you are working on localized changes. - - -=head2 Automatic global build sequencing - -Because Cons does full and accurate dependency analysis, and does this -globally, for the entire build, Cons is able to use this information to take -full control of the B<sequencing> of the build. This sequencing is evident -in the above examples, and is equivalent to what you would expect for make, -given a full set of dependencies. With Cons, this extends trivially to -larger, multi-directory builds. As a result, all of the complexity involved -in making sure that a build is organized correctly--including multi-pass -hierarchical builds--is eliminated. We'll discuss this further in the next -sections. - -=head1 Building large trees--still just as simple - - -=head2 A hierarchy of build scripts - -A larger build, in Cons, is organized by creating a hierarchy of B<build -scripts>. At the top of the tree is a script called F<Construct>. The rest -of the scripts, by convention, are each called F<Conscript>. These scripts -are connected together, very simply, by the C<Build>, C<Export>, and -C<Import> commands. - - -=head2 The Build command - -The C<Build> command takes a list of F<Conscript> file names, and arranges -for them to be included in the build. For example: - - Build qw( - drivers/display/Conscript - drivers/mouse/Conscript - parser/Conscript - utilities/Conscript - ); - -This is a simple two-level hierarchy of build scripts: all the subsidiary -F<Conscript> files are mentioned in the top-level F<Construct> file. Notice -that not all directories in the tree necessarily have build scripts -associated with them. - -This could also be written as a multi-level script. For example, the -F<Construct> file might contain this command: - - Build qw( - parser/Conscript - drivers/Conscript - utilities/Conscript - ); - -and the F<Conscript> file in the F<drivers> directory might contain this: - - Build qw( - display/Conscript - mouse/Conscript - ); - -Experience has shown that the former model is a little easier to understand, -since the whole construction tree is laid out in front of you, at the -top-level. Hybrid schemes are also possible. A separately maintained -component that needs to be incorporated into a build tree, for example, -might hook into the build tree in one place, but define its own construction -hierarchy. - -By default, Cons does not change its working directory to the directory -containing a subsidiary F<Conscript> file it is including. This behavior -can be enabled for a build by specifying, in the top-level F<Construct> -file: - - Conscript_chdir 1; - -When enabled, Cons will change to the subsidiary F<Conscript> file's -containing directory while reading in that file, and then change back -to the top-level directory once the file has been processed. - -It is expected that this behavior will become the default in some future -version of Cons. To prepare for this transition, builds that expect -Cons to remain at the top of the build while it reads in a subsidiary -F<Conscript> file should explicitly disable this feature as follows: - - Conscript_chdir 0; - - -=head2 Relative, top-relative, and absolute file names - -You may have noticed that the file names specified to the Build command are -relative to the location of the script it is invoked from. This is generally -true for other filename arguments to other commands, too, although we might -as well mention here that if you begin a file name with a hash mark, ``#'', -then that file is interpreted relative to the top-level directory (where the -F<Construct> file resides). And, not surprisingly, if you begin it with ``/'', -then it is considered to be an absolute pathname. This is true even on -systems which use a back slash rather than a forward slash to name absolute -paths. - -(There is another file prefix, ``!'', that is interpreted specially by -Cons. See discussion of the C<Link> command, below, for details.) - - -=head2 Using modules in build scripts - -You may pull modules into each F<Conscript> file using the normal Perl -C<use> or C<require> statements: - - use English; - require My::Module; - -Each C<use> or C<require> only affects the one F<Conscript> file in which -it appears. To use a module in multiple F<Conscript> files, you must -put a C<use> or C<require> statement in each one that needs the module. - - -=head2 Scope of variables - -The top-level F<Construct> file and all F<Conscript> files begin life in -a common, separate Perl package. B<Cons> controls the symbol table for -the package so that, the symbol table for each script is empty, except -for the F<Construct> file, which gets some of the command line arguments. -All of the variables that are set or used, therefore, are set by the -script itself--not by some external script. - -Variables can be explicitly B<imported> by a script from its parent -script. To import a variable, it must have been B<exported> by the parent -and initialized (otherwise an error will occur). - - -=head2 The Export command - -The C<Export> command is used as in the following example: - - $env = new cons(); - $INCLUDE = "#export/include"; - $LIB = "#export/lib"; - Export qw( env INCLUDE LIB ); - Build qw( util/Conscript ); - -The values of the simple variables mentioned in the C<Export> list will be -squirreled away by any subsequent C<Build> commands. The C<Export> command -will only export Perl B<scalar> variables, that is, variables whose name -begins with C<$>. Other variables, objects, etc. can be exported by -reference--but all scripts will refer to the same object, and this object -should be considered to be read-only by the subsidiary scripts and by the -original exporting script. It's acceptable, however, to assign a new value -to the exported scalar variable--that won't change the underlying variable -referenced. This sequence, for example, is OK: - - $env = new cons(); - Export qw( env INCLUDE LIB ); - Build qw( util/Conscript ); - $env = new cons(CFLAGS => '-O'); - Build qw( other/Conscript ); - -It doesn't matter whether the variable is set before or after the C<Export> -command. The important thing is the value of the variable at the time the -C<Build> command is executed. This is what gets squirreled away. Any -subsequent C<Export> commands, by the way, invalidate the first: you must -mention all the variables you wish to export on each C<Export> command. - - -=head2 The Import command - -Variables exported by the C<Export> command can be imported into subsidiary -scripts by the C<Import> command. The subsidiary script always imports -variables directly from the superior script. Consider this example: - - Import qw( env INCLUDE ); - -This is only legal if the parent script exported both C<$env> and -C<$INCLUDE>. It also must have given each of these variables values. It is -OK for the subsidiary script to only import a subset of the exported -variables (in this example, C<$LIB>, which was exported by the previous -example, is not imported). - -All the imported variables are automatically re-exported, so the sequence: - - Import qw ( env INCLUDE ); - Build qw ( beneath-me/Conscript ); - -will supply both C<$env> and C<$INCLUDE> to the subsidiary file. If only -C<$env> is to be exported, then the following will suffice: - - Import qw ( env INCLUDE ); - Export qw ( env ); - Build qw ( beneath-me/Conscript ); - -Needless to say, the variables may be modified locally before invoking -C<Build> on the subsidiary script. - - -=head2 Build script evaluation order - -The only constraint on the ordering of build scripts is that superior -scripts are evaluated before their inferior scripts. The top-level -F<Construct> file, for instance, is evaluated first, followed by any -inferior scripts. This is all you really need to know about the evaluation -order, since order is generally irrelevant. Consider the following C<Build> -command: - - Build qw( - drivers/display/Conscript - drivers/mouse/Conscript - parser/Conscript - utilities/Conscript - ); - -We've chosen to put the script names in alphabetical order, simply because -that's the most convenient for maintenance purposes. Changing the order will -make no difference to the build. - - -=head1 A Model for sharing files - - -=head2 Some simple conventions - -In any complex software system, a method for sharing build products needs to -be established. We propose a simple set of conventions which are trivial to -implement with Cons, but very effective. - -The basic rule is to require that all build products which need to be shared -between directories are shared via an intermediate directory. We have -typically called this F<export>, and, in a C environment, provided -conventional sub-directories of this directory, such as F<include>, F<lib>, -F<bin>, etc. - -These directories are defined by the top-level F<Construct> file. A simple -F<Construct> file for a B<Hello, World!> application, organized using -multiple directories, might look like this: - - # Construct file for Hello, World! - - # Where to put all our shared products. - $EXPORT = '#export'; - - Export qw( CONS INCLUDE LIB BIN ); - - # Standard directories for sharing products. - $INCLUDE = "$EXPORT/include"; - $LIB = "$EXPORT/lib"; - $BIN = "$EXPORT/bin"; - - # A standard construction environment. - $CONS = new cons ( - CPPPATH => $INCLUDE, # Include path for C Compilations - LIBPATH => $LIB, # Library path for linking programs - LIBS => '-lworld', # List of standard libraries - ); - - Build qw( - hello/Conscript - world/Conscript - ); - -The F<world> directory's F<Conscript> file looks like this: - - # Conscript file for directory world - Import qw( CONS INCLUDE LIB ); - - # Install the products of this directory - Install $CONS $LIB, 'libworld.a'; - Install $CONS $INCLUDE, 'world.h'; - - # Internal products - Library $CONS 'libworld.a', 'world.c'; - -and the F<hello> directory's F<Conscript> file looks like this: - - # Conscript file for directory hello - Import qw( CONS BIN ); - - # Exported products - Install $CONS $BIN, 'hello'; - - # Internal products - Program $CONS 'hello', 'hello.c'; - -To construct a B<Hello, World!> program with this directory structure, go to -the top-level directory, and invoke C<cons> with the appropriate -arguments. In the following example, we tell Cons to build the directory -F<export>. To build a directory, Cons recursively builds all known products -within that directory (only if they need rebuilding, of course). If any of -those products depend upon other products in other directories, then those -will be built, too. - - % cons export - Install world/world.h as export/include/world.h - cc -Iexport/include -c hello/hello.c -o hello/hello.o - cc -Iexport/include -c world/world.c -o world/world.o - ar r world/libworld.a world/world.o - ar: creating world/libworld.a - ranlib world/libworld.a - Install world/libworld.a as export/lib/libworld.a - cc -o hello/hello hello/hello.o -Lexport/lib -lworld - Install hello/hello as export/bin/hello - - -=head2 Clean, understandable, location-independent scripts - -You'll note that the two F<Conscript> files are very clean and -to-the-point. They simply specify products of the directory and how to build -those products. The build instructions are minimal: they specify which -construction environment to use, the name of the product, and the name of -the inputs. Note also that the scripts are location-independent: if you wish -to reorganize your source tree, you are free to do so: you only have to -change the F<Construct> file (in this example), to specify the new locations -of the F<Conscript> files. The use of an export tree makes this goal easy. - -Note, too, how Cons takes care of little details for you. All the F<export> -directories, for example, were made automatically. And the installed files -were really hard-linked into the respective export directories, to save -space and time. This attention to detail saves considerable work, and makes -it even easier to produce simple, maintainable scripts. - - -=head1 Separating source and build trees - -It's often desirable to keep any derived files from the build completely -separate from the source files. This makes it much easier to keep track of -just what is a source file, and also makes it simpler to handle B<variant> -builds, especially if you want the variant builds to co-exist. - - -=head2 Separating build and source directories using the Link command - -Cons provides a simple mechanism that handles all of these requirements. The -C<Link> command is invoked as in this example: - - Link 'build' => 'src'; - -The specified directories are ``linked'' to the specified source -directory. Let's suppose that you setup a source directory, F<src>, with the -sub-directories F<world> and F<hello> below it, as in the previous -example. You could then substitute for the original build lines the -following: - - Build qw( - build/world/Conscript - build/hello/Conscript - ); - -Notice that you treat the F<Conscript> file as if it existed in the build -directory. Now if you type the same command as before, you will get the -following results: - - % cons export - Install build/world/world.h as export/include/world.h - cc -Iexport/include -c build/hello/hello.c -o build/hello/hello.o - cc -Iexport/include -c build/world/world.c -o build/world/world.o - ar r build/world/libworld.a build/world/world.o - ar: creating build/world/libworld.a - ranlib build/world/libworld.a - Install build/world/libworld.a as export/lib/libworld.a - cc -o build/hello/hello build/hello/hello.o -Lexport/lib -lworld - Install build/hello/hello as export/bin/hello - -Again, Cons has taken care of the details for you. In particular, you will -notice that all the builds are done using source files and object files from -the build directory. For example, F<build/world/world.o> is compiled from -F<build/world/world.c>, and F<export/include/world.h> is installed from -F<build/world/world.h>. This is accomplished on most systems by the simple -expedient of ``hard'' linking the required files from each source directory -into the appropriate build directory. - -The links are maintained correctly by Cons, no matter what you do to the -source directory. If you modify a source file, your editor may do this ``in -place'' or it may rename it first and create a new file. In the latter case, -any hard link will be lost. Cons will detect this condition the next time -the source file is needed, and will relink it appropriately. - -You'll also notice, by the way, that B<no> changes were required to the -underlying F<Conscript> files. And we can go further, as we shall see in the -next section. - -=head2 Explicit references to the source directory - -When using the C<Link> command on some operating systems or with some -tool chains, it's sometimes useful to have a command actually use -the path name to the source directory, not the build directory. For -example, on systems that must copy, not "hard link," the F<src/> and -F<build/> copies of C<Linked> files, using the F<src/> path of a file -name might make an editor aware that a syntax error must be fixed in the -source directory, not the build directory. - -You can tell Cons that you want to use the "source path" for a file by -preceding the file name with a ``!'' (exclamation point). For example, -if we add a ``!'' to the beginning of a source file: - - Program $env "foo", "!foo.c"; # Notice initial ! on foo.c - -Cons will compile the target as follows: - - cc -c src/foo.c -o build/foo.o - cc -o build/foo build/foo.o - -Notice that Cons has compiled the program from the the F<src/foo.c> -source file. Without the initial ``!'', Cons would have compiled the -program using the F<build/foo.c> path name. - - - -=head1 Variant builds - - -=head2 Hello, World! for baNaNa and peAcH OS's - -Variant builds require just another simple extension. Let's take as an -example a requirement to allow builds for both the baNaNa and peAcH -operating systems. In this case, we are using a distributed file system, -such as NFS to access the particular system, and only one or the other of -the systems has to be compiled for any given invocation of C<cons>. Here's -one way we could set up the F<Construct> file for our B<Hello, World!> -application: - - # Construct file for Hello, World! - - die qq(OS must be specified) unless $OS = $ARG{OS}; - die qq(OS must be "peach" or "banana") - if $OS ne "peach" && $OS ne "banana"; - - # Where to put all our shared products. - $EXPORT = "#export/$OS"; - - Export qw( CONS INCLUDE LIB BIN ); - - # Standard directories for sharing products. - $INCLUDE = "$EXPORT/include"; - $LIB = "$EXPORT/lib"; - $BIN = "$EXPORT/bin"; - - # A standard construction environment. - $CONS = new cons ( - CPPPATH => $INCLUDE, # Include path for C Compilations - LIBPATH => $LIB, # Library path for linking programs - LIBS => '-lworld', # List of standard libraries - ); - - # $BUILD is where we will derive everything. - $BUILD = "#build/$OS"; - - # Tell cons where the source files for $BUILD are. - Link $BUILD => 'src'; - - Build ( - "$BUILD/hello/Conscript", - "$BUILD/world/Conscript", - ); - -Now if we login to a peAcH system, we can build our B<Hello, World!> -application for that platform: - - % cons export OS=peach - Install build/peach/world/world.h as export/peach/include/world.h - cc -Iexport/peach/include -c build/peach/hello/hello.c -o build/peach/hello/hello.o - cc -Iexport/peach/include -c build/peach/world/world.c -o build/peach/world/world.o - ar r build/peach/world/libworld.a build/peach/world/world.o - ar: creating build/peach/world/libworld.a - ranlib build/peach/world/libworld.a - Install build/peach/world/libworld.a as export/peach/lib/libworld.a - cc -o build/peach/hello/hello build/peach/hello/hello.o -Lexport/peach/lib -lworld - Install build/peach/hello/hello as export/peach/bin/hello - - -=head2 Variations on a theme - -Other variations of this model are possible. For example, you might decide -that you want to separate out your include files into platform dependent and -platform independent files. In this case, you'd have to define an -alternative to C<$INCLUDE> for platform-dependent files. Most F<Conscript> -files, generating purely platform-independent include files, would not have -to change. - -You might also want to be able to compile your whole system with debugging -or profiling, for example, enabled. You could do this with appropriate -command line options, such as C<DEBUG=on>. This would then be translated -into the appropriate platform-specific requirements to enable debugging -(this might include turning off optimization, for example). You could -optionally vary the name space for these different types of systems, but, as -we'll see in the next section, it's not B<essential> to do this, since Cons -is pretty smart about rebuilding things when you change options. - - -=head1 Signatures - -Cons uses file B<signatures> to decide if a derived file is out-of-date -and needs rebuilding. In essence, if the contents of a file change, -or the manner in which the file is built changes, the file's signature -changes as well. This allows Cons to decide with certainty when a file -needs rebuilding, because Cons can detect, quickly and reliably, whether -any of its dependency files have been changed. - - -=head2 MD5 content and build signatures - -Cons uses the B<MD5> (B<Message Digest 5>) algorithm to compute file -signatures. The MD5 algorithm computes a strong cryptographic checksum -for any given input string. Cons can, based on configuration, use two -different MD5 signatures for a given file: - -The B<content signature> of a file is an MD5 checksum of the file's -contents. Consequently, when the contents of a file change, its content -signature changes as well. - -The B<build signature> of a file is a combined MD5 checksum of: - -=over 4 - -the signatures of all the input files used to build the file - -the signatures of all dependency files discovered by source scanners -(for example, C<.h> files) - -the signatures of all dependency files specified explicitly via the -C<Depends> method) - -the command-line string used to build the file - -=back - -The build signature is, in effect, a digest of all the dependency -information for the specified file. Consequently, a file's build -signature changes whenever any part of its dependency information -changes: a new file is added, the contents of a file on which it depends -change, there's a change to the command line used to build the file (or -any of its dependency files), etc. - -For example, in the previous section, the build signature of the -F<world.o> file will include: - -=over 4 - -the signature of the F<world.c> file - -the signatures of any header files that Cons detects are included, -directly or indirectly, by F<world.c> - -the text of the actual command line was used to generate F<world.o> - -=back - -Similarly, the build signature of the F<libworld.a> file will include -all the signatures of its constituents (and hence, transitively, the -signatures of B<their> constituents), as well as the command line that -created the file. - -Note that there is no need for a derived file to depend upon any -particular F<Construct> or F<Conscript> file. If changes to these files -affect a file, then this will be automatically reflected in its build -signature, since relevant parts of the command line are included in the -signature. Unrelated F<Construct> or F<Conscript> changes will have no -effect. - - -=head2 Storing signatures in .consign files - -Before Cons exits, it stores the calculated signatures for all of the -files it built or examined in F<.consign> files, one per directory. -Cons uses this stored information on later invocations to decide if -derived files need to be rebuilt. - -After the previous example was compiled, the F<.consign> file in the -F<build/peach/world> directory looked like this: - - world.h:985533370 - d181712f2fdc07c1f05d97b16bfad904 - world.o:985533372 2a0f71e0766927c0532977b0d2158981 - world.c:985533370 - c712f77189307907f4189b5a7ab62ff3 - libworld.a:985533374 69e568fc5241d7d25be86d581e1fb6aa - -After the file name and colon, the first number is a timestamp of the -file's modification time (on UNIX systems, this is typically the number -of seconds since January 1st, 1970). The second value is the build -signature of the file (or ``-'' in the case of files with no build -signature--that is, source files). The third value, if any, is the -content signature of the file. - - -=head2 Using build signatures to decide when to rebuild files - -When Cons is deciding whether to build or rebuild a derived file, it -first computes the file's current build signature. If the file doesn't -exist, it must obviously be built. - -If, however, the file already exists, Cons next compares the -modification timestamp of the file against the timestamp value in -the F<.consign> file. If the timestamps match, Cons compares the -newly-computed build signature against the build signature in the -F<.consign> file. If the timestamps do not match or the build -signatures do not match, the derived file is rebuilt. - -After the file is built or rebuilt, Cons arranges to store the -newly-computed build signature in the F<.consign> file when it exits. - - -=head2 Signature example - -The use of these signatures is an extremely simple, efficient, and -effective method of improving--dramatically--the reproducibility of a -system. - -We'll demonstrate this with a simple example: - - # Simple "Hello, World!" Construct file - $CFLAGS = '-g' if $ARG{DEBUG} eq 'on'; - $CONS = new cons(CFLAGS => $CFLAGS); - Program $CONS 'hello', 'hello.c'; - -Notice how Cons recompiles at the appropriate times: - - % cons hello - cc -c hello.c -o hello.o - cc -o hello hello.o - % cons hello - cons: "hello" is up-to-date. - % cons DEBUG=on hello - cc -g -c hello.c -o hello.o - cc -o hello hello.o - % cons DEBUG=on hello - cons: "hello" is up-to-date. - % cons hello - cc -c hello.c -o hello.o - cc -o hello hello.o - - -=head2 Source-file signature configuration - -Cons provides a C<SourceSignature> method that allows you to configure -how the signature should be calculated for any source file when its -signature is being used to decide if a dependent file is up-to-date. -The arguments to the C<SourceSignature> method consist of one or more -pairs of strings: - - SourceSignature 'auto/*.c' => 'content', - '*' => 'stored-content'; - -The first string in each pair is a pattern to match against derived file -path names. The pattern is a file-globbing pattern, not a Perl regular -expression; the pattern <*.l> will match all Lex source files. The C<*> -wildcard will match across directory separators; the pattern C<foo/*.c> -would match all C source files in any subdirectory underneath the C<foo> -subdirectory. - -The second string in each pair contains one of the following keywords to -specify how signatures should be calculated for source files that match -the pattern. The available keywords are: - -=over 4 - -=item content - -Use the content signature of the source file when calculating signatures -of files that depend on it. This guarantees correct calculation of the -file's signature for all builds, by telling Cons to read the contents of -a source file to calculate its content signature each time it is run. - -=item stored-content - -Use the source file's content signature as stored in the F<.consign> -file, provided the file's timestamp matches the cached timestamp value -in the F<.consign> file. This optimizes performance, with the slight -risk of an incorrect build if a source file's contents have been changed -so quickly after its previous update that the timestamp still matches -the stored timestamp in the F<.consign> file even though the contents -have changed. - -=back - -The Cons default behavior of always calculating a source file's -signature from the file's contents is equivalent to specifying: - - SourceSignature '*' => 'content'; - -The C<*> will match all source files. The C<content> keyword -specifies that Cons will read the contents of a source file to calculate -its signature each time it is run. - -A useful global performance optimization is: - - SourceSignature '*' => 'stored-content'; - -This specifies that Cons will use pre-computed content signatures -from F<.consign> files, when available, rather than re-calculating a -signature from the the source file's contents each time Cons is run. In -practice, this is safe for most build situations, and only a problem -when source files are changed automatically (by scripts, for example). -The Cons default, however, errs on the side of guaranteeing a correct -build in all situations. - -Cons tries to match source file path names against the patterns in the -order they are specified in the C<SourceSignature> arguments: - - SourceSignature '/usr/repository/objects/*' => 'stored-content', - '/usr/repository/*' => 'content', - '*.y' => 'content', - '*' => 'stored-content'; - -In this example, all source files under the F</usr/repository/objects> -directory will use F<.consign> file content signatures, source files -anywhere else underneath F</usr/repository> will not use F<.consign> -signature values, all Yacc source files (C<*.y>) anywhere else will not -use F<.consign> signature values, and any other source file will use -F<.consign> signature values. - - -=head2 Derived-file signature configuration - -Cons provides a C<SIGNATURE> construction variable that allows you to -configure how signatures are calculated for any derived file when its -signature is being used to decide if a dependent file is up-to-date. -The value of the C<SIGNATURE> construction variable is a Perl array -reference that holds one or more pairs of strings, like the arguments to -the C<SourceSignature> method. - -The first string in each pair is a pattern to match against derived file -path names. The pattern is a file-globbing pattern, not a Perl regular -expression; the pattern `*.obj' will match all (Win32) object files. -The C<*> wildcard will match across directory separators; the pattern -`foo/*.a' would match all (UNIX) library archives in any subdirectory -underneath the foo subdirectory. - -The second string in each pair contains one of the following keywords -to specify how signatures should be calculated for derived files that -match the pattern. The available keywords are the same as for the -C<SourceSignature> method, with an additional keyword: - -=over 4 - -=item build - -Use the build signature of the derived file when calculating signatures -of files that depend on it. This guarantees correct builds by forcing -Cons to rebuild any and all files that depend on the derived file. - -=item content - -Use the content signature of the derived file when calculating signatures -of files that depend on it. This guarantees correct calculation of the -file's signature for all builds, by telling Cons to read the contents of -a derived file to calculate its content signature each time it is run. - -=item stored-content - -Use the derived file's content signature as stored in the F<.consign> -file, provided the file's timestamp matches the cached timestamp value -in the F<.consign> file. This optimizes performance, with the slight -risk of an incorrect build if a derived file's contents have been -changed so quickly after a Cons build that the file's timestamp still -matches the stored timestamp in the F<.consign> file. - -=back - -The Cons default behavior (as previously described) for using -derived-file signatures is equivalent to: - - $env = new cons(SIGNATURE => ['*' => 'build']); - -The C<*> will match all derived files. The C<build> keyword specifies -that all derived files' build signatures will be used when calculating -whether a dependent file is up-to-date. - -A useful alternative default C<SIGNATURE> configuration for many sites: - - $env = new cons(SIGNATURE => ['*' => 'content']); - -In this configuration, derived files have their signatures calculated -from the file contents. This adds slightly to Cons' workload, but has -the useful effect of "stopping" further rebuilds if a derived file is -rebuilt to exactly the same file contents as before, which usually -outweighs the additional computation Cons must perform. - -For example, changing a comment in a C file and recompiling should -generate the exact same object file (assuming the compiler doesn't -insert a timestamp in the object file's header). In that case, -specifying C<content> or C<stored-content> for the signature calculation -will cause Cons to recognize that the object file did not actually -change as a result of being rebuilt, and libraries or programs that -include the object file will not be rebuilt. When C<build> is -specified, however, Cons will only "know" that the object file was -rebuilt, and proceed to rebuild any additional files that include the -object file. - -Note that Cons tries to match derived file path names against the -patterns in the order they are specified in the C<SIGNATURE> array -reference: - - $env = new cons(SIGNATURE => ['foo/*.o' => 'build', - '*.o' => 'content', - '*.a' => 'stored-content', - '*' => 'content']); - -In this example, all object files underneath the F<foo> subdirectory -will use build signatures, all other object files (including object -files underneath other subdirectories!) will use F<.consign> file -content signatures, libraries will use F<.consign> file build -signatures, and all other derived files will use content signatures. - - -=head2 Debugging signature calculation - -Cons provides a C<-S> option that can be used to specify what internal -Perl package Cons should use to calculate signatures. The default Cons -behavior is equivalent to specifying C<-S md5> on the command line. - -The only other package (currently) available is an C<md5::debug> -package that prints out detailed information about the MD5 signature -calculations performed by Cons: - - % cons -S md5::debug hello - sig::md5::srcsig(hello.c) - => |52d891204c62fe93ecb95281e1571938| - sig::md5::collect(52d891204c62fe93ecb95281e1571938) - => |fb0660af4002c40461a2f01fbb5ffd03| - sig::md5::collect(52d891204c62fe93ecb95281e1571938, - fb0660af4002c40461a2f01fbb5ffd03, - cc -c %< -o %>) - => |f7128da6c3fe3c377dc22ade70647b39| - sig::md5::current(|| - eq |f7128da6c3fe3c377dc22ade70647b39|) - cc -c hello.c -o hello.o - sig::md5::collect() - => |d41d8cd98f00b204e9800998ecf8427e| - sig::md5::collect(f7128da6c3fe3c377dc22ade70647b39, - d41d8cd98f00b204e9800998ecf8427e, - cc -o %> %< ) - => |a0bdce7fd09e0350e7efbbdb043a00b0| - sig::md5::current(|| - eq |a0bdce7fd09e0350e7efbbdb043a00b0|) - cc -o hello, hello.o - - -=head1 Code Repositories - -Many software development organizations will have one or more central -repository directory trees containing the current source code for one or -more projects, as well as the derived object files, libraries, and -executables. In order to reduce unnecessary recompilation, it is useful to -use files from the repository to build development software--assuming, of -course, that no newer dependency file exists in the local build tree. - - -=head2 Repository - -Cons provides a mechanism to specify a list of code repositories that will -be searched, in-order, for source files and derived files not found in the -local build directory tree. - -The following lines in a F<Construct> file will instruct Cons to look first -under the F</usr/experiment/repository> directory and then under the -F</usr/product/repository> directory: - - Repository qw ( - /usr/experiment/repository - /usr/product/repository - ); - -The repository directories specified may contain source files, derived files -(objects, libraries and executables), or both. If there is no local file -(source or derived) under the directory in which Cons is executed, then the -first copy of a same-named file found under a repository directory will be -used to build any local derived files. - -Cons maintains one global list of repositories directories. Cons will -eliminate the current directory, and any non-existent directories, from the -list. - - -=head2 Finding the Construct file in a Repository - -Cons will also search for F<Construct> and F<Conscript> files in the -repository tree or trees. This leads to a chicken-and-egg situation, -though: how do you look in a repository tree for a F<Construct> file if the -F<Construct> file tells you where the repository is? To get around this, -repositories may be specified via C<-R> options on the command line: - - % cons -R /usr/experiment/repository -R /usr/product/repository . - -Any repository directories specified in the F<Construct> or F<Conscript> -files will be appended to the repository directories specified by -command-line C<-R> options. - -=head2 Repository source files - -If the source code (include the F<Conscript> file) for the library version -of the I<Hello, World!> C application is in a repository (with no derived -files), Cons will use the repository source files to create the local object -files and executable file: - - % cons -R /usr/src_only/repository hello - gcc -c /usr/src_only/repository/hello.c -o hello.o - gcc -c /usr/src_only/repository/world.c -o world.o - ar r libworld.a world.o - ar: creating libworld.a - ranlib libworld.a - gcc -o hello hello.o libworld.a - -Creating a local source file will cause Cons to rebuild the appropriate -derived file or files: - - % pico world.c - [EDIT] - % cons -R /usr/src_only/repository hello - gcc -c world.c -o world.o - ar r libworld.a world.o - ar: creating libworld.a - ranlib libworld.a - gcc -o hello hello.o libworld.a - -And removing the local source file will cause Cons to revert back to -building the derived files from the repository source: - - % rm world.c - % cons -R /usr/src_only/repository hello - gcc -c /usr/src_only/repository/world.c -o world.o - ar r libworld.a world.o - ar: creating libworld.a - ranlib libworld.a - gcc -o hello hello.o libworld.a - - -=head2 Repository derived files - -If a repository tree contains derived files (usually object files, -libraries, or executables), Cons will perform its normal signature -calculation to decide whether the repository file is up-to-date or a derived -file must be built locally. This means that, in order to ensure correct -signature calculation, a repository tree must also contain the F<.consign> -files that were created by Cons when generating the derived files. - -This would usually be accomplished by building the software in the -repository (or, alternatively, in a build directory, and then copying the -result to the repository): - - % cd /usr/all/repository - % cons hello - gcc -c hello.c -o hello.o - gcc -c world.c -o world.o - ar r libworld.a world.o - ar: creating libworld.a - ranlib libworld.a - gcc -o hello hello.o libworld.a - -(This is safe even if the F<Construct> file lists the F</usr/all/repository> -directory in a C<Repository> command because Cons will remove the current -directory from the repository list.) - -Now if we want to build a copy of the application with our own F<hello.c> -file, we only need to create the one necessary source file, and use the -C<-R> option to have Cons use other files from the repository: - - % mkdir $HOME/build1 - % cd $HOME/build1 - % ed hello.c - [EDIT] - % cons -R /usr/all/repository hello - gcc -c hello.c -o hello.o - gcc -o hello hello.o /usr/all/repository/libworld.a - -Notice that Cons has not bothered to recreate a local F<libworld.a> library -(or recompile the F<world.o> module), but instead uses the already-compiled -version from the repository. - -Because the MD5 signatures that Cons puts in the F<.consign> file contain -timestamps for the derived files, the signature timestamps must match the -file timestamps for a signature to be considered valid. - -Some software systems may alter the timestamps on repository files (by -copying them, e.g.), in which case Cons will, by default, assume the -repository signatures are invalid and rebuild files unnecessarily. This -behavior may be altered by specifying: - - Repository_Sig_Times_OK 0; - -This tells Cons to ignore timestamps when deciding whether a signature is -valid. (Note that avoiding this sanity check means there must be proper -control over the repository tree to ensure that the derived files cannot be -modified without updating the F<.consign> signature.) - - -=head2 Local copies of files - -If the repository tree contains the complete results of a build, and we try -to build from the repository without any files in our local tree, something -moderately surprising happens: - - % mkdir $HOME/build2 - % cd $HOME/build2 - % cons -R /usr/all/repository hello - cons: "hello" is up-to-date. - -Why does Cons say that the F<hello> program is up-to-date when there is no -F<hello> program in the local build directory? Because the repository (not -the local directory) contains the up-to-date F<hello> program, and Cons -correctly determines that nothing needs to be done to rebuild this -up-to-date copy of the file. - -There are, however, many times in which it is appropriate to ensure that a -local copy of a file always exists. A packaging or testing script, for -example, may assume that certain generated files exist locally. Instead of -making these subsidiary scripts aware of the repository directory, the -C<Local> command may be added to a F<Construct> or F<Conscript> file to -specify that a certain file or files must appear in the local build -directory: - - Local qw( - hello - ); - -Then, if we re-run the same command, Cons will make a local copy of the -program from the repository copy (telling you that it is doing so): - - % cons -R /usr/all/repository hello - Local copy of hello from /usr/all/repository/hello - cons: "hello" is up-to-date. - -Notice that, because the act of making the local copy is not considered a -"build" of the F<hello> file, Cons still reports that it is up-to-date. - -Creating local copies is most useful for files that are being installed into -an intermediate directory (for sharing with other directories) via the -C<Install> command. Accompanying the C<Install> command for a file with a -companion C<Local> command is so common that Cons provides a -C<Install_Local> command as a convenient way to do both: - - Install_Local $env, '#export', 'hello'; - -is exactly equivalent to: - - Install $env '#export', 'hello'; - Local '#export/hello'; - -Both the C<Local> and C<Install_Local> commands update the local F<.consign> -file with the appropriate file signatures, so that future builds are -performed correctly. - - -=head2 Repository dependency analysis - -Due to its built-in scanning, Cons will search the specified repository -trees for included F<.h> files. Unless the compiler also knows about the -repository trees, though, it will be unable to find F<.h> files that only -exist in a repository. If, for example, the F<hello.c> file includes the -F<hello.h> file in its current directory: - - % cons -R /usr/all/repository hello - gcc -c /usr/all/repository/hello.c -o hello.o - /usr/all/repository/hello.c:1: hello.h: No such file or directory - -Solving this problem forces some requirements onto the way construction -environments are defined and onto the way the C C<#include> preprocessor -directive is used to include files. - -In order to inform the compiler about the repository trees, Cons will add -appropriate C<-I> flags to the compilation commands. This means that the -C<CPPPATH> variable in the construction environment must explicitly specify -all subdirectories which are to be searched for included files, including the -current directory. Consequently, we can fix the above example by changing -the environment creation in the F<Construct> file as follows: - - $env = new cons( - CC => 'gcc', - CPPPATH => '.', - LIBS => 'libworld.a', - ); - -Due to the definition of the C<CPPPATH> variable, this yields, when we -re-execute the command: - - % cons -R /usr/all/repository hello - gcc -c -I. -I/usr/all/repository /usr/all/repository/hello.c -o hello.o - gcc -o hello hello.o /usr/all/repository/libworld.a - -The order of the C<-I> flags replicates, for the C preprocessor, the same -repository-directory search path that Cons uses for its own dependency -analysis. If there are multiple repositories and multiple C<CPPPATH> -directories, Cons will append the repository directories to the beginning of -each C<CPPPATH> directory, rapidly multiplying the number of C<-I> flags. -As an extreme example, a F<Construct> file containing: - - Repository qw( - /u1 - /u2 - ); - - $env = new cons( - CPPPATH => 'a:b:c', - ); - -Would yield a compilation command of: - - cc -Ia -I/u1/a -I/u2/a -Ib -I/u1/b -I/u2/b -Ic -I/u1/c -I/u2/c -c hello.c -o hello.o - -In order to shorten the command lines as much as possible, Cons will -remove C<-I> flags for any directories, locally or in the repositories, -which do not actually exist. (Note that the C<-I> flags are not included -in the MD5 signature calculation for the target file, so the target will -not be recompiled if the compilation command changes due to a directory -coming into existence.) - -Because Cons relies on the compiler's C<-I> flags to communicate the -order in which repository directories must be searched, Cons' handling -of repository directories is fundamentally incompatible with using -double-quotes on the C<#include> directives in any C source code that -you plan to modify: - - #include "file.h" /* DON'T USE DOUBLE-QUOTES LIKE THIS */ - -This is because most C preprocessors, when faced with such a directive, will -always first search the directory containing the source file. This -undermines the elaborate C<-I> options that Cons constructs to make the -preprocessor conform to its preferred search path. - -Consequently, when using repository trees in Cons, B<always> use -angle-brackets for included files in any C source (.c or .h) files that -you plan to modify locally: - - #include <file.h> /* USE ANGLE-BRACKETS INSTEAD */ - -Code that will not change can still safely use double quotes on #include -lines. - - -=head2 Repository_List - -Cons provides a C<Repository_List> command to return a list of all -repository directories in their current search order. This can be used for -debugging, or to do more complex Perl stuff: - - @list = Repository_List; - print join(' ', @list), "\n"; - - -=head2 Repository interaction with other Cons features - -Cons' handling of repository trees interacts correctly with other Cons -features--which is to say, it generally does what you would expect. - -Most notably, repository trees interact correctly, and rather powerfully, -with the 'Link' command. A repository tree may contain one or more -subdirectories for version builds established via C<Link> to a source -subdirectory. Cons will search for derived files in the appropriate build -subdirectories under the repository tree. - - -=head1 Default targets - -Until now, we've demonstrated invoking Cons with an explicit target -to build: - - % cons hello - -Normally, Cons does not build anything unless a target is specified, -but specifying '.' (the current directory) will build everything: - - % cons # does not build anything - - % cons . # builds everything under the top-level directory - -Adding the C<Default> method to any F<Construct> or F<Conscript> file will add -the specified targets to a list of default targets. Cons will build -these defaults if there are no targets specified on the command line. -So adding the following line to the top-level F<Construct> file will mimic -Make's typical behavior of building everything by default: - - Default '.'; - -The following would add the F<hello> and F<goodbye> commands (in the -same directory as the F<Construct> or F<Conscript> file) to the default list: - - Default qw( - hello - goodbye - ); - -The C<Default> method may be used more than once to add targets to the -default list. - -=head1 Selective builds - -Cons provides two methods for reducing the size of given build. The first is -by specifying targets on the command line, and the second is a method for -pruning the build tree. We'll consider target specification first. - - -=head2 Selective targeting - -Like make, Cons allows the specification of ``targets'' on the command -line. Cons targets may be either files or directories. When a directory is -specified, this is simply a short-hand notation for every derivable -product--that Cons knows about--in the specified directory and below. For -example: - - % cons build/hello/hello.o - -means build F<hello.o> and everything that F<hello.o> might need. This is -from a previous version of the B<Hello, World!> program in which F<hello.o> -depended upon F<export/include/world.h>. If that file is not up-to-date -(because someone modified F<src/world/world.h)>, then it will be rebuilt, -even though it is in a directory remote from F<build/hello>. - -In this example: - - % cons build - -Everything in the F<build> directory is built, if necessary. Again, this may -cause more files to be built. In particular, both F<export/include/world.h> -and F<export/lib/libworld.a> are required by the F<build/hello> directory, -and so they will be built if they are out-of-date. - -If we do, instead: - - % cons export - -then only the files that should be installed in the export directory will be -rebuilt, if necessary, and then installed there. Note that C<cons build> -might build files that C<cons export> doesn't build, and vice-versa. - - -=head2 No ``special'' targets - -With Cons, make-style ``special'' targets are not required. The simplest -analog with Cons is to use special F<export> directories, instead. Let's -suppose, for example, that you have a whole series of unit tests that are -associated with your code. The tests live in the source directory near the -code. Normally, however, you don't want to build these tests. One solution -is to provide all the build instructions for creating the tests, and then to -install the tests into a separate part of the tree. If we install the tests -in a top-level directory called F<tests>, then: - - % cons tests - -will build all the tests. - - % cons export - -will build the production version of the system (but not the tests), and: - - % cons build - -should probably be avoided (since it will compile tests unnecessarily). - -If you want to build just a single test, then you could explicitly name the -test (in either the F<tests> directory or the F<build> directory). You could -also aggregate the tests into a convenient hierarchy within the tests -directory. This hierarchy need not necessarily match the source hierarchy, -in much the same manner that the include hierarchy probably doesn't match -the source hierarchy (the include hierarchy is unlikely to be more than two -levels deep, for C programs). - -If you want to build absolutely everything in the tree (subject to whatever -options you select), you can use: - - % cons . - -This is not particularly efficient, since it will redundantly walk all the -trees, including the source tree. The source tree, of course, may have -buildable objects in it--nothing stops you from doing this, even if you -normally build in a separate build tree. - - -=head1 Build Pruning - -In conjunction with target selection, B<build pruning> can be used to reduce -the scope of the build. In the previous peAcH and baNaNa example, we have -already seen how script-driven build pruning can be used to make only half -of the potential build available for any given invocation of C<cons>. Cons -also provides, as a convenience, a command line convention that allows you -to specify which F<Conscript> files actually get ``built''--that is, -incorporated into the build tree. For example: - - % cons build +world - -The C<+> argument introduces a Perl regular expression. This must, of -course, be quoted at the shell level if there are any shell meta-characters -within the expression. The expression is matched against each F<Conscript> -file which has been mentioned in a C<Build> statement, and only those -scripts with matching names are actually incorporated into the build -tree. Multiple such arguments are allowed, in which case a match against any -of them is sufficient to cause a script to be included. - -In the example, above, the F<hello> program will not be built, since Cons -will have no knowledge of the script F<hello/Conscript>. The F<libworld.a> -archive will be built, however, if need be. - -There are a couple of uses for build pruning via the command line. Perhaps -the most useful is the ability to make local changes, and then, with -sufficient knowledge of the consequences of those changes, restrict the size -of the build tree in order to speed up the rebuild time. A second use for -build pruning is to actively prevent the recompilation of certain files that -you know will recompile due to, for example, a modified header file. You may -know that either the changes to the header file are immaterial, or that the -changes may be safely ignored for most of the tree, for testing -purposes.With Cons, the view is that it is pragmatic to admit this type of -behavior, with the understanding that on the next full build everything that -needs to be rebuilt will be. There is no equivalent to a ``make touch'' -command, to mark files as permanently up-to-date. So any risk that is -incurred by build pruning is mitigated. For release quality work, obviously, -we recommend that you do not use build pruning (it's perfectly OK to use -during integration, however, for checking compilation, etc. Just be sure to -do an unconstrained build before committing the integration). - - -=head1 Temporary overrides - -Cons provides a very simple mechanism for overriding aspects of a build. The -essence is that you write an override file containing one or more -C<Override> commands, and you specify this on the command line, when you run -C<cons>: - - % cons -o over export - -will build the F<export> directory, with all derived files subject to the -overrides present in the F<over> file. If you leave out the C<-o> option, -then everything necessary to remove all overrides will be rebuilt. - - -=head2 Overriding environment variables - -The override file can contain two types of overrides. The first is incoming -environment variables. These are normally accessible by the F<Construct> -file from the C<%ENV> hash variable. These can trivially be overridden in -the override file by setting the appropriate elements of C<%ENV> (these -could also be overridden in the user's environment, of course). - - -=head2 The Override command - -The second type of override is accomplished with the C<Override> command, -which looks like this: - - Override <regexp>, <var1> => <value1>, <var2> => <value2>, ...; - -The regular expression I<regexp> is matched against every derived file that -is a candidate for the build. If the derived file matches, then the -variable/value pairs are used to override the values in the construction -environment associated with the derived file. - -Let's suppose that we have a construction environment like this: - - $CONS = new cons( - COPT => '', - CDBG => '-g', - CFLAGS => '%COPT %CDBG', - ); - -Then if we have an override file F<over> containing this command: - - Override '\.o$', COPT => '-O', CDBG => ''; - -then any C<cons> invocation with C<-o over> that creates F<.o> files via -this environment will cause them to be compiled with C<-O >and no C<-g>. The -override could, of course, be restricted to a single directory by the -appropriate selection of a regular expression. - -Here's the original version of the Hello, World! program, built with this -environment. Note that Cons rebuilds the appropriate pieces when the -override is applied or removed: - - % cons hello - cc -g -c hello.c -o hello.o - cc -o hello hello.o - % cons -o over hello - cc -O -c hello.c -o hello.o - cc -o hello hello.o - % cons -o over hello - cons: "hello" is up-to-date. - % cons hello - cc -g -c hello.c -o hello.o - cc -o hello hello.o - -It's important that the C<Override> command only be used for temporary, -on-the-fly overrides necessary for development because the overrides are not -platform independent and because they rely too much on intimate knowledge of -the workings of the scripts. For temporary use, however, they are exactly -what you want. - -Note that it is still useful to provide, say, the ability to create a fully -optimized version of a system for production use--from the F<Construct> and -F<Conscript> files. This way you can tailor the optimized system to the -platform. Where optimizer trade-offs need to be made (particular files may -not be compiled with full optimization, for example), then these can be -recorded for posterity (and reproducibility) directly in the scripts. - - -=head1 More on construction environments - -As previously mentioned, a B<construction environment> is an object that -has a set of keyword/value pairs and a set of methods, and which is used -to tell Cons how target files should be built. This section describes -how Cons uses and expands construction environment values to control its -build behavior. - -=head2 Construction variable expansion - -Construction variables from a construction environment are expanded -by preceding the keyword with a C<%> (percent sign): - - Construction variables: - XYZZY => 'abracadabra', - - The string: "The magic word is: %XYZZY!" - expands to: "The magic word is: abracadabra!" - -A construction variable name may be surrounded by C<{> and C<}> (curly -braces), which are stripped as part of the expansion. This can -sometimes be necessary to separate a variable expansion from trailing -alphanumeric characters: - - Construction variables: - OPT => 'value1', - OPTION => 'value2', - - The string: "%OPT %{OPT}ION %OPTION %{OPTION}" - expands to: "value1 value1ION value2 value2" - -Construction variable expansion is recursive--that is, a string -containing C<%->expansions after substitution will be re-expanded until -no further substitutions can be made: - - Construction variables: - STRING => 'The result is: %FOO', - FOO => '%BAR', - BAR => 'final value', - - The string: "The string says: %STRING" - expands to: "The string says: The result is: final value" - -If a construction variable is not defined in an environment, then the -null string is substituted: - - Construction variables: - FOO => 'value1', - BAR => 'value2', - - The string: "%FOO <%NO_VARIABLE> %BAR" - expands to: "value1 <> value2" - -A doubled C<%%> will be replaced by a single C<%>: - - The string: "Here is a percent sign: %%" - expands to: "Here is a percent sign: %" - -=head2 Default construction variables - -When you specify no arguments when creating a new construction -environment: - - $env = new cons(); - -Cons creates a reference to a new, default construction -environment. This contains a number of construction variables and some -methods. At the present writing, the default construction variables on a -UNIX system are: - - CC => 'cc', - CFLAGS => '', - CCCOM => '%CC %CFLAGS %_IFLAGS -c %< -o %>', - CXX => '%CC', - CXXFLAGS => '%CFLAGS', - CXXCOM => '%CXX %CXXFLAGS %_IFLAGS -c %< -o %>', - INCDIRPREFIX => '-I', - INCDIRSUFFIX => '', - LINK => '%CXX', - LINKCOM => '%LINK %LDFLAGS -o %> %< %_LDIRS %LIBS', - LINKMODULECOM => '%LD -r -o %> %<', - LIBDIRPREFIX => '-L', - LIBDIRSUFFIX => '', - AR => 'ar', - ARFLAGS => 'r', - ARCOM => ['%AR %ARFLAGS %> %<', '%RANLIB %>'], - RANLIB => 'ranlib', - AS => 'as', - ASFLAGS => '', - ASCOM => '%AS %ASFLAGS %< -o %>', - LD => 'ld', - LDFLAGS => '', - PREFLIB => 'lib', - SUFLIB => '.a', - SUFLIBS => '.so:.a', - SUFOBJ => '.o', - SIGNATURE => [ '*' => 'build' ], - ENV => { 'PATH' => '/bin:/usr/bin' }, - - -And on a Win32 system (Windows NT), the default construction variables -are (unless the default rule style is set using the B<DefaultRules> -method): - - CC => 'cl', - CFLAGS => '/nologo', - CCCOM => '%CC %CFLAGS %_IFLAGS /c %< /Fo%>', - CXXCOM => '%CXX %CXXFLAGS %_IFLAGS /c %< /Fo%>', - INCDIRPREFIX => '/I', - INCDIRSUFFIX => '', - LINK => 'link', - LINKCOM => '%LINK %LDFLAGS /out:%> %< %_LDIRS %LIBS', - LINKMODULECOM => '%LD /r /o %> %<', - LIBDIRPREFIX => '/LIBPATH:', - LIBDIRSUFFIX => '', - AR => 'lib', - ARFLAGS => '/nologo ', - ARCOM => "%AR %ARFLAGS /out:%> %<", - RANLIB => '', - LD => 'link', - LDFLAGS => '/nologo ', - PREFLIB => '', - SUFEXE => '.exe', - SUFLIB => '.lib', - SUFLIBS => '.dll:.lib', - SUFOBJ => '.obj', - SIGNATURE => [ '*' => 'build' ], - -These variables are used by the various methods associated with the -environment. In particular, any method that ultimately invokes an external -command will substitute these variables into the final command, as -appropriate. For example, the C<Objects> method takes a number of source -files and arranges to derive, if necessary, the corresponding object -files: - - Objects $env 'foo.c', 'bar.c'; - -This will arrange to produce, if necessary, F<foo.o> and F<bar.o>. The -command invoked is simply C<%CCCOM>, which expands, through substitution, -to the appropriate external command required to build each object. The -substitution rules will be discussed in detail in the next section. - -The construction variables are also used for other purposes. For example, -C<CPPPATH> is used to specify a colon-separated path of include -directories. These are intended to be passed to the C preprocessor and are -also used by the C-file scanning machinery to determine the dependencies -involved in a C Compilation. - -Variables beginning with underscore are created by various methods, -and should normally be considered ``internal'' variables. For example, -when a method is called which calls for the creation of an object from -a C source, the variable C<_IFLAGS> is created: this corresponds to the -C<-I> switches required by the C compiler to represent the directories -specified by C<CPPPATH>. - -Note that, for any particular environment, the value of a variable is set -once, and then never reset (to change a variable, you must create a new -environment. Methods are provided for copying existing environments for this -purpose). Some internal variables, such as C<_IFLAGS> are created on demand, -but once set, they remain fixed for the life of the environment. - -The C<CFLAGS>, C<LDFLAGS>, and C<ARFLAGS> variables all supply a place -for passing options to the compiler, loader, and archiver, respectively. - -The C<INCDIRPREFIX> and C<INCDIRSUFFIX> variables specify option -strings to be appended to the beginning and end, respectively, of each -include directory so that the compiler knows where to find F<.h> files. -Similarly, the C<LIBDIRPREFIX> and C<LIBDIRSUFFIX> variables specify the -option string to be appended to the beginning of and end, respectively, -of each directory that the linker should search for libraries. - -Another variable, C<ENV>, is used to determine the system environment during -the execution of an external command. By default, the only environment -variable that is set is C<PATH>, which is the execution path for a UNIX -command. For the utmost reproducibility, you should really arrange to set -your own execution path, in your top-level F<Construct> file (or perhaps by -importing an appropriate construction package with the Perl C<use> -command). The default variables are intended to get you off the ground. - -=head2 Expanding variables in construction commands - -Within a construction command, construction variables will be expanded -according to the rules described above. In addition to normal variable -expansion from the construction environment, construction commands also -expand the following pseudo-variables to insert the specific input and -output files in the command line that will be executed: - -=over 10 - -=item %> - -The target file name. In a multi-target command, this expands to the -first target mentioned.) - -=item %0 - -Same as C<%E<gt>>. - -=item %1, %2, ..., %9 - -These refer to the first through ninth input file, respectively. - -=item %E<lt> - -The full set of input file names. If any of these have been used -anywhere else in the current command line (via C<%1>, C<%2>, etc.), then -those will be deleted from the list provided by C<%E<lt>>. Consider the -following command found in a F<Conscript> file in the F<test> directory: - - Command $env 'tgt', qw(foo bar baz), qq( - echo %< -i %1 > %> - echo %< -i %2 >> %> - echo %< -i %3 >> %> - ); - -If F<tgt> needed to be updated, then this would result in the execution of -the following commands, assuming that no remapping has been established for -the F<test> directory: - - echo test/bar test/baz -i test/foo > test/tgt - echo test/foo test/baz -i test/bar >> test/tgt - echo test/foo test/bar -i test/baz >> test/tgt - -=back - -Any of the above pseudo-variables may be followed immediately by one of -the following suffixes to select a portion of the expanded path name: - - :a the absolute path to the file name - :b the directory plus the file name stripped of any suffix - :d the directory - :f the file name - :s the file name suffix - :F the file name stripped of any suffix - :S the absolute path path to a Linked source file - -Continuing with the above example, C<%E<lt>:f> would expand to C<foo bar baz>, -and C<%E<gt>:d> would expand to C<test>. - -There are additional C<%> elements which affect the command line(s): - -=over 10 - -=item %[ %] - -It is possible to programmatically rewrite part of the command by -enclosing part of it between C<%[> and C<%]>. This will call the -construction variable named as the first word enclosed in the brackets -as a Perl code reference; the results of this call will be used to -replace the contents of the brackets in the command line. For example, -given an existing input file named F<tgt.in>: - - @keywords = qw(foo bar baz); - $env = new cons(X_COMMA => sub { join(",", @_) }); - Command $env 'tgt', 'tgt.in', qq( - echo '# Keywords: %[X_COMMA @keywords %]' > %> - cat %< >> %> - ); - -This will execute: - - echo '# Keywords: foo,bar,baz' > tgt - cat tgt.in >> tgt - -=item %( %) - -Cons includes the text of the command line in the MD5 signature for a -build, so that targets get rebuilt if you change the command line (to -add or remove an option, for example). Command-line text in between -C<%(> and C<%)>, however, will be ignored for MD5 signature calculation. - -Internally, Cons uses C<%(> and C<%)> around include and library -directory options (C<-I> and C<-L> on UNIX systems, C</I> and -C</LIBPATH> on Windows NT) to avoid rebuilds just because the directory -list changes. Rebuilds occur only if the changed directory list causes -any included I<files> to change, and a changed include file is detected -by the MD5 signature calculation on the actual file contents. - -=back - -=head2 Expanding construction variables in file names - -Cons expands construction variables in the source and target file names -passed to the various construction methods according to the expansion -rules described above: - - $env = new cons( - DESTDIR => 'programs', - SRCDIR => 'src', - ); - Program $env '%DESTDIR/hello', '%SRCDIR/hello.c'; - -This allows for flexible configuration, through the construction -environment, of directory names, suffixes, etc. - - -=head1 Build actions - -Cons supports several types of B<build actions> that can be performed -to construct one or more target files. Usually, a build action is -a construction command--that is, a command-line string that invokes -an external command. Cons can also execute Perl code embedded in a -command-line string, and even supports an experimental ability to build -a target file by executing a Perl code reference directly. - -A build action is usually specified as the value of a construction -variable: - - $env = new cons( - CCCOM => '%CC %CFLAGS %_IFLAGS -c %< -o %>', - LINKCOM => '[perl] &link_executable("%>", "%<")', - ARCOM => sub { my($env, $target, @sources) = @_; - # code to create an archive - } - ); - -A build action may be associated directly with one or more target files -via the C<Command> method; see below. - -=head2 Construction commands - -A construction command goes through expansion of construction variables -and C<%-> pseudo-variables, as described above, to create the actual -command line that Cons will execute to generate the target file or -files. - -After substitution occurs, strings of white space are converted into -single blanks, and leading and trailing white space is eliminated. It -is therefore currently not possible to introduce variable length white -space in strings passed into a command. - -If a multi-line command string is provided, the commands are executed -sequentially. If any of the commands fails, then none of the rest are -executed, and the target is not marked as updated, i.e. a new signature is -not stored for the target. - -Normally, if all the commands succeed, and return a zero status (or whatever -platform-specific indication of success is required), then a new signature -is stored for the target. If a command erroneously reports success even -after a failure, then Cons will assume that the target file created by that -command is accurate and up-to-date. - -The first word of each command string, after expansion, is assumed to be an -executable command looked up on the C<PATH> environment variable (which is, -in turn, specified by the C<ENV> construction variable). If this command is -found on the path, then the target will depend upon it: the command will -therefore be automatically built, as necessary. It's possible to write -multi-part commands to some shells, separated by semi-colons. Only the first -command word will be depended upon, however, so if you write your command -strings this way, you must either explicitly set up a dependency (with the -C<Depends> method), or be sure that the command you are using is a system -command which is expected to be available. If it isn't available, you will, -of course, get an error. - -Cons normally prints a command before executing it. This behavior is -suppressed if the first character of the command is C<@>. Note that -you may need to separate the C<@> from the command name or escape it to -prevent C<@cmd> from looking like an array to Perl quote operators that -perform interpolation: - - # The first command line is incorrect, - # because "@cp" looks like an array - # to the Perl qq// function. - # Use the second form instead. - Command $env 'foo', 'foo.in', qq( - @cp %< tempfile - @ cp tempfile %> - ); - -If there are shell meta characters anywhere in the expanded command line, -such as C<E<lt>>, C<E<gt>>, quotes, or semi-colon, then the command -will actually be executed by invoking a shell. This means that a command -such as: - - cd foo - -alone will typically fail, since there is no command C<cd> on the path. But -the command string: - - cd $<:d; tar cf $>:f $<:f - -when expanded will still contain the shell meta character semi-colon, and a -shell will be invoked to interpret the command. Since C<cd> is interpreted -by this sub-shell, the command will execute as expected. - -=head2 Perl expressions - -If any command (even one within a multi-line command) begins with -C<[perl]>, the remainder of that command line will be evaluated by the -running Perl instead of being forked by the shell. If an error occurs -in parsing the Perl code, or if the Perl expression returns 0 or undef, -the command will be considered to have failed. For example, here is a -simple command which creates a file C<foo> directly from Perl: - - $env = new cons(); - Command $env 'foo', - qq([perl] open(FOO,'>foo');print FOO "hi\\n"; close(FOO); 1); - -Note that when the command is executed, you are in the same package as -when the F<Construct> or F<Conscript> file was read, so you can call -Perl functions you've defined in the same F<Construct> or F<Conscript> -file in which the C<Command> appears: - - $env = new cons(); - sub create_file { - my $file = shift; - open(FILE, ">$file"); - print FILE "hi\n"; - close(FILE); - return 1; - } - Command $env 'foo', "[perl] &create_file('%>')"; - -The Perl string will be used to generate the signature for the derived -file, so if you change the string, the file will be rebuilt. The contents -of any subroutines you call, however, are not part of the signature, -so if you modify a called subroutine such as C<create_file> above, -the target will I<not> be rebuilt. Caveat user. - -=head2 Perl code references [EXPERIMENTAL] - -Cons supports the ability to create a derived file by directly executing -a Perl code reference. This feature is considered EXPERIMENTAL and -subject to change in the future. - -A code reference may either be a named subroutine referenced by the -usual C<\&> syntax: - - sub build_output { - my($env, $target, @sources) = @_; - print "build_output building $target\n"; - open(OUT, ">$target"); - foreach $src (@sources) { - if (! open(IN, "<$src")) { - print STDERR "cannot open '$src': $!\n"; - return undef; - } - print OUT, <IN>; - } - close(OUT); - return 1; - } - Command $env 'output', \&build_output; - -or the code reference may be an anonymous subroutine: - - Command $env 'output', sub { - my($env, $target, @sources) = @_; - print "building $target\n"; - open(FILE, ">$target"); - print FILE "hello\n"; - close(FILE); - return 1; - }; - -To build the target file, the referenced subroutine is passed, in order: -the construction environment used to generate the target; the path -name of the target itself; and the path names of all the source files -necessary to build the target file. - -The code reference is expected to generate the target file, of course, -but may manipulate the source and target files in any way it chooses. -The code reference must return a false value (C<undef> or C<0>) if -the build of the file failed. Any true value indicates a successful -build of the target. - -Building target files using code references is considered EXPERIMENTAL -due to the following current limitations: - -=over 4 - -Cons does I<not> print anything to indicate the code reference is being -called to build the file. The only way to give the user any indication -is to have the code reference explicitly print some sort of "building" -message, as in the above examples. - -Cons does not generate any signatures for code references, so if the -code in the reference changes, the target will I<not> be rebuilt. - -Cons has no public method to allow a code reference to extract -construction variables. This would be good to allow generalization of -code references based on the current construction environment, but would -also complicate the problem of generating meaningful signatures for code -references. - -=back - -Support for building targets via code references has been released in -this version to encourage experimentation and the seeking of possible -solutions to the above limitations. - - -=head1 Default construction methods - -The list of default construction methods includes the following: - - -=head2 The C<new> constructor - -The C<new> method is a Perl object constructor. That is, it is not invoked -via a reference to an existing construction environment B<reference>, but, -rather statically, using the name of the Perl B<package> where the -constructor is defined. The method is invoked like this: - - $env = new cons(<overrides>); - -The environment you get back is blessed into the package C<cons>, which -means that it will have associated with it the default methods described -below. Individual construction variables can be overridden by providing -name/value pairs in an override list. Note that to override any command -environment variable (i.e. anything under C<ENV>), you will have to override -all of them. You can get around this difficulty by using the C<copy> method -on an existing construction environment. - - -=head2 The C<clone> method - -The C<clone> method creates a clone of an existing construction environment, -and can be called as in the following example: - - $env2 = $env1->clone(<overrides>); - -You can provide overrides in the usual manner to create a different -environment from the original. If you just want a new name for the same -environment (which may be helpful when exporting environments to existing -components), you can just use simple assignment. - - -=head2 The C<copy> method - -The C<copy> method extracts the externally defined construction variables -from an environment and returns them as a list of name/value -pairs. Overrides can also be provided, in which case, the overridden values -will be returned, as appropriate. The returned list can be assigned to a -hash, as shown in the prototype, below, but it can also be manipulated in -other ways: - - %env = $env1->copy(<overrides>); - -The value of C<ENV>, which is itself a hash, is also copied to a new hash, -so this may be changed without fear of affecting the original -environment. So, for example, if you really want to override just the -C<PATH> variable in the default environment, you could do the following: - - %cons = new cons()->copy(); - $cons{ENV}{PATH} = "<your path here>"; - $cons = new cons(%cons); - -This will leave anything else that might be in the default execution -environment undisturbed. - - -=head2 The C<Install> method - -The C<Install> method arranges for the specified files to be installed in -the specified directory. The installation is optimized: the file is not -copied if it can be linked. If this is not the desired behavior, you will -need to use a different method to install the file. It is called as follows: - - Install $env <directory>, <names>; - -Note that, while the files to be installed may be arbitrarily named, -only the last component of each name is used for the installed target -name. So, for example, if you arrange to install F<foo/bar> in F<baz>, -this will create a F<bar> file in the F<baz> directory (not F<foo/bar>). - - -=head2 The C<InstallAs> method - -The C<InstallAs> method arranges for the specified source file(s) to be -installed as the specified target file(s). Multiple files should be -specified as a file list. The installation is optimized: the file is not -copied if it can be linked. If this is not the desired behavior, you will -need to use a different method to install the file. It is called as follows: - -C<InstallAs> works in two ways: - -Single file install: - - InstallAs $env TgtFile, SrcFile; - -Multiple file install: - - InstallAs $env ['tgt1', 'tgt2'], ['src1', 'src2']; - -Or, even as: - - @srcs = qw(src1 src2 src3); - @tgts = qw(tgt1 tgt2 tgt3); - InstallAs $env [@tgts], [@srcs]; - -Both the target and the sources lists should be of the same length. - -=head2 The C<Precious> method - -The C<Precious> method asks cons not to delete the specified file or -list of files before building them again. It is invoked as: - - Precious <files>; - -This is especially useful for allowing incremental updates to libraries -or debug information files which are updated rather than rebuilt anew each -time. Cons will still delete the files when the C<-r> flag is specified. - -=head2 The C<AfterBuild> method - -The C<AfterBuild> method evaluates the specified perl string after -building the given file or files (or finding that they are up to date). -The eval will happen once per specified file. C<AfterBuild> is called -as follows: - - AfterBuild $env 'foo.o', qq(print "foo.o is up to date!\n"); - -The perl string is evaluated in the C<script> package, and has access -to all variables and subroutines defined in the F<Conscript> file in -which the C<AfterBuild> method is called. - -=head2 The C<Command> method - -The C<Command> method is a catchall method which can be used to arrange for -any build action to be executed to update the target. For this command, a -target file and list of inputs is provided. In addition, a build action -is specified as the last argument. The build action is typically a -command line or lines, but may also contain Perl code to be executed; -see the section above on build actions for details. - -The C<Command> method is called as follows: - - Command $env <target>, <inputs>, <build action>; - -The target is made dependent upon the list of input files specified, and the -inputs must be built successfully or Cons will not attempt to build the -target. - -To specify a command with multiple targets, you can specify a reference to a -list of targets. In Perl, a list reference can be created by enclosing a -list in square brackets. Hence the following command: - - Command $env ['foo.h', 'foo.c'], 'foo.template', q( - gen %1 - ); - -could be used in a case where the command C<gen> creates two files, both -F<foo.h> and F<foo.c>. - - -=head2 The C<Objects> method - -The C<Objects> method arranges to create the object files that correspond to -the specified source files. It is invoked as shown below: - - @files = Objects $env <source or object files>; - -Under Unix, source files ending in F<.s> and F<.c> are currently -supported, and will be compiled into a name of the same file ending -in F<.o>. By default, all files are created by invoking the external -command which results from expanding the C<CCCOM> construction variable, -with C<%E<lt>> and C<%E<gt>> set to the source and object files, -respectively. (See the section above on construction variable expansion -for details). The variable C<CPPPATH> is also used when scanning source -files for dependencies. This is a colon separated list of pathnames, and -is also used to create the construction variable C<_IFLAGS,> which will -contain the appropriate list of -C<I> options for the compilation. Any -relative pathnames in C<CPPPATH> is interpreted relative to the -directory in which the associated construction environment was created -(absolute and top-relative names may also be used). This variable is -used by C<CCCOM>. The behavior of this command can be modified by -changing any of the variables which are interpolated into C<CCCOM>, such -as C<CC>, C<CFLAGS>, and, indirectly, C<CPPPATH>. It's also possible -to replace the value of C<CCCOM>, itself. As a convenience, this file -returns the list of object filenames. - - -=head2 The C<Program> method - -The C<Program> method arranges to link the specified program with the -specified object files. It is invoked in the following manner: - - Program $env <program name>, <source or object files>; - -The program name will have the value of the C<SUFEXE> construction -variable appended (by default, C<.exe> on Win32 systems, nothing on Unix -systems) if the suffix is not already present. - -Source files may be specified in place of objects files--the C<Objects> -method will be invoked to arrange the conversion of all the files into -object files, and hence all the observations about the C<Objects> method, -above, apply to this method also. - -The actual linking of the program will be handled by an external command -which results from expanding the C<LINKCOM> construction variable, with -C<%E<lt>> set to the object files to be linked (in the order presented), -and C<%E<gt>> set to the target. (See the section above on construction -variable expansion for details.) The user may set additional variables -in the construction environment, including C<LINK>, to define which -program to use for linking, C<LIBPATH>, a colon-separated list of -library search paths, for use with library specifications of the form -I<-llib>, and C<LIBS>, specifying the list of libraries to link against -(in either I<-llib> form or just as pathnames. Relative pathnames in -both C<LIBPATH> and C<LIBS> are interpreted relative to the directory -in which the associated construction environment is created (absolute -and top-relative names may also be used). Cons automatically sets up -dependencies on any libraries mentioned in C<LIBS>: those libraries will -be built before the command is linked. - - -=head2 The C<Library> method - -The C<Library> method arranges to create the specified library from the -specified object files. It is invoked as follows: - - Library $env <library name>, <source or object files>; - -The library name will have the value of the C<SUFLIB> construction -variable appended (by default, C<.lib> on Win32 systems, C<.a> on Unix -systems) if the suffix is not already present. - -Source files may be specified in place of objects files--the C<Objects> -method will be invoked to arrange the conversion of all the files into -object files, and hence all the observations about the C<Objects> method, -above, apply to this method also. - -The actual creation of the library will be handled by an external -command which results from expanding the C<ARCOM> construction variable, -with C<%E<lt>> set to the library members (in the order presented), -and C<%E<gt>> to the library to be created. (See the section above -on construction variable expansion for details.) The user may set -variables in the construction environment which will affect the -operation of the command. These include C<AR>, the archive program -to use, C<ARFLAGS>, which can be used to modify the flags given to -the program specified by C<AR>, and C<RANLIB>, the name of a archive -index generation program, if needed (if the particular need does not -require the latter functionality, then C<ARCOM> must be redefined to not -reference C<RANLIB>). - -The C<Library> method allows the same library to be specified in multiple -method invocations. All of the contributing objects from all the invocations -(which may be from different directories) are combined and generated by a -single archive command. Note, however, that if you prune a build so that -only part of a library is specified, then only that part of the library will -be generated (the rest will disappear!). - - -=head2 The C<Module> method - -The C<Module> method is a combination of the C<Program> and C<Command> -methods. Rather than generating an executable program directly, this command -allows you to specify your own command to actually generate a module. The -method is invoked as follows: - - Module $env <module name>, <source or object files>, <construction command>; - -This command is useful in instances where you wish to create, for example, -dynamically loaded modules, or statically linked code libraries. - - -=head2 The C<Depends> method - -The C<Depends> method allows you to specify additional dependencies for a -target. It is invoked as follows: - - Depends $env <target>, <dependencies>; - -This may be occasionally useful, especially in cases where no scanner exists -(or is writable) for particular types of files. Normally, dependencies are -calculated automatically from a combination of the explicit dependencies set -up by the method invocation or by scanning source files. - -A set of identical dependencies for multiple targets may be specified -using a reference to a list of targets. In Perl, a list reference can -be created by enclosing a list in square brackets. Hence the following -command: - - Depends $env ['foo', 'bar'], 'input_file_1', 'input_file_2'; - -specifies that both the F<foo> and F<bar> files depend on the listed -input files. - - -=head2 The C<RuleSet> method - -The C<RuleSet> method returns the construction variables for building -various components with one of the rule sets supported by Cons. The -currently supported rule sets are: - -=over 4 - -=item msvc - -Rules for the Microsoft Visual C++ compiler suite. - -=item unix - -Generic rules for most UNIX-like compiler suites. - -=back - -On systems with more than one available compiler suite, this allows you -to easily create side-by-side environments for building software with -multiple tools: - - $msvcenv = new cons(RuleSet("msvc")); - $cygnusenv = new cons(RuleSet("unix")); - -In the future, this could also be extended to other platforms that -have different default rule sets. - - -=head2 The C<DefaultRules> method - -The C<DefaultRules> method sets the default construction variables that -will be returned by the C<new> method to the specified arguments: - - DefaultRules(CC => 'gcc', - CFLAGS => '', - CCCOM => '%CC %CFLAGS %_IFLAGS -c %< -o %>'); - $env = new cons(); - # $env now contains *only* the CC, CFLAGS, - # and CCCOM construction variables - -Combined with the C<RuleSet> method, this also provides an easy way -to set explicitly the default build environment to use some supported -toolset other than the Cons defaults: - - # use a UNIX-like tool suite (like cygwin) on Win32 - DefaultRules(RuleSet('unix')); - $env = new cons(); - -Note that the C<DefaultRules> method completely replaces the default -construction environment with the specified arguments, it does not -simply override the existing defaults. To override one or more -variables in a supported C<RuleSet>, append the variables and values: - - DefaultRules(RuleSet('unix'), CFLAGS => '-O3'); - $env1 = new cons(); - $env2 = new cons(); - # both $env1 and $env2 have 'unix' defaults - # with CFLAGS set to '-O3' - - -=head2 The C<Ignore> method - -The C<Ignore> method allows you to ignore explicitly dependencies that -Cons infers on its own. It is invoked as follows: - - Ignore <patterns>; - -This can be used to avoid recompilations due to changes in system header -files or utilities that are known to not affect the generated targets. - -If, for example, a program is built in an NFS-mounted directory on -multiple systems that have different copies of F<stdio.h>, the differences -will affect the signatures of all derived targets built from source files -that C<#include E<lt>stdio.hE<gt>>. This will cause all those targets to -be rebuilt when changing systems. If this is not desirable behavior, then -the following line will remove the dependencies on the F<stdio.h> file: - - Ignore '^/usr/include/stdio\.h$'; - -Note that the arguments to the C<Ignore> method are regular expressions, -so special characters must be escaped and you may wish to anchor the -beginning or end of the expression with C<^> or C<$> characters. - - -=head2 The C<Salt> method - -The C<Salt> method adds a constant value to the signature calculation -for every derived file. It is invoked as follows: - - Salt $string; - -Changing the Salt value will force a complete rebuild of every derived -file. This can be used to force rebuilds in certain desired -circumstances. For example, - - Salt `uname -s`; - -Would force a complete rebuild of every derived file whenever the -operating system on which the build is performed (as reported by C<uname --s>) changes. - - -=head2 The C<UseCache> method - -The C<UseCache> method instructs Cons to maintain a cache of derived -files, to be shared among separate build trees of the same project. - - UseCache("cache/<buildname>") || warn("cache directory not found"); - - -=head2 The C<SourcePath> method - -The C<SourcePath> mathod returns the real source path name of a file, -as opposed to the path name within a build directory. It is invoked -as follows: - - $path = SourcePath <buildpath>; - - -=head2 The C<ConsPath> method - -The C<ConsPath> method returns true if the supplied path is a derivable -file, and returns undef (false) otherwise. -It is invoked as follows: - - $result = ConsPath <path>; - - -=head2 The C<SplitPath> method - -The C<SplitPath> method looks up multiple path names in a string separated -by the default path separator for the operating system (':' on UNIX -systems, ';' on Windows NT), and returns the fully-qualified names. -It is invoked as follows: - - @paths = SplitPath <pathlist>; - -The C<SplitPath> method will convert names prefixed '#' to the -appropriate top-level build name (without the '#') and will convert -relative names to top-level names. - - -=head2 The C<DirPath> method - -The C<DirPath> method returns the build path name(s) of a directory or -list of directories. It is invoked as follows: - - $cwd = DirPath <paths>; - -The most common use for the C<DirPath> method is: - - $cwd = DirPath '.'; - -to fetch the path to the current directory of a subsidiary F<Conscript> -file. - - -=head2 The C<FilePath> method - -The C<FilePath> method returns the build path name(s) of a file or -list of files. It is invoked as follows: - - $file = FilePath <path>; - - -=head2 The C<Help> method - -The C<Help> method specifies help text that will be displayed when the -user invokes C<cons -h>. This can be used to provide documentation -of specific targets, values, build options, etc. for the build tree. -It is invoked as follows: - - Help <helptext>; - -The C<Help> method may only be called once, and should typically be -specified in the top-level F<Construct> file. - - -=head1 Extending Cons - - -=head2 Overriding construction variables - -There are several ways of extending Cons, which vary in degree of -difficulty. The simplest method is to define your own construction -environment, based on the default environment, but modified to reflect your -particular needs. This will often suffice for C-based applications. You can -use the C<new> constructor, and the C<clone> and C<copy> methods to create -hybrid environments. These changes can be entirely transparent to the -underlying F<Conscript> files. - - -=head2 Adding new methods - -For slightly more demanding changes, you may wish to add new methods to the -C<cons> package. Here's an example of a very simple extension, -C<InstallScript>, which installs a tcl script in a requested location, but -edits the script first to reflect a platform-dependent path that needs to be -installed in the script: - - # cons::InstallScript - Create a platform dependent version of a shell - # script by replacing string ``#!your-path-here'' with platform specific - # path $BIN_DIR. - - sub cons::InstallScript { - my ($env, $dst, $src) = @_; - Command $env $dst, $src, qq( - sed s+your-path-here+$BIN_DIR+ %< > %> - chmod oug+x %> - ); - } - -Notice that this method is defined directly in the C<cons> package (by -prefixing the name with C<cons::>). A change made in this manner will be -globally visible to all environments, and could be called as in the -following example: - - InstallScript $env "$BIN/foo", "foo.tcl"; - -For a small improvement in generality, the C<BINDIR> variable could be -passed in as an argument or taken from the construction environment--as -C<%BINDIR>. - - -=head2 Overriding methods - -Instead of adding the method to the C<cons> name space, you could define a -new package which inherits existing methods from the C<cons> package and -overrides or adds others. This can be done using Perl's inheritance -mechanisms. - -The following example defines a new package C<cons::switch> which -overrides the standard C<Library> method. The overridden method builds -linked library modules, rather than library archives. A new -constructor is provided. Environments created with this constructor -will have the new library method; others won't. - - package cons::switch; - BEGIN {@ISA = 'cons'} - - sub new { - shift; - bless new cons(@_); - } - - sub Library { - my($env) = shift; - my($lib) = shift; - my(@objs) = Objects $env @_; - Command $env $lib, @objs, q( - %LD -r %LDFLAGS %< -o %> - ); - } - -This functionality could be invoked as in the following example: - - $env = new cons::switch(@overrides); - ... - Library $env 'lib.o', 'foo.c', 'bar.c'; - - -=head1 Invoking Cons - -The C<cons> command is usually invoked from the root of the build tree. A -F<Construct> file must exist in that directory. If the C<-f> argument is -used, then an alternate F<Construct> file may be used (and, possibly, an -alternate root, since C<cons> will cd to F<Construct> file's containing -directory). - -If C<cons> is invoked from a child of the root of the build tree with -the C<-t> argument, it will walk up the directory hierarchy looking for a -F<Construct> file. (An alternate name may still be specified with C<-f>.) -The targets supplied on the command line will be modified to be relative -to the discovered F<Construct> file. For example, from a directory -containing a top-level F<Construct> file, the following invocation: - - % cd libfoo/subdir - % cons -t target - -is exactly equivalent to: - - % cons libfoo/subdir/target - -If there are any C<Default> targets specified in the directory hierarchy's -F<Construct> or F<Conscript> files, only the default targets at or below -the directory from which C<cons -t> was invoked will be built. - -The command is invoked as follows: - - cons <arguments> -- <construct-args> - -where I<arguments> can be any of the following, in any order: - -=over 10 - -=item I<target> - -Build the specified target. If I<target> is a directory, then recursively -build everything within that directory. - -=item I<+pattern> - -Limit the F<Conscript> files considered to just those that match I<pattern>, -which is a Perl regular expression. Multiple C<+> arguments are accepted. - -=item I<name>=<val> - -Sets I<name> to value I<val> in the C<ARG> hash passed to the top-level -F<Construct> file. - -=item C<-cc> - -Show command that would have been executed, when retrieving from cache. No -indication that the file has been retrieved is given; this is useful for -generating build logs that can be compared with real build logs. - -=item C<-cd> - -Disable all caching. Do not retrieve from cache nor flush to cache. - -=item C<-cr> - -Build dependencies in random order. This is useful when building multiple -similar trees with caching enabled. - -=item C<-cs> - -Synchronize existing build targets that are found to be up-to-date with -cache. This is useful if caching has been disabled with -cc or just recently -enabled with UseCache. - -=item C<-d> - -Enable dependency debugging. - -=item C<-f> <file> - -Use the specified file instead of F<Construct> (but first change to -containing directory of I<file>). - -=item C<-h> - -Show a help message local to the current build if one such is defined, and -exit. - -=item C<-k> - -Keep going as far as possible after errors. - -=item C<-o> <file> - -Read override file I<file>. - -=item C<-p> - -Show construction products in specified trees. No build is attempted. - -=item C<-pa> - -Show construction products and associated actions. No build is attempted. - -=item C<-pw> - -Show products and where they are defined. No build is attempted. - -=item C<-q> - -Make the build quiet. Multiple C<-q> options may be specified. - -A single C<-q> options suppress messages about Installing and Removing -targets. - -Two C<-q> options suppress build command lines and target up-to-date -messages. - -=item C<-r> - -Remove construction products associated with <targets>. No build is -attempted. - -=item C<-R> <repos> - -Search for files in I<repos>. Multiple B<-R> I<repos> directories are -searched in the order specified. - -=item C<-S> <pkg> - -Use the sig::<pkg> package to calculate. Supported <pkg> values -include "md5" for MD5 signature calculation and "md5::debug" for debug -information about MD5 signature calculation. - -If the specified package ends in <::debug>, signature debug information -will be printed to the file name specified in the C<CONS_SIG_DEBUG> -environment variable, or to standard output if the environment variable -is not set. - -=item C<-t> - -Traverse up the directory hierarchy looking for a F<Construct> file, -if none exists in the current directory. Targets will be modified to -be relative to the F<Construct> file. - -Internally, C<cons> will change its working directory to the directory -which contains the top-level F<Construct> file and report: - - cons: Entering directory `top-level-directory' - -This message indicates to an invoking editor (such as emacs) or build -environment that Cons will now report all file names relative to the -top-level directory. This message can not be suppressed with the C<-q> -option. - -=item C<-v> - -Show C<cons> version and continue processing. - -=item C<-V> - -Show C<cons> version and exit. - -=item C<-wf> <file> - -Write all filenames considered into I<file>. - -=item C<-x> - -Show a help message similar to this one, and exit. - -=back - -And I<construct-args> can be any arguments that you wish to process in the -F<Construct> file. Note that there should be a B<--> separating the arguments -to cons and the arguments that you wish to process in the F<Construct> file. - -Processing of I<construct-args> can be done by any standard package like -B<Getopt> or its variants, or any user defined package. B<cons> will pass in -the I<construct-args> as B<@ARGV> and will not attempt to interpret anything -after the B<-->. - - % cons -R /usr/local/repository -d os=solaris +driver -- -c test -f DEBUG - -would pass the following to cons - - -R /usr/local/repository -d os=solaris +driver - -and the following, to the top level F<Construct> file as B<@ARGV> - - -c test -f DEBUG - -Note that C<cons -r .> is equivalent to a full recursive C<make clean>, -but requires no support in the F<Construct> file or any F<Conscript> -files. This is most useful if you are compiling files into source -directories (if you separate the F<build> and F<export> directories, -then you can just remove the directories). - -The options C<-p>, C<-pa>, and C<-pw> are extremely useful for use as an aid -in reading scripts or debugging them. If you want to know what script -installs F<export/include/foo.h>, for example, just type: - - % cons -pw export/include/foo.h - - -=head1 Using and writing dependency scanners - -QuickScan allows simple target-independent scanners to be set up for -source files. Only one QuickScan scanner may be associated with any given -source file and environment, although the same scanner may (and should) -be used for multiple files of a given type. - -A QuickScan scanner is only ever invoked once for a given source file, -and it is only invoked if the file is used by some target in the tree -(i.e., there is a dependency on the source file). - -QuickScan is invoked as follows: - - QuickScan CONSENV CODEREF, FILENAME [, PATH] - -The subroutine referenced by CODEREF is expected to return a list of -filenames included directly by FILE. These filenames will, in turn, be -scanned. The optional PATH argument supplies a lookup path for finding -FILENAME and/or files returned by the user-supplied subroutine. The PATH -may be a reference to an array of lookup-directory names, or a string of -names separated by the system's separator character (':' on UNIX systems, -';' on Windows NT). - -The subroutine is called once for each line in the file, with $_ set to the -current line. If the subroutine needs to look at additional lines, or, for -that matter, the entire file, then it may read them itself, from the -filehandle SCAN. It may also terminate the loop, if it knows that no further -include information is available, by closing the filehandle. - -Whether or not a lookup path is provided, QuickScan first tries to lookup -the file relative to the current directory (for the top-level file -supplied directly to QuickScan), or from the directory containing the -file which referenced the file. This is not very general, but seems good -enough--especially if you have the luxury of writing your own utilities -and can control the use of the search path in a standard way. - -Here's a real example, taken from a F<Construct> file here: - - sub cons::SMFgen { - my($env, @tables) = @_; - foreach $t (@tables) { - $env->QuickScan(sub { /\b\S*?\.smf\b/g }, "$t.smf", - $env->{SMF_INCLUDE_PATH}); - $env->Command(["$t.smdb.cc","$t.smdb.h","$t.snmp.cc", - "$t.ami.cc", "$t.http.cc"], "$t.smf", - q(smfgen %( %SMF_INCLUDE_OPT %) %<)); - } - } - -The subroutine above finds all names of the form <name>.smf in the -file. It will return the names even if they're found within comments, -but that's OK (the mechanism is forgiving of extra files; they're just -ignored on the assumption that the missing file will be noticed when -the program, in this example, smfgen, is actually invoked). - -[NOTE that the form C<$env-E<gt>QuickScan ...> and C<$env-E<gt>Command -...> should not be necessary, but, for some reason, is required -for this particular invocation. This appears to be a bug in Perl or -a misunderstanding on my part; this invocation style does not always -appear to be necessary.] - -Here is another way to build the same scanner. This one uses an -explicit code reference, and also (unnecessarily, in this case) reads -the whole file itself: - - sub myscan { - my(@includes); - do { - push(@includes, /\b\S*?\.smf\b/g); - } while <SCAN>; - @includes - } - -Note that the order of the loop is reversed, with the loop test at the -end. This is because the first line is already read for you. This scanner -can be attached to a source file by: - - QuickScan $env \&myscan, "$_.smf"; - -This final example, which scans a different type of input file, takes -over the file scanning rather than being called for each input line: - - $env->QuickScan( - sub { my(@includes) = (); - do { - push(@includes, $3) - if /^(#include|import)\s+(\")(.+)(\")/ && $3 - } while <SCAN>; - @includes - }, - "$idlFileName", - "$env->{CPPPATH};$BUILD/ActiveContext/ACSCLientInterfaces" - ); - -=head1 SUPPORT AND SUGGESTIONS - -Cons is maintained by the user community. To subscribe, send mail to -B<cons-discuss-request@gnu.org> with body B<subscribe>. - -Please report any suggestions through the B<cons-discuss@gnu.org> mailing -list. - -=head1 BUGS - -Sure to be some. Please report any bugs through the B<bug-cons@gnu.org> -mailing list. - -=head1 INFORMATION ABOUT CONS - -Information about CONS can be obtained from the official cons web site -B<http://www.dsmit.com/cons/> or its mirrors listed there. - -The cons maintainers can be contacted by email at -B<cons-maintainers@gnu.org> - -=head1 AUTHORS - -Originally by Bob Sidebotham. Then significantly enriched by the members -of the Cons community B<cons-discuss@gnu.org>. - -The Cons community would like to thank Ulrich Pfeifer for the original pod -documentation derived from the F<cons.html> file. Cons documentation is now -a part of the program itself. - -=cut - |