     INSTALL NOTES FOR SystemC Verification Library Release 2.0.0
     ------------------------------------------------------------

Contents:

        1. Special Notes for SCV kits

        2. Installation Notes for Unix

        3. Installation Notes for Windows

1. Special Notes for SCV kits
-----------------------------

The SCV (SystemC Verification Library) installation process attempts to
follow the conventions set forth by the SystemC core library. However,
there are some cases where the SCV installation process diverges from the
conventions of the core library. In particular, the SCV example makefiles
are different from the core library makefiles.

2. Installation Notes for Unix
------------------------------

System Requirements
===================

Accellera SystemC version 2.3.1 or 2.3.0 must be installed before starting the
install process for this version of SCV. While not recommended, the old
Accellera SystemC version 2.2.0 is also supported.

SCV can be installed on the following UNIX, or UNIX-like platforms:

  o Linux
    * Architectures
      - x86 (32-bit)
      - x86_64 (64-bit)
      - x86 (32-bit) application running on x86_64 (64-bit) kernel
        (../configure --host=i686-linux-gnu)
    * Compilers
      - GNU C++ compiler
      - or compatible

  o Mac OS X
    * Architectures
      - x86 (32-bit)
      - x86_64 (64-bit)
      - powerpc (32-bit)   [deprecated]
      - powerpc64 (64-bit) [deprecated]
    * Compilers
      - GNU C++ compiler
      - Clang C++ compiler
      - or compatible

  o Solaris
    * Architectures
      - SPARC (32-bit)
    * Compilers
      - GNU C++ compiler
      - Sun/Solaris Studio

  o Windows
    * Compatibility layer
      - Cygwin [untested]
      - MinGW / MSYS
    * Architectures
      - x86 (32-bit)
      - x86_64 (64-bit)
    * Compilers
      - GNU C++ compiler
      - or compatible

Note: Not all combinations are equally well-tested and some combinations
      may not work as expected. Please report your findings by following
      the instructions in the README file.

The README file contains a list of detailed platforms, architectures,
and compiler versions that have been used for testing this release.

We recommend not compiling SCV on machines with less than 256Mb of RAM.

When using SCV with SystemC version 2.2.0 on 64-bit architectures, one has to
provide a relocatable version of the SystemC library. This is because SCV is
built as a dynamically linked library. Since this is not default in 64-bit
version of gcc, the -fPIC flag has to be added in the build process of the
SystemC library. A simple way is to add the flag directly to the compiler
call (CXXFLAGS is not supported by SystemC 2.2.0 build process). Remember
to reset the environment variable after building SystemC.

  > setenv CXX "g++ -fPIC" (csh)
  > export CXX="g++ -fPIC" (bash)


Sources for Compilers and Related Tools
=======================================

To build, install, and use SCV on UNIX platforms, you need the following tools:

  1. A supported compiler for your platform as listed in System Requirements

  2. GNU Make (gmake)

GCC and gmake are free software that you can obtain from the following sources:

  GCC           http://www.gnu.org/software/gcc/gcc.html

  gmake         http://www.gnu.org/software/make/make.html


Basic SCV Installation
==========================

