Cons FAQ

Why, when I kill Cons with ^C, does it print the following msg before exiting?

                cons: error in file "docs-spark/Conscript" (Undefined subroutine &sig::hash::END called at ./cons line XYZZY.)
        

Perl. This comes up on p5p every once in a while.

As I understand it, the problem is this: a signal can arrive between any two instructions, some signals must be at least partially dealt with at once. If perl was in the middle of an action such as malloc, it might not be safe to interrupt in the middle and then evaluate more perl code before returning to that original position. There are ideas floating around for dealing with it and lots of desire to have it dealt with, but it is not easy (not completely and correctly anyhow).

You have to give it a target, usually a directory. Try

                perl cons.pl .
        

(that's a dot at the end of the line).

Alternatively, you can use the 'Default' function to specify one or more default targets to build when no targets are specified on the command line. The following in a Construct file:

                Default '.';
        

will mimic make's behavior of building the world by default.

I tried to run the 'hello' example. My Construct is:

            $env = new cons(
                CC => 'gcc',
            );

            Program $env 'hello', 'hello.c'
        

When I type 'cons hello', I get this output:

            gcc -c hello.c -o hello.o
            gcc: installation problem, cannot exec `cpp': Invalid argument
            cons: *** [hello.o] Error 256
            cons: errors constructing hello.o
        

Which is strange, since I can *manually* type:

            gcc -c hello.c hello.o
        

and it works just fine. I am guessing my PATH or GCC_EXEC_PREFIX is getting munged by 'cons', because :

            perl -e "system 'gcc -c hello.c hello.o'"
        

works just fine too!!!

Cons does not pass the user's environment to the child processes that it forks to build the software. Anything you need or want to pass in from the user's environment must be done so explicitly. In practice, this isn't hard at all:

            $Env = new cons(
                ENV => {
                    PATH => $ENV{PATH} . ":/bin:/usr/bin",
                    USER => $ENV{USER},
                }
            );
        

Create any other, subsidiary Cons environments using $Env->clone, and everything else in your build gets the PATH that you want.

This is for purposes of repeatability, so the build won't work for me because I have some weird thing in my path (or some other weird env variable that might alter compiler behavior) and yet fail for everyone else. Cons wants you to explicity set the path to what you need it to be.

Most folks use Make this way too, for the same reason.

Yet another mechanism that I wanted to implement in CONS but failed was a build script for templates coded in different languages (locales). I have this directory structure:

            templates/
            templates/en
            templates/fr
	

where templates/ are my locale-independent templates and templates/Conscript says 'for each locale, build a locale-specific template' (but do not Install it). The individual locale's Conscript contains the Install directive.

templates/Conscript:

            @Locales = ('en','fr');
            @Sources = ('index.html');
            foreach $Locale (@Locales) {
             Command $CONS qq($Locale), join(' ',@Sources), q(localize %<);
             Build qq($Locale/Conscript);
            }
        

templates/en/Conscript:

            foreach $Source(<*.html>) {
             Install $CONS qq($BIN), qq($Source); 
            }
        

I thought that CONS will first look at templates/Conscript, run the above Command which will generate a set of files in templates/$Locale, and then Build templates/$Locale/Conscript which will Install the generated files into $BIN. This didn't work. Is there a correct/better way to accomplish this?

Cons directives (Install, Build, Command) can be moderately counter-intuitive, because they're not "executed" at the time they're processed by perl. ("Build" is especially problematic, because it doesn't actually *perform* a build of anything, it just reads up the specified subsidiary Conscript files containing build instructions...)

When the Cons directives are processed, they just set up the appropriate dependency tree and store the proper build commands for all the targets in all the Construct+Conscript files. It's not until Cons is actually trying to build the targets specified on its command line (or in the Default method) that it does any "real work" of building or installing files.

Fixing your example to generate an index.html file from an index.in file for each locale:

templates/Conscript:

            @Locales = qw(en fr);
            foreach $Locale (@Locales) {
                Build qq($Locale/Conscript);
            }

        templates/en/Conscript:

            @Inputs = qw(index.in);
            foreach $Source (@Inputs) {
                ($target = $Source) =~ s/\.in$/.html/; # index.in => index.html
                Command $CONS qq($target), qq($Source), q(localize %<);
                Install $CONS qq($BIN), qq($target);
            }
        

Cons will use MD5 signatures for files outside the local build directory. The catch is that Cons does not, by default, search the standard directories for adding a file to its signature calculation. The search directories must be explicitly specified via CPPPATH or LIBPATH.

With CPPPATH explicitly specified like so:

	  $env = new cons ( CPPPATH => '/usr/include:.' );
	

You get the expected behavior:

	  % cons .
	  cc -I/usr/include -I. -c foo.c -o foo.o
	  cc -o foo foo.o
	  % cons .
	  cons: "." is up-to-date.
	  % su
	  Password:
	  # vi /usr/include/stdio.h
	  # exit
	  % cons .
	  cc -I/usr/include -I. -c foo.c -o foo.o
	  cc -o foo foo.o
	  %
	

No. You could put all of the information about your entire directory tree in one top-level Construct file that uses relative path names for all file references. In practice, though, most people find it a lot more convenient to list the source files and build rules for a given subdirectory's constructions in that subdirectory. Your mileage may vary.

Make the target of the Command be a reference to an array containing a list of the targets being built. This is most commonly done by enclosing the list in [square brackets].

In order, for a common example, to build target foo.class and bar.class files from a single invocation of the Java compiler on the input foo.java and bar.java files:

            @sources = qw(foo.java bar.java);
            @targets = qw(foo.class bar.class);
            Command $CONS [@targets], @sources, q(javac %<);
        

The Command directive can take a reference to an array in this way in all versions of Cons back to 1.3.1. Beginning with version 2.2.0, the Depends directive can also take references to an array in this way.

Or, if you have more targets produced from a given set of sources... say, foo.java and bar.java producing foo.class bar.class and baz.class... then this would work for you...

            @sources = qw(foo bar);
            @targets = qw(foo bar baz);

            CompileJava $CONS [@targets], [@sources];

            sub cons::CompileJava {
               my($cons, $tgt, $src) = @_;
               $cons->Command([map(("$_.class"), @$tgt)], map(("$_.java"), @$src),
                   q(javac %< ));
            }
        

You need different environments specifying what CC is for each compiler:

            $CONS = new cons();

            # GNU C build environment
            $CONS_GCC = clone $CONS(
                    CC               => "gcc",
            );

            # Microsoft Visual C build environment
            $CONS_MSVC = clone $CONS(
                    CC               => "cl",
            );

            Library $CONS_GCC "mylib.a", qw(a.c b.c c.c);
            Library $CONS_MSVC "mylib.a", qw(x.c y.c z.c);
        

During one call to cons, we would like to build two versions of a single set of source. We need to direct one source directory to two destinations, since we have to have different object files. We found it a real hassle having to update two sets of very similar sources in separate directories and decided to fold them together and use preprocessor directives to control the compilation.

I didn't find a simple way to do that. Instead, I just created a second set of source files (.cpp) in the same directory as the first, with different names. These source files simply #include their counterpart.

Any cleaner solutions?

Well, in one of the projects at FORE, we build an embedded OS and the boot monitor (bootrom) mostly from the same set of sources.

In another project, we build the exact same sources for a variety of platforms like sunos5, irix6, and other flavors of unix.

In the first case, we need to build both as cross-compiled targets on the same host platform.

In the second case, we will always compile the sources only for the target platform on itself.

The second case is easier compared to the first, so I'll give you an idea of how we approached the first one.

I can't cut and paste the Conscripts here due to the copyrights in them, but I can given you an idea of what you can do.

           # Trees
           $src = "#src";
           $build = "#build";

           $variant1 = "$build/var1";
           $variant2 = "$build/var2";

           Link $build => $src;

           # cons object for variant1
           $cons1 = new cons(CFLAGS => '-DVARIANT1');

           # cons object for variant2
           $cons2 = new cons(CFLAGS => '-DVARIANT2');

           # common sources
           @srcs = qw(a.c b.c c.c)

           # variant1 sources
           @var1src = qw(d.c)

           # variant2 sources
           @var2src = qw(e.c)

           # First Variant of Program `prog' 

           Install $cons1 $variant1, map("$src/$_", @srcs, @var1src);
           Program $cons1 "$variant1/prog", map("$variant1/$_", @srcs, @var1src);

           # Second Variant of Program `prog' 

           Install $cons2 $variant2, map("$src/$_", @srcs, @var2src);
           Program $cons2 "$variant2/prog", map("$variant2/$_", @srcs, @var2src);
        

So, you'll find the final program in variant1 style in build/variant1/prog and in variant2 style in build/variant2/prog

The second case is much easier since you need to just change your build tree to be dependent on the OS.

             chomp ($ostype = `uname`);

             $build = "#build/$ostype";

             Link $build => $src;
        

The Link directive can do exactly this when used with multiple build environments. One way is to define multiple Cons environments with different CFLAGS, and then Link+Build the subsidiary program with each environment in turn:

            $ cat Construct
            my $build1 = new cons ( CFLAGS  => '-DVERSION=1' );

            my $build2 = new cons ( CFLAGS  => '-DVERSION=2' );

            $Env = $build1;
            Export qw( Env );
            Link 'build1' => 'src';
            Build 'build1/Conscript';

            $Env = $build2;
            Export qw( Env );
            Link 'build2' => 'src';
            Build 'build2/Conscript';
            $
        

You need to assign each build environment to $Env in turn because that's the environment that the subsidiary 'src' directory's Conscript file is expecting to Import:

            $ cat src/Conscript
            # src/Conscript

            Import qw( Env );

            Program  $Env 'foo', 'foo.c';
            $
        

Because the src directory is Linked twice, once each with the separate build environments, it gets "called" with a different -DVERSION option in each subdirectory. Then, the common .c file uses normal #if/#ifdef to figure out which VERSION is needed:

            $ cat src/foo.c
            /*
             * src/foo.c
             */

            main()
            {
            #if VERSION == 1
                    printf("This is version 1\n");
            #elif VERSION == 2
                    printf("This is version 2\n");
            #else
            #error Must -DVERSION=1 or -DVERSION=2 when compiling!
            #endif
            }
        

Put it all together, and the build looks like this:

            $ cons . 
            cc -DVERSION=1 -c build1/foo.c -o build1/foo.o
            cc -o build1/foo build1/foo.o
            cc -DVERSION=2 -c build2/foo.c -o build2/foo.o
            cc -o build2/foo build2/foo.o
            $ build1/foo
            This is version 1
            $ build2/foo
            This is version 2
            $ 
        

Another variation on this theme would have separate build1/Conscript and build2/Conscript files, each defining their own environment and Linking to the top-level src directory. This is easier to manage if there is a large number of different build environment (or if the environments themselves are complicated).

Upgrade to Cons 2.0 or later and use "../" to ascend the directory tree as you'd expect. (Prior to version 2.0, Cons didn't know how to build things above its top-level directory without some messy workarounds.)

