cons in STAR

• What is cons ?
• Why cons ?
• Where can you get help on cons?
  • Online help
  • Man pages
• How to run cons
  • Full build
  • Partial build
  • Tables build
  • Quiet build
  • Install includes only
  • Clean up
  • Clean up soft links
  • Track dependencies
  • Overwrite parameters
• Perl scripts
  • Construct
  • Conscript
• What problems show up with CPP path
• Where can you get cons?

What is cons

• cons is a replacement for make. It is not compatible with make, but it has a number of powerful capabilities not found in other software construction systems, including make.
• 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 scope of variables is replaced with an import/export mechanism for sharing information between scripts, significantly improving the readability and maintainability of each script
• cons is known to work on a variety of platforms. It's in production use on versions of Free BSD, Linux, Solaris, NT, SunOS, HPUX, AIX, and IRIX.

Why cons ?

• Build complexity
  • make is good when you have codes in one directories.
  • It became quite complicated to make consistent build when, for example, share library depends on archive library in other directory. cons can handle this.
• Build reproducibility
  • make relies on simple time stamp when it follows dependencies. It does not check how targets are built. With any target built it keeps track on version of script, executables and command line which has been used to build it.
• Variant builds: allows, for example, switch between debug non debug version from cons command line
  (see construction [name]=[val] in online help)
• Repositories --- in our case to work using standard build in STAR library i.e. handle include path, repositories built targets and so on (see cons man pages)
• Perl versus makefile.
  • cons itself has 1.2k lines of Perl + 3.8k lines of documentation.
  • Standard Construct + standard Conscript together have ~600 lines of codes which can be compared with ~4.5 locs of Makefiles used for maintaining STAR library.
• maintainability: More people (and a growing number in STAR) understand Perl than complicated makefiles
• Flexibility. The scheme with Conscript file which can reside in the local directory and which can have local --- non standard build.
• cons is extendable.
  • Limited functionality (c only) which basic version of cons has can be extended (+Fortran, c++, Mortran, stic,…)
• Speed: cons works from 1.5 to 2 times faster than make (1.5 : to build everything from scratch; 2: to check that everything has been built).

Where can you get help on cons?

Man pages

• man cons, or
• perldoc `which cons`
• FAQ

Usage: cons  -- 

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.

  -g            Enable Construct/Conscript debug print out

  -f [file]     Use the specified file instead of "Construct" (but first
                change to containing directory of [file]).

  -i            Don\'t force to search for include file in default include directory
  -lh           Show a help message local to the current build if
                one such is defined,  and exit.

  -o [file]     Read override file [file].

  -k            Keep going as far as possible after errors.

  -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 about Installing and Removing targets.

  -wf [file]    Write all filenames considered into [file].

  -r            Remove construction products associated with [targets]

  -R [repos]    Search for files in [repos].  Multiple -R [repos]
                directories are searched in the order specified.

  -noR          Do not search for files in repositories.

  -v            Show cons version and continue processing.
  -V            Show cons version and exit.
  -x            Show this message and exit.
  -h            Show this message and exit.

   Please report any bugs/fixes/suggestions through the
   cons-discuss@eng.fore.com mailing list. To subscribe, send mail to
   cons-discuss-request@eng.fore.com with body 'subscribe'.

   User documentation of cons is contained in cons and can be obtained
   by doing 'perldoc /path/to/cons'.

   The Official cons site is: http://www.dsmit.com/cons/

How to run cons

Full build

In top level directory (which contains pams or/and StRoot) type

cons .
        or simply 
cons
        ("." is default target)

Partial build

  +[pattern]    Limit the cons scripts considered to just those that
                match [pattern]. Multiple + arguments are accepted.
    Thus 

cons +tpc 

    will be executed for tpc and ftpc directories.

Table build

Quiet build

Install includes only

Track dependencies