To install SCV on a UNIX system, do the following steps:

  1. Change to the top level directory (scv)

  2. Create a temporary directory, e.g.,

        > mkdir objdir

  3. Change to the temporary directory, e.g.,

        > cd objdir

  4. Set the following environment variable(s):

     For gcc on Solaris:

        > setenv CXX g++
        > setenv CC gcc

     For gcc on Linux (csh):

        > setenv CXX g++
        > setenv CC gcc

     For gcc on Linux (bash):

        > export CXX=g++
        > export CC=gcc

     For Apple gcc or clang on OS X (bash):

        > export CXX=c++
        > export CC=cc

     For cross-compilation to i386, x86_64, or ppc architecture with Apple gcc
     or clang on OS X (bash):

        > export CXX="c++ -arch <i386|x86_64|ppc>"
        > export CC="cc -arch <i386|x86_64|ppc>"

        In this case, don't forget to also specify the right target architecture
        triplet (based on the output of config/config.guess, but modified to the
        chosen processor architecture) with the --target <architecture-triplet>
        to the ../configure call.

     For aCC on HP-UX:

        > setenv CXX aCC
        > setenv CC cc

     You can also specify an absolute path to the compiler of your choice.


  5. Configure the package for your system, e.g.,
     (The configure script is explained below.)

        > ../configure --with-systemc=<path_to_SystemC>

     While the 'configure' script is running, which takes a few moments, it
     prints messages to inform you of the features it is checking. It also
     detects the platform.

     If you do not specify the path to a SystemC installation, configure will
     look in ../systemc. So, if your SystemC and SCV packages are located at
     the same  root directory, you do not need to specify the --with-systemc
     option.

     If you do specify the path to a SystemC installation, use an absolute
     path (one starting with "/"), and do not use wildcards.

     Do not put spaces in around the "=" in the "--with-systemc=" option or
     in other configure options.

     If you want to install SCV using a compiler other than the ones we have
     fully tested, you will need to specify the --disable-compiler-check
     option.

     The command above instructs configure to install SCV in the same directory
     as the SystemC installation. If you want to install the package elsewhere,
     use the --prefix option, e.g. as follows:

        > ../configure --prefix=/usr/local/scv --with-systemc=/usr/local/systemc-2.3.1

     Note: make sure you have created the target directory before installing
           the package. Do _not_ use /usr/local as a prefix.

     Note for System V users:
     If you are using `csh' on an older version of System V, you might
     need to use the `sh ../configure' command instead of '../configure'.
     Otherwise, `csh' will attempt to `configure' itself.

  6. Compile the package.

        > gmake   (or gmake debug to build debug version of library)

     Some Solaris systems are unable to compile SCV with optimization enabled
     (which it is by default). If you run into trouble, try configuring again
     with the "--disable-opt" option specified on the configure command line.

  7. Install the package.

        > gmake install

     This command will copy the SCV libraries, header files, documentation, and
     examples directories into your SCV installation directory (this will be
     your SystemC installation directory unless you used --prefix, as mentioned
     in #5 above). This means that you must have write permissions into the
     SCV installation area. Once this step is successfully completed, you will
     have a complete SCV installation.

  8. At this point you may wish to verify the installation by
     testing the example suite.

        > gmake check

     This will compile and run the examples in the subdirectory
     examples.

  9. You can now remove the temporary directory, .e.g,

        > cd ..
        > rm -rf objdir

     Alternatively, you can keep the temporary directory to allow
     you to:

     a) Experiment with the examples.

     b) Later uninstall the package.

     To clean up the temporary directory, enter:

        > gmake clean

     To uninstall the package, enter:

        > gmake uninstall


Running the Examples
====================

Copies of the examples reside in the temporary directory - see
instruction 8 above for details on building and running them.

In addition, a copy of the example code resides in the directory
examples at the highest level of the installation.

Use the makefiles provided in the 'examples' directory as templates
for makefiles you need for compiling your own examples.


Using the Configure Script
==========================

The `configure' shell script tries to determine the correct values for
various system-dependent variables used during compilation. It uses
these values to create a `Makefile' in each directory of the package.
It also creates one or more `.h' files containing system-dependent
definitions if needed. Then, it creates the following files:

  config.status         A shell script that you can run at another time to
                        recreate the current configuration.

  config.cache          A file in which the configure test results are
                        saved to speed up reconfiguration.

                        Data is appended to the config.cache file.
                        You can remove unwanted data.

  config.log            A file in which compiler output is saved.
                        This is used to debug the configure script.

If you need to use other commands to successfully compile the package
on your system, please try to determine if the configure script can be used
for these commands. Then, send either a diff file or instructions about
the commands you used to the email address provided in the README file.
This information will be used to improve the installation process in
the next release.

The `configure.in' file is provided in case you want to change or regenerate
the `configure' script, for example to use a newer version of `autoconf'.
The `configure.in' file is used by the `autoconf' program to create the
`configure' script.

Note for developers:

  In case you have changed the `configure.in' file or one of the
  `Makefile.am' files:

  - Run 'make distclean' to remove the generated `configure' script,
    the generated `aclocal.m4' file and the generated `Makefile.in'
    files.

  - Use the GNU autotools `aclocal', `libtoolize' (called `glibtoolize'
    on Mac OS X), `autoheader', `automake', and `autoconf' to generate
    the `configure' script. We use the following sequence:

      aclocal
      libtoolize --automake --force --copy
      autoheader --force
      automake --add-missing --copy
      autoconf

    If you are using a non-GNU compiler you may need to add the
    --include-deps option on the automake line. The script `config/bootstrap'
    containing this command sequence is provided for your convenience.


