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 XXX.)
        

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 qw(
                        .
                );
        

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); 
            }
        

templates/en/Conscript: 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 storing 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);
            }
        

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 %<);
        

As of version 1.8, only the Command directive can take a reference 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 %< ));
            }
        

For C, you need a different environment for each specifying what CC is:

            # C build environment
            $CONS = new cons();

            $CONS_C = clone $CONS(
                    CC               => "gcc",
                    CPPPATH          => $my_cpppath,
            );

            # C++ build environment
            $CONS_CPP = clone $CONS(
                    CC               => "gcc -x c++",
                    CPPPATH          => $my_cplusplus_cpppath,
            );

            @c_sources = qw(a.c b.c c.c);

            @cpp_sources = qw(a.cc b.cc c.cc);

            Library $CONS_C "mylib.a", @c_sources;
            Library $CONS_CPP "mylib.a", @cpp_sources;
        

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.

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 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.

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 diffeent 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} = "ccc";
            $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} = "ccc";
            $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.

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.

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

This is a problem in general though with cons, in that it always deletes the target before running the command even if that's not what you'd like.

To answer my own question... Does anyone see any problems with this approach?

            Command $CONS "libfoo.a", (
                    "/path/to/original/libfoo.a",
                    Objects $CONS "bar.c",
                ),  
                "cp %1 %>; %AR r %> %<; %RANLIB %>";
        

It seems to be doing exactly what I want it to do. :) a little messy maybe, but less so than trying to extract and re-archive everything.

This is definitely the best approach, IMO. What this does is explicitly recognize that you have a source (the original archive) and a separate target. If you try to make the source and the target the same thing, the Cons model doesn't work. For example, if we added an option to Cons to tell it to not remove files, you still have a circular dependency: the signature of the derived file depends on the files that go into it. But in this case, your derived file depends upon the derived file itself. So it would force a re-derivation the next time...

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',
                ...
            );
        

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.

(BTW, there's a bug (or feature, if you will), currently, in that you have to specify files with drive letters as top-relative names, by starting them with a "#").

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.