.....
Run Conscript-standard in StRoot/St_TLA_Maker             for St_TLA_Maker        
...
.sun4x_56/lib/St_TLA_Maker.so
  .sun4x_56/obj/StRoot/St_TLA_Maker/St_TLA_Maker.so
    .sun4x_56/obj/StRoot/St_TLA_Maker/St_TLA_Maker.o
      .sun4x_56/obj/StRoot/St_TLA_Maker/St_TLA_Maker.cxx
      include/St_DataSetIter.h
        StRoot/St_base/St_DataSetIter.h
      include/St_DataSet.h
        StRoot/St_base/St_DataSet.h
      /afs/rhic/star/ROOT/2.23/ROOT/src/TNode.h
      /afs/rhic/star/ROOT/2.23/ROOT/src/TRotMatrix.h
      /afs/rhic/star/ROOT/2.23/ROOT/src/TNamed.h
      /afs/rhic/star/ROOT/2.23/ROOT/src/TString.h
      /afs/rhic/star/ROOT/2.23/ROOT/src/TRefCnt.h
      /afs/rhic/star/ROOT/2.23/ROOT/src/Rtypes.h
      /afs/rhic/star/ROOT/2.23/ROOT/src/DllImport.h
      /afs/rhic/star/ROOT/2.23/ROOT/src/RConfig.h
      /afs/rhic/star/ROOT/2.23/ROOT/src/RVersion.h
      /afs/rhic/star/ROOT/2.23/ROOT/src/TMath.h
      /afs/rhic/star/ROOT/2.23/ROOT/src/TList.h
...

Remove products

Clean up soft links

cons is using soft links. The trouble with soft link that they still exist when you have deleted original files.
To clean up these links you should add one more parameters in cons

cons LinksCheck=YES

Overwrite parameters

The following list of parameters can be overwritten from cons command line :
cons parameter=value

• NODEBUG=yes, set debug flag to -O2 (default -g);
• DEBUG=value, set debug flag to "value";
• CPPFLAGS=value;
• CPP=value;
• CC=value;
• CCFLAGS=value;
• CLIBS=value;
• CXX=value;
• CXXFLAGS=value;
• FC=value;
• FFLAGS=value;
• FLIBS=value;
• LD=value;
• LDFLAGS=value;
• EXEFLAGS=value;
• Libraries=value;
• LIBS=value;
• LIBPATH=value;
• SO=value;
• SOFLAGS=value;
• Salt=value, add to target signature "value".

Perl scripts

cons is Perl-based. That is cons scripts:

• Construct and
• Conscript

files, the equivalent to makefiles -- are all written in Perl.
Build of directory tree is organized by creating a hierarchy of build scripts. 
At the top of the tree is a script called Construct. 
The rest of the scripts, by convention, are each called Conscript. 
These scripts are connected together, very simply, by the Build, Export, and Import commands.
      
      
Construct

      
#!/opt/star/bin/perl
use Env;
...
$_ = $STAR_HOST_SYS;
print "System: ", $_,"\n" unless ($param::quiet);
if (/^i386_/) {
$OSFID    = "lnx Linux linux LINUX CERNLIB_LINUX CERNLIB_UNIX CERNLIB_LNX CERNLIB_QMLNX NEW_ARRAY_ON GNU_GCC ST_NO_NUMERIC_LIMITS ST_NO_EXCEPTIONS ST_NO_NAMESPACES";
  $CXXFLAGS = "-fPIC -Wall";
$CFLAGS   = "-fPIC -Wall";
  $CPPFLAGS.= "f2cFortran";
  $LDFLAGS  = "-Wl,-Bstatic";
  $EXEFLAGS = $CXXFLAGS . " -Wl,-Bdynamic";
  $SOFLAGS  = "-shared";  
  $CLIBS    = "-L/usr/pgi/linux86/lib -L/usr/X11R6/lib  -lXt -lXpm -lX11  -lpgc -lm -ldl  -rdynamic";
...
}
else {
...
}
..
env = new cons(
		'CPPPATH'      => $CPPPATH,
		'CPPFLAGS'     => $CPPFLAGS,
		'DEBUG'        => $DEBUG,
		'FC'	       => $FC,
		'FFLAGS'       => $FFLAGS,
		'FEXTEND'      => $FEXTEND,
		'FCPPPATH'     => $FCPPPATH,
		'Fout'         => $Fout,
...
		'ENV'	        => { 'PATH' => $PATH,
				     'STAR' => $STAR,
				     'CERN_ROOT' => $CERN_ROOT,
				     'STAF' => $STAF,
				     'STAR_BIN' => $STAR_BIN,
				     'STAR_SYS' => $STAR_HOST_SYS
				   },
	       );