Compilation and Linking Options
===============================

Some systems require compilation or linking options that the `configure'
script does not define. You can define the initial values for these
options by setting them in your environment before running the
`configure' script.

Using a Bourne-compatible shell, the command line entry might be:

        > CC=c89 CFLAGS=-O2 LIBS=-lposix ../configure

Or, on systems that have the `env' program, the command line entry might be:

        > env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ../configure


Optional Features
=================

By default, optimized libraries are built.


Specifying the System Type
==========================

Some features cannot be automatically determined by `configure' unless
it can detect the host type on which the package will run.
If it prints a message that it cannot determine the host type,
use the `--host=TYPE' option to define it. TYPE can either be a
short system name, such as `sun4', or a canonical name with three fields:

     CPU-COMPANY-SYSTEM

See the `config.sub' file for details about the values of each field. If
the `config.sub' file is not included in the package, the package does not
need to know the host type.

If you are building compiler tools for cross-compiling, you can also
use the `--target=TYPE' option to select the type of system for which
the code is produced and the `--build=TYPE' option to select the type of
system on which you are compiling the package.


Sharing Defaults
================

You can set the default values that `configure' scripts share by
creating a site shell script called `config.site'. This file contains the
default values for variables like `CC', `cache_file', and `prefix'.
The `configure' script looks for the `config.site' file in the following
search precedence:

  1. PREFIX/share/config.site

  2. PREFIX/etc/config.site

Alternatively, you can set the `CONFIG_SITE' environment variable to the
site script path.

Note: The `configure' script for some systems does not look for a site script.


Operation Controls
==================

The `configure' script recognizes the following options to control its
operation:

`--cache-file=FILE'
        Use and save the test results in FILE instead of
        `./config.cache'. Set FILE to `/dev/null' to disable caching
        when debugging `configure'.

`--help'
        Print a summary of `configure' options and exit.

`--quiet'
`--silent'
`-q'
        Do not print messages about checks being made.
        To suppress all normal output, redirect it to `/dev/null'.
        Error messages continue to print.

`--srcdir=DIR'
        Look for the package's source code in directory DIR.
        Typically `configure' determines the directory automatically.

`--version'
        Print the version of `autoconf' used to generate the `configure'
        script and exit.

Other options that are rarely used are available in the `configure' script.
Use the `--help' option to print a list.


3. Installation Notes for Windows
---------------------------------

Note - this release *only* compiles with Visual C++ 2005 or later;
it may not work with earlier versions of Microsoft C++.

SystemC must be installed before starting the install
process for this version of SCV. An environment variable named 'SYSTEMC'
with a variable value that contains the path to the SystemC install is
required by the project that builds the SCV library (e.g.
'C:\apps\systemc-2.3.1\msvc80'). Instructions on how to set this
environment variable are given at the end of this section.


Visual C++ 8.0
==============

The download directory contains two subdirectories: 'msvc80' and
'examples'.

The 'msvc80' directory contains the project and workspace files to
compile the SCV library.

Double-click on the 'scv.sln' file to launch Visual C++ 8.0 (2005) with
the workspace file. The workspace file will have the proper switches set
to compile for Visual C++ 8.0. (Migrating the project files to newer
versions of Visual C++ should work as expected).

Select `Build scv' under the Build menu or press F7 to build
the library and its dependencies.

The `examples' directory contains the project files to compile the SCV
examples. In addition to the 'SYSTEMC' environment variable, an equivalent
environment variable named 'SCV' that contains the path to the SCV install
is required by the SCV example projects (e.g. C:\apps\scv-2.0.0\msvc80).
Go to one of the examples subdirectories and double-click on the
.vcproj file to launch Visual C++ with the workspace file. The workspace
file will have the proper switches set to compile for Visual C++ 8.0. Select
'Build <example>.exe' under the Build menu or press F7 to build the example
executable.