If I build object files spread out in multiple directories, each generated by a separate Conscript file, how can I link them all together into another relocatable module?

In each Conscript file, include a LinkedModule directive, similar to:

            LinkedModule $ENV "#lib/combined.o", qw (
                source1.c
                source2.c
                object1.o
            );
        

The list of files will be different in each Conscript file, but cons will basically combine all of these lists together to create the final lib/combined.o file.

It seems that modifying an environment in cons is a no-no. Any other environments copied or cloned from the original won't have the modifications.

	  $e1 = new cons(VAR => 'abc');
	  $e1->{VAR} = "xyz";
	  print $e1->{VAR}.", ";
	  $e2 = $e1->clone();
	  print $e2->{VAR}."\n";
	

This prints xyz, abc.

I'd like to, when setting up my environments, set up the base env to 'approximately' the right settings, then tweak it depending on various conditions. This says I can't do that.

Construction environment variables are "frozen" when the environment is created. The way to create a modified environment from a template would be to supply the desired modifications as arguments to the clone() method:

	  $e1 = new cons(VAR => 'abc');
	  $e2 = $e1->clone(VAR => 'xyz');
	

Import and Export arrange for Perl scalar values to be shared between Construct and Conscript files. There are several ways you can use them to pass information.

First, you could put the desired values directly in Perl scalars that can each be Exported/Imported independently:

	  Construct:
	      $CONS = new cons;
	      $INCLUDE = $ENV{INCLUDE} || '/usr/include';
	      Export qw(CONS INCLUDE);
	      Build 'Conscript';
	  Conscript:
	      Import qw(CONS INCLUDE);
	      Depends $CONS 'output', "$INCLUDE/file1", "$INCLUDE/file2";
	

