
          Document Title: tools_build.txt

                 Subject: Building the SPEC CPU2000 Tool Suite

            Last updated: 16 Dec 1999 9:33am jh
                          (To check for possible updates to this document,
                          please see http://www.spec.org/osg/cpu2000 ) 

------------------------------------------------------------------------



          Contents
          --------
             Introduction
             Pre-supplied binaries
             When to build the tools yourself
             How to build the tools
             Notes specific to Unix systems
             Notes specific to NT systems
             How to verify that your build succeeded
             Packagetools
             What to do if something goes wrong
             Executing just part of buildtools




Introduction
------------

SPEC supplies various tools that are used to ensure consistent operation 
of benchmarks across a variety of platforms.  In order to generate a 
valid rawfile which will be submitted to SPEC, you must use the SPEC
supplied tools.

The tools include (but are not limited to):

     specmake    - gnu make (Calling it "specmake" avoids possible conflicts 
                   with versions of make that may already be on your system.  
		   SPEC requests that you use the versions of the tools that 
		   it supplies, so that if SPEC applies patches or extensions
		   from time to time, all users run with a consistent tool
		   set.  Similar considerations apply to other tools in 
		   this list.)
     specgzip    - gzip      
     spectar     - gnu tar   
     specperl    - perl 
     specdiff    - examines results to see if the correct answer was obtained
     specinvoke  - invokes benchmarks for CPU2000     
     Various perl modules, such as IO, GD, Digest-MD5, Compress-Zlib, 
         MIME-Base64, HTML-Parser, URI, etc

Many of these tools are based on the freely available program of the 
same name.  


Pre-supplied binaries
---------------------

You will find pre-compiled binaries for the tools in the directories:

    $SPEC/tools/bin/<archname>

The term $SPEC designates the top directory where you installed
the benchmark suite.  (On an NT system, it would be called %SPEC%.)

The precompiled binaries will be automatically installed when you
run:

    install.sh (Unix) or 
    install.bat (NT)


When to build the tools yourself
--------------------------------

Sometimes it may be necessary to rebuild the tools, for example if a
change in an operating system renders a precompiled binary inoperable,
or if you are the first person to add support for a new architecture.

   NOTICE: If you are adding support for a new architecture, and intend
   to submit results to SPEC, you should ask SPEC to review
   your tool build.  Please turn on your operating system's session
   recorder (e.g. in Unix, typically the 'script' command) prior to
   doing buildtools.  


How to build the tools
----------------------

The scripts:
  
      $SPEC/tools/src/buildtools     (Unix)
      %SPEC%\tools\src\buildtools.bat (NT)

will build the tools.  But you may need to invoke the buildtools script
with appropriate environment variables set first - see the sections
immediately following that provide notes about specific platforms.

If everything goes right, you won't have to do very much at all, other
than watch build commands fly by.  

                            
Notes specific to Unix systems
------------------------------

When building the tools under Unix, the following warnings appear 
to be harmless as of February 1999:

   - Any message generated by a "make clean", especially the first time
     that you build, since there's nothing to clean!

   - Warnings about missing 'makeinfo', 'alocal', 'automake', 'autoconf'.

You may find the following flags useful on the listed systems:

  AIX: 
    CC=cc CFLAGS='-O' PERLFLAGS="-Doptimize='-O'" ./buildtools

  HPUX:
    INSTALL=$PWD/tar-1.12/install-sh CC="/opt/ansic/bin/cc" \
       CFLAGS="-Ae +O2 +Olibcalls +z" ./buildtools

  Siemens:
    Some of the builds may want to run 'ranlib' on their libraries, and at
    least some versions of Reliant Unix don't supply it.  If you find that
    to be the case, there's a shell script in $SPEC/tools/src/bin called
    'ranlib.siemens'.  Copy that to a directory in your path, and call it
    'ranlib', and all should be well.
    Use the following commands to build the tools:
	LD_LIBRARY_PATH=$SPEC/tools/src:$LD_LIBRARY_PATH
	export LD_LIBRARY_PATH
	CFLAGS='-O -D_XPG_IV' PERLFLAGS='-Duseposix=undef' ./buildtools

  Tru64 Unix (Alpha):
    You may find gzip confused about the definition of basename.
    This problem is avoided by doing the following (in csh):
        % setenv CC "cc -std0"
        % buildtools
    Or in an sh-compatible shell:
        $ CC="cc -std0" ./buildtools


Notes specific to NT systems
----------------------------

When building the tools under NT, before doing anything else, start by
checking:

     %SPEC%\tools\src\make-3.77\NMakefile

to see whether there is a value supplied for /MACHINE.  The original
gnu make distribution sets /MACHINE:I386.  As of early May, 1999, 
this switch now appears to be superfluous and will probably be 
removed from SPEC's version of the NMakefile.  Alternately, you can 
set it to the correct value for your architecture.  For example, on 
an Alpha system, you would say /MACHINE:ALPHA

Then go ahead and execute 

      %SPEC%\tools\src\buildtools.bat 

You will probably be asked the following question, 

   The syntax of the command is incorrect.
           rmdir /s /q .\mini || rmdir /s .\mini
   The system cannot find the file specified.
   .\mini, Are you sure (Y/N)?

The correct answer is: Y

You can ignore warnings about objects that are not found, especially 
at the beginning of each tool build, when cleanup is attempted from 
previous builds.  Some tools may not know how to make 'clean';
don't worry about it.

As of February 1999, the following compiler warnings appear to be harmless:

Make:

  differences in parameter lists, const qualifiers, 
  signed/unsigned mismatches
  LINK all references to "ADVAPI32.dll" discarded by /OPT:REF
  
gzip:

  'strlwr' : inconsistent dll linkage, parameter differences 
  different 'const' qualifiers

Tar:

  signed/unsigned mismatches
  formal parameter differences
  bison.simple undefined getdate functions

Perl:

  overriding '/MD' with '/MT'
  truncation from 'const int' to 'char'
  POSIX inconsistent dll linkage
  installhtml 'cannot resolve' messages, unknown pod directives
  

How to verify that your build succeeded
---------------------------------------

After a tool build, you should: 

     cd $SPEC (Unix) or %SPEC% (NT)

     shrc.bat (NT)
     . ./shrc (Unix, if you are in an sh-compatible shell.  
                     If not, start one!)  

     See if you can at least get as far as asking the major tools
     to identify themselves:

          runspec -V 
          specmake -v 
          specgzip -h
          specperl -v
          specdiff -h
          runspec -h 
          specinvoke -h 


Packagetools
------------

If everything has succeeded, and you intend to submit results using 
your new tools, you should submit the tools to SPEC.  To do so:

     cd $SPEC (Unix) or cd %SPEC% (NT)
     packagetools <archname>

Pick an architecture name that other users will recognize.  Check
on the CD in tools/bin for some examples.

The packagetools script will create: 

    $SPEC/tools/bin/<archname>/specgzip
    $SPEC/tools/bin/<archname>/spectar
    $SPEC/tools/bin/<archname>/<everything else>.tar.gz

Having created a large tarfile with everything but gzip and tar in it,
packagetools will then proceed to create an even larger tarfile with
specgzip and spectar it in too.  This even bigger file is known as:

    $SPEC/<archname>-<version>-tar.gz

and is to be submitted to SPEC.

You can optionally add components to your platform's toolset.  For example,
if you would like $SPEC/config/default.cfg to be set in an appropriate
way, you can add that as a parameter to packagetools.

Please submit the resulting compressed tarfile to SPEC for review, 
along with the recording of your tool build session.   SPEC will add 
the tools you have built to its patch library, for possible distribution 
to future users of your interesting new architecture.

NOTE 1: If your operating system is unable to execute the packagetools
script, please have a look at what the script does and enter the
corresponding commands by hand.  Again, you will want to submit the
results to SPEC.

NOTE 2: Be sure to test your packagetools on a different system,
preferably one with a different disk layout.  If the destination
system is unable to invoke libperl.so, check that libperl.so
exists in one of the locations where shrc expects to find it.


What to do if something goes wrong
----------------------------------

If something goes wrong, you probably do NOT want to make some
random adjustment (like: reinstall a compiler, fix an environment
variable, or adjust your path) and start all over again.  That's 
going to be painful and take a lot of your time.  Instead, you 
should temporarily abandon the buildtools script at that point
and just try to build the offending tool, until you understand
exactly why that particular tool is failing.

Turn on your operating system's logging facility.  Make a huge 
terminal window (e.g. 200 columns wide by 84 lines tall, with
9999 lines recorded off the top), so you can see what is going on.

Read what buildtools (or buildtools.bat) does for you, then cd to
tools/src/<tool> and try the commands by hand. For example, you might do
something like this:

    cd $SPEC/tools/src/<toolname>
    ./configure
    make (or build.sh or whatever you note buildtools would have done)

Now, try fixing that environment variable or reinstalling that compiler, 
and rebuild the single tool.  Does it look better?

If not, have a close look at the error messages and the Makefile.  Does
the Makefile use a feature that is not present in your version of make? 
If so, can you get it to work with gnu make?  

Try doing a web search to see if there are known problems with the 
tool on your architecture.

If SPEC supplies Version X.Y of a tool and it just won't build on
your operating system, you might check whether there is a new Version
X.Y+1 available.  If so, download the new version to a scratch 
directory outside of the SPEC tree and try building it there.  If
that version succeeds, try to deduce why.  Narrow it down to a 
one-line fix, won't you please?  Then tell SPEC that you'd like 
the same one-line fix applied to its variant of the tool.  Or, if you
just can't narrow the fix down, ask SPEC whether it will approve 
use of Version X.Y+1 instead of X.Y on your system.

Note that for GNU configure based tools (everything except PERL and its
modules) you may specify your compiler by setting the CC environment
variable. For compiler flags, set CFLAGS.

When building perl, note that:

 - If you want to force the compiler use -Dcc='yourcompiler'
 - If you want to force compiler options use -Doptimize='youroptions'

If you want to see more about what buildtools is doing for you, 
turn on your shell's verbose mode.  For example:

   sh -x ./buildtools


Executing just part of buildtools
---------------------------------

Once you believe that you understand how to fix the problem tool, and
can build it by hand, see whether the buildtools script can build it.
You can execute just a portion of buildtools by defining environment
variables.  Please read the script itself to see what variables are
allowed; the following are just some examples:

       SKIPALL - turns off everything.  If you like, set this, then
                 turn individual phases on by setting them.
       DOMAKE  - build make
       DOGZIP  - build gzip
       DOPERL  - build perl
       DOPERL2 - build perl modules
       DOCOPY  - copy the results to $SPEC/bin and fix shbangs

It doesn't matter what you set the environment variables to -- any
non-zero-length string will do.

If you are using NT, be sure to note the WARNING in buildtools.bat 
about how the variables work.

-----------------------------------------------------------------------------
Copyright (C) 1999-2000 Standard Performance Evaluation Corporation
All Rights Reserved