For convenience, a combined solution file called `scv-examples.sln' which
includes all example project files is available in the `msvc80' directory.
With this solution, you can build all examples at once and run them
individually afterwards. Or alternatively, you can run all examples at once by
executing the run_examples.bat script in the `msvc80' directory.


Creating SCV Applications
=========================

1. Start Visual Studio. From the Start Page select New Project and Win32
   Console Project. Type the project name and select a suitable location
   then click OK.

2. Select the Application Settings page of the Win32 Application Wizard
   and make sure the 'Empty project' box is ticked. Click 'Finish' to
   complete the wizard.

3. Add new/existing C++ files to the project and edit code.

4. Display the project Property Pages by selecting 'Properties...'
   from the Project menu.

5. From the C/C++ tab, select the General properties and set
   'Detect 64-bit Portability Issues' to No

6. From the C/C++ tab, select the 'Code Generation' properties and set
   'Runtime Library' to
     - 'Multi-threaded Debug (/MTd)' [for configuration 'Debug']
     - 'Multi-threaded (/MT)'        [for configuration 'Release']

7. From the C/C++ tab, select the Language properties and set
   'Enable Run-Time Type Info' to Yes

8. From the C/C++ tab, select the Command Line properties and add /vmg
   to the 'Additional Options:' box.

9. From the Linker tab, select the Input properties and type
   'scv.lib systemc.lib' in the 'Additional Dependencies' box.

9. (Optional) From the C/C++ tab, select the Advanced properties and
   add '4996' to the 'Disable Specific Warnings' box to silence
   compiler messages about certain C library functions.

10. Click OK


Also make sure that the compiler and linker can find the SystemC and SCV
header and library files respectively. There are two ways to do this, both
can refer to an environment variable pointing to the SystemC and SCV install
paths:

To update the include file and library directory search paths for all
projects:

1. Select Tools -> Options . . . and the Projects -> VC++ Directories tab

2. Select show directories for: Library files

3. Select the 'New' icon and enter: $(SYSTEMC)\SystemC\Debug
   (or Release, if you want to use an optimized build)

4. Select the 'New' icon and enter: $(SCV)\Debug
   (or Release, if you want to use an optimized build)

5. Select show directories for: Include files

6. Select the 'New' icon and enter: $(SYSTEMC)\..\src

7. Select the 'New' icon and enter: $(SCV)\..\src

To add the include file and library directory search paths for the current
project only:

1. Display the project Property Pages by selecting 'Properties...' from
   the Project menu.

2. From the C/C++ tab, select the General properties and type the path to
   the SystemC and SCV 'src' directories in the text entry field labeled
   'Additional include directories'
   (e.g. the examples use '$(SCV)\..\src;$(SYSTEMC)\..\src')

3. From the Linker tab, select the General properties and type the path to
   the SystemC and SCV libraries in the text entry field labeled
   'Additional Library Directories
   (e.g. the examples use '$(SCV)\$(IntDir);$(SYSTEMC)\SystemC\$(IntDir)'
    - $(IntDir) usually expands to `Debug' or `Release')

4. From the Linker tab, select the Input properties and enter the following
   library names in the 'Additional Dependencies' text entry field:
   'scv.lib systemc.lib'

5. Click OK

To set the SYSTEMC and SCV environment variables, right-click on the
'My Computer' icon and select the properties menu. Select the 'Advanced'
tab from the 'System Properties' page and click the 'Environment Variables'
button.

Create a new environment variable named 'SYSTEMC' with a variable value that
contains the path to the SystemC installation
(e.g. 'C:\apps\systemc-2.3.1\msvc80').

Create a new environment variable named 'SCV' with a variable value that
contains the path to the SCV installation (e.g. 'C:\apps\scv-2.0.0\msvc80').
Click OK to save the environment variables
(note the environment variables must be set before starting Visual C++).