This approach is straightforward but has two drawbacks:

1) Any time you want to pass more information, you have to add more variables to the Import and Export lists in the various Construct and Conscript files.

2) $INCLUDE is a normal Perl scalar and must be expanded to generate the proper path names. Consequently, you can't use Perl operators like qw() which don't expand variables (no "qw($INCLUDE/file1 $INCLUDE/file2)").

A more natural Cons approach would be to put these variables in the Cons environment, and then use Cons' construction-variable expansion (with a % prefix) to extract the values from the construction environment:

	  Construct:
	      $CONS = new cons(INCLUDE => $ENV{INCLUDE} || '/usr/include');
	      Export qw(CONS);
	      Build 'Conscript';
	  Conscript:
	      Import qw(CONS);
	      Depends $CONS 'output', qw(%INCLUDE/file1 %INCLUDE/file2);
	

This eliminates the need to pass additional scalars directly through Export and Import.

I have the following command:

            Command $env ("$BIN/license.txt", "license.txt",
                          "test -e %> || cp %< %>");
        

The intended result is "replace this file only if it doesn't exist at all in $BIN." But of course it doesn't work, because cons deletes the target before it runs my command, so it always does the copy. Bummer.

Is there a way, short of a fake target that always runs, to do this?

(BTW, what I *really* want is for it only to do the cp if %< is newer than %>, any idea how to do that? Anyway, the existence test is good enough for my application.)