Export qw( env INCLUDE LIB BIN EXPORT BUILD OBJ);
Build  @Targets;


Conscript

 Import qw ( env INCLUDE LIB BIN  EXPORT BUILD OBJ);
(my $build = $OBJ) =~ s/\#//g;
$build =~ s/\\/\//g;  # Account NT
(my $ObjDir = DirPath '.') =~ s/\\/\//g;
(my $Dir = $ObjDir) =~ s/$build\///g; 
my $pkg  = basename($Dir);
...
my @src     = qw (CorrFctn/MinvCorrFctn.cxx
		  CorrFctn/OpeningAngleCorrFctn.cxx
		  CorrFctn/QinvCorrFctn.cxx
		  CorrFctn/QvecCorrFctn.cxx
		  CorrFctn/ExitSepCorrFctn.cxx
                    …
                  ); 
my $SO_PKG = $pkg . "." . $env->{SUFSOLIB}
LinkedModule $env2 $SO_PKG, @src;
Install $env2 $LIB, $SO_PKG;

      

      
What problems show up with C Ppreprocessor include path
      

 The most often problem shows up when cons complains that it does know how to build
include file like this:
cons: don't know how to construct "include/tables/St_gen_header_Table.h"

To track down from which source code you get this complain just debug dependencies:
cons -d +StEventMaker
...
.i386_redhat51/lib/StEventMaker.so
  .i386_redhat51/obj/StRoot/StEventMaker/StEventMaker.so
    .i386_redhat51/obj/StRoot/StEventMaker/StEventMaker.o
      .i386_redhat51/obj/StRoot/StEventMaker/StEventMaker.cxx
      /afs/rhic/star/packages/StAF/SL99g/inc/fortranc.h
      .i386_redhat51/obj/StRoot/StEventMaker/StEventManager.hh
      include/tables/St_gen_header_Table.h
cons: don't know how to construct "include/tables/St_gen_header_Table.h"

The problem is due to the requirement that for all non system include files, i.e.
files which includes using double quoted string 

("string",instead of < string > for system header files) 

cons has to know where to find this include files) or how to construct it. 
Right now in STAR library only three directories 
exported as C Preprocessor include path:
	

	  
 include,
	  
 StRoot, and
	  
 the current directory which contains the compiling source file 
	
The include files from the following directories are installed in include directory:

   
idl,inc,include --- mainly these are PAM tables idl-files and PAM inc files
   
PAM include files generated from PAM idl-files
   
header files from STAR Utilities:
      

          
St_base 
	  
StChain 
	  
StBFChain 
	  
StUtilities 
	  
StAnalysisUtilities 
	  
xdf2root 
	  
StarClassLibrary 
	  
StEvent 
          
StEventUtilities
	  
StMcEvent 
      

Wrappers header files for Tables and PAMs are installed in
     

        
 include/tables, and
        
 include/'Domain Name'
     
directories, respectively. 
      
      
Where can you get cons? 
      
      

	
The latest stable version of CONS is 1.6b1
	
You will need Perl 5.002 or better and the Perl MD5 Extension, available from CPAN. 
	
The version of cons (1.6b1) + necessary extension (Fortran, Mortran, C++,…) 
	  installed under $STAR/mgr
	
There is a test suit for cons which can be found in $STAR/mgr/cons-test
      


      
Yuri Fisyak


Last modified: Fri Jan 21 10:36:00 EST 2000