Assuming that license.txt is not a derived file, then would this do?

            system("cp license.txt $BIN") unless -e "$BIN/license.txt";
        

If license.txt is derived, then this won't do, since it will be done too soon (before the derivation of the file).

I'm looking for a way to replace files in an existing library using cons. i.e. I have some library 'libfoo.a' containing 'bar.o' and 'baz.o'. I want to build my own version of 'bar.o' from 'bar.c' and then build a new 'libfoo.a' with the new 'bar.o' and the old 'baz.o'.

Is there any easy way to accomplish this? The only way I've come up with so far (I haven't tried it, and it will be a hack regardless) is to extract all of the objects from the existing library and then repackage the whole thing, because cons wants to delete the existing library before it rebuilds it rather than just replacing the files.

As of Cons 2.0, you can prevent the library (target file) from being removed before being rebuilt by using the Precious method:

	  Library $CONS "libfoo.a", @objects;
	  Precious "libfoo.a";
	

On most systems (Solaris, Irix at least) it is faster (sometimes by a lot) to rebuild the archive from the .o files than to replace ones in the middle.

The Library method is hard-wired to generate non-shared libraries (.a files). How can I build shared libraries (.sl files)?

As a quick-and-dirty approach, you can use the Program method to build a shared library directly by setting appropriate values for CFLAGS, LINK and LDFLAGS:

            $slenv = $env->clone(CFLAGS => '-fPIC',
                                 LINK => 'gcc',
                                 LDFLAGS => '-shared'); 

            Program $slenv "mydll.sl" "file1.o", "file2.o", ...;
        

Try adding the function below to your Construct. Use just like Library. You must do the following to use it:

        - Set LINK,LDFLAGS, etc. in your slenv environment to include
          '-shared' as above.
        - Set SUFSHLIB to '.sl'
        - Set SUFLIBS to '.sl:.a' so the shared lib will be found as a
          dependency by your program.  This will solve the problem you are
          having, assuming you are using -lmydll to link with your lib.

        ########################################################################
        # SharedLibrary
        ########################################################################
        # Usage: just like Library, but builds a shared lib.  User must set
        # CFLAGS,LINK,LDFLAGS etc. to proper options for building a shared lib.
        sub cons::SharedLibrary {
            my($env) = shift;
            my($lib) = $dir::cwd->lookup(file::addsuffix(shift, $env->{SUFSHLIB}));
            my($libenv) = $env->_resolve($lib);
            $lib->bind(find build::command::link($libenv, $libenv->{LINKCOM}),
                       $env->_Objects(map($dir::cwd->lookup($_), @_)));
        }
        

I try to set up a build environment where several architectures are built in parallel, but certain targets (for example C files generated by yacc) should be shared between all architectures.

When I try to do this, however, cons always rebuilds the shared targets. I found the reason is that cons includes the build command's time stamp into the target file signature, i.e. if you have a target like

            Command $CONS "y.tab.c", "a.y", "yacc a.y";
        

The signature of y.tab.c contains the command name "yacc" (without path) and the modification time of /usr/bin/yacc, /usr/ccs/bin/yacc or wherever yacc resides. In general, this is probably an advantage, because it forces a rebuild whenever new compiler versions are installed.

Any ideas how to address this problem? One could wrap a simple perl or shell script around yacc. With the script belonging to the source code, the modification time of the script would be the same for all archi- tectures. But this is not exceptionally elegant ...

            Ignore "/yacc\$";
        

But if you ever upgrade yacc, y.tab.c will not get rebuilt automatically.

You might be better off by simply rebuilding y.tab.c for each platform, rather than trying to share it among all platforms.

Another possibility is to create "fake" .consign files in the directories where yacc lives, and give every copy of yacc the exact same checksum.

I'm working on a Construct file which I am trying to set up for multiple compilers and environments.

One of the compilers assumes that objects have a '.obj' ending, not '.o', and it tries to compile '.o' files. Needless to say, this is undesirable :-)

Is there some way to inform cons that the default object extension should be obj?

Within the cons environment, re-define SUFOBJ:

            $ENV = new cons(
                ...
                SUFOBJ       => '.o',
                ...
            );
        

When using third-party stuff from a repository, you only need to change the #include "..." lines if you're going to make your own modifications to any included (.h) file. If you're going to leave it shrink-wrapped, then you can leave the quotes alone and it should pick up everything from the repository just fine.

This loses only if you want to (or must) use a more-recently-modified local .h file instead of what's in the repository. The C preprocessor will see the #include "..." and always use the repository copy, no matter what Cons does with -I flags to try to get it to use the local one.

Derive a new $env with the correct added line. Newlines separate commands in cons so this should work. Here's a working Construct:

	  $env = new cons();
	  $regenv = $env->clone(LINKCOM => $env->{LINKCOM} . "\necho done!!!\n");
	  Program $regenv 'hello', 'hello.c';
	

It outputs this:

	  % cons hello
	  cc -c hello.c -o hello.o
	  cc -o hello hello.o
	  echo done!!!
	  done!!!
	

I'm trying to use Cons to build programs on several different platforms (Solaris, HP-UX, Linux, NT at least).

I was somewhat surprised that that the following could happen:

            hpux% cons hello
            cc -c hello.c -o hello.o
            cc -o hello hello.o
            hpux%
            hpux% rlogin solaris
            solaris%
            solaris% cons hello
            cons: "hello" is up-to-date.
        

Shouldn't the "platform" be part of the signatures in some way?

I would prefer that it isn't. We do cross-compiles for the same target machine on several different host machine architectures. Having the platform NOT be part of the signature means we can start a build under Solaris and re-compile just the changes on a Linux box without rebuilding the whole system.

Is there some simple way I can accomplish this myself?

You can accomplish this yourself by adding a "Salt" statement to your Construct file, similar to the following:

            $host_type = `uname -s`;
            Salt($host_type);
        

You can use whatever you want to use to distinguish your build platforms as an argument to Salt.

I'm trying to use Cons to build programs on several different platforms (Solaris, HP-UX, Linux, NT at least).

I was somewhat surprised that that the following could happen:

On HPUX I have two different compilers named "cc", one in /usr/bin and one in /usr/ccs/bin. If I change my Construct file to

            %env = new cons()->copy();
            $env{CC} = "cc";
            $env{ENV}{PATH} = "/usr/local/bin:/bin:/usr/bin";
            $env = new cons(%env);
        

then build hello, and then later change Construct to

            %env = new cons()->copy();
            $env{CC} = "cc";
            $env{ENV}{PATH} = "/usr/ccs/bin:/usr/local/bin:/bin:/usr/bin";
            $env = new cons(%env);
        

then cons still thinks hello is up-to-date.

Shouldn't the actual path to "cc" used in the command be part of the signature, insead of just "cc" as I suspect it is now?

Perhaps. The dependency analysis for ".o" files could be modified so that it also depends upon the compiler executable file as well as the source files. I would rather have it implemented in this manner, rather than simply going by the file path.

For now, you could simply use $env{ENV}{PATH} as part of the argument to the Salt command.

Yes, as of Cons 2.0, Windows NT absolute path names can be specified either with volume letters (c:\msvc42\include) or as a UNC path (\\share\include).

(Prior to version 2.0, Cons required a counter-intuitive work-around of beginning volume-letter absolute path names with a '#' to avoid some internal processing.)

How can you specify an absolute path name in NT in CPPPATH. I want CPPPATH to have something like v:\msvc42\include in it.

I can't put the colon in there because that is the delimiter that CONS uses in the CPPPATH. But if I don't put it in there then CONS does something like

                cl /I\v\msvc42\include
        

which doesn't work either.

In Cons version 1.4a2, you can make CPPPATH be an array reference:

                CPPPATH => [ "#v:\msvc42\include", "another directory", ... ]
        

This is now the preferred way to specify a path; the old way is deprecated.

I have a problem in NT because of the odd case-insensitivity of NT. If I have one .c file that '#includes "abc.h"' and another that '#include "ABC.H"', they are really including the same file (assuming the same directory or include path, etc.). NT remembers the case that was used to create the file so the filename might be "abc.H", or "Abc.h", whatever, but the name is case insensitive because no matter what case you use to open the file, it will work.

But cons treats them as different. The real problem is where "abc.h" is generated or "Installed" into the location where the compiler will find it. The file is not created in time and/or it is deleted (i.e. unlinked from the Link directory).

When scanning .c files for #includes, if I change all the include file names to lower case, then things behave as expected.

It seems that some sort of change to recognize case insensitivity would be a useful change for NT.

It'd be best, however, to change the directory and file handling modules to generically convert all file names to lower case.

Cons has a lot of hard-wired knowledge about building linking object files and executable files from C code. Are there suffix rules for different kinds of source files, like make does?

As long as you're willing to explicitly list all the targets to which your suffix rule will apply, you can use the following in your Construct:

                sub cons::SufRule
                {
                  my($env, $frsuf, $tosuf, @srcs) = @_;
                  my($rule) = pop @srcs;
                  foreach (@srcs) {
                    s/$frsuf$// || next;
                    Command $env "$_$tosuf", "$_$frsuf", $rule;
                  }
                }
        

Then your Conscript can do things like so:

                $CONS = new cons;

                SufRule $CONS ".pl" => ".c", @INIT, '%PERL %< > %>';
        

which allows a bunch of C files to be generated from perl scripts, or

                SufRule {$CONS->clone(CFLAGS => "-dD -E")} ".c" => ".i", @SRCS,
                        '%CCCOM';
        

which builds preprocessed versions of C files when I ask for them.