blob: a5231d4892f15f51c843533ec3bb0db10af2c6e4 [file] [log] [blame] [edit]
INSTALL NOTES FOR SystemC Release 2.3
-------------------------------------
Contents:
1. Installation Notes for Unix
2. Installation Notes for Windows
3. SystemC Library Configuration Switches
1. Installation Notes for Unix
------------------------------
System Requirements
===================
SystemC 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
- Clang 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 BSD
* Architectures
- x86 (32-bit)
- x86_64 (64-bit)
* Compilers
- GNU C++ compiler
- Clang C++ compiler
- or compatible
o Windows
* Compatibility layer
- Cygwin
- 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.
Sources for Compilers and Related Tools
=======================================
To build, install, and use SystemC on UNIX platforms, you need
the following tools:
1. GNU C++ compiler, version 3.4 or later
or
Clang C++ compiler version 3.0 or later
2. GNU Make (gmake)
GCC, Clang, and gmake are free software that you can
obtain from the following sources:
GCC http://www.gnu.org/software/gcc/gcc.html
Clang http://clang.llvm.org/
gmake http://www.gnu.org/software/make/make.html
Basic SystemC Installation
==========================
To install SystemC on a UNIX system, do the following steps:
1. Change to the top level directory (systemc-2.3.1)
2. Create a temporary directory, e.g.,
> mkdir objdir
3. Change to the temporary directory, e.g.,
> cd objdir
4. Choose your compiler by setting the CXX environment variable
(the configure script tries to guess the default compiler, if
this step is omitted):
If you use a POSIX-compatible shell (e.g. bash):
> export CXX="<compiler>"
e.g. for GCC compilers
> export CXX=g++
The Clang compiler is usually named 'clang++', thus e.g.
> export CXX=clang++
When using a C shell (e.g. csh/tcsh), the syntax to set the
environment variable is different:
> setenv CXX g++
For the Sun/Solaris Studio compilers, use
> setenv CXX CC
You can also specify an absolute path to the compiler of your choice.
See also the Section "Compilation and Linking Options" below.
5. Configure the package for your system, e.g.,
(The configure script is explained below.)
> ../configure
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.
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.
SystemC 2.3 includes a fixed-point package that is always built.
When compiling your applications with fixed-point types, you still have
to use compiler flag -DSC_INCLUDE_FX. Note that compile times increase
significantly when using this compiler flag.
In case you want to install the package in another place than the
top level directory (systemc-2.3.1), configure the package e.g. as
follows:
> ../configure --prefix=/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, unless you
follow the Unix/FHS directory layouts (see below).
A fine grained configuration of the installation directories can
be achieved via additional options, given to the configure script.
By default, the files are installed directly to the PREFIX directory
root and the library is installed to PREFIX/lib-<TARGETARCH>,
depending on the current target architecture. This may be undesired
in cases where the package is meant to be installed in a system-wide
location as part of shared (default) library and include hierarchies
(e.g. /usr/local, /usr, /opt, ...). To follow the Unix/FHS directory
standards, you can use the following options:
--with-unix-layout use Unix directory layout for installation
[default=no]
when "yes", the following (fine-grained) settings will be used:
--includedir=DIR C++ header files [PREFIX/include]
--libdir=DIR object code libraries [EPREFIX/lib]
--docdir=DIR documentation root [DATAROOTDIR/doc/systemc]
The library destination itself can be further and separately configured
by using the following option:
--with-arch-suffix add suffix to library installation directory
[default=-<TARGETARCH>]
With this option, one can easily follow e.g. the "multi-arch"
conventions on some platforms:
../configure --with-arch-suffix=32 # lib32
../configure --with-arch-suffix=/x86_64-linux-gnu # lib/x86_64-linux-gnu
Several options are available to the configure script to modify
the compiler configuration and the selection of certain features:
--disable-shared do not build shared library (libsystemc.so)
--enable-debug include debugging symbols
--disable-optimize disable compiler optimization
--disable-async-updates disable request_async_update support
--enable-pthreads use POSIX threads for SystemC processes
--enable-phase-callbacks
enable simulation phase callbacks (experimental)
See the section on the general usage of the configure script and
"../configure --help" for more information.
Note: If you change the configuration after having compiled the
package already, you should run a "gmake clean" before
recompiling.
6. Compile the package.
> gmake
Note: The explicit gmake targets "opt" and "debug", etc. have
been removed in this package. Use the corresponding
options to the configure script instead.
7. At this point you may wish to verify the compiled package by
testing the example suite.
> gmake check
This will compile and run the examples in the subdirectory
examples.
8. Install the package.
> gmake install
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 7 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 (or in the
shared documentation install directory).
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.ac' 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.ac' file is used by the `autoconf' program to create the
`configure' script.
Note for (key) developers:
In case you have changed the `configure.ac' file or one of the
`Makefile.am' files:
- Use the `config/distclean' script to remove the generated `configure'
script, the generated `aclocal.m4' file and the generated `Makefile.in'
files.
- Use the `config/bootstrap' script to generate the `configure' script
and the necessary `Makefile.in' files. This script makes use of the
GNU auto-tools `aclocal', `automake', and `autoconf'.
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.
Instead of passing the variables via the environment, it is preferred
to pass the values as options to the configure script:
> ../configure CXX=g++-4.4 LIBS=-lposix
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 additional 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.
2. Installation Notes for Windows
---------------------------------
This release has been tested on Visual C++ versions 2005 through 2013,
running on Windows 7.
Note: This section covers the installation based on Microsoft Visual C++.
For Cygwin or MinGW-based installations, see Section 1.
Note: If you experience spurious errors about missing files in the
downloaded archive, please make sure to either download the
ZIP archive from accellera.org or use a reliable archive software,
fully supporting modern tar archive versions.
Some paths in the SystemC archive are longer than the historical
99 character limit, and several Windows archivers (e.g. WinZip)
have been reported to trip over this. The open source archiver
7-zip (http://7-zip.org) is known to work.
Microsoft Visual C++ 2005 (compiler version 8.0) or later
---------------------------------------------------------
The download directory contains two subdirectories: 'msvc80' and
'examples'.
The 'msvc80' directory contains the project and workspace files to
compile the 'systemc.lib' library. Double-click on the 'SystemC.sln'
file to launch Visual C++ 2005 with the workspace file. The workspace file
will have the proper switches set to compile for Visual C++ 2005.
Select `Build SystemC' under the Build menu or press F7 to build
`systemc.lib'.
The `examples' directory contains the project and workspace files to
compile the SystemC examples. 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++ 2005. Select 'Build <example>.exe' under the
Build menu or press F7 to build the example executable.
For convenience, a combined solution file 'SystemC-examples.sln' with
all example projects can be found in the 'msvc80' directory. A similar
solution file for the TLM examples is located in 'examples/tlm/build-msvc'.
The provided project files are prepared for both the 32-bit 'Win32' and
64-bit 'x64' configurations. Please refer to the Microsoft Visual Studio
documentation for details about 64-bit builds.
Creating SystemC 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 Language properties and set
'Enable Run-Time Type Info' to Yes
7. From the C/C++ tab, select the Command Line properties and add /vmg
to the 'Additional Options:' box.
8. From the Linker tab, select the Input properties and type 'systemc.lib'
in the 'Additional Dependencies' box.
9. Click OK
Also make sure that the compiler and linker can find the SystemC header
and library files respectively. There are two ways to do this:
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 browse to: C:\systemc-2.3.1\msvc80\systemc\debug
4. Select show directories for: Include files
5. Select the 'New' icon and browse to: C:\systemc-2.3.1\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 'src' directory in the text entry field labeled
'Additional include directories' (e.g. the examples use '..\..\..\src').
3. From the Linker tab, select the General properties and type the path to
the SystemC library: ...\systemc-2.3.1\msvc80\systemc\debug'systemc.lib'
in the 'Additional Library Directories:' box.
9. Click OK
3. SystemC Library Configuration Switches
-----------------------------------------
In addition to the explicitly selectable feature given as options to
the `configure' script (see 1.), some aspects of the library
implementation can be controlled via
- preprocessor switches given during library build
- preprocessor switches added while building a SystemC application
- environment variables
The currently supported switches are documented in this section.
Preprocessor switches
=====================
Additional preprocessor switches for the library build can be passed
to the configure script via the CXXFLAGS variable:
../configure CXXFLAGS="-DSC_OVERRIDE_DEFAULT_STACK_SIZE=0x80000"
In Visual C++, the preprocessor symbols can be added to the project
configuration via the 'C/C++' tab under the 'Preprocessor' properties
in the 'Preprocessor definitions' setting.
* SC_DEFAULT_WRITER_POLICY=<sc_writer_policy> -
Override default value for the signal writer policy
This setting allows deactivating the multiple writer checks for
sc_signals at (application) compile time. This mechanism supersedes
the old environment variable SC_SIGNAL_WRITE_CHECK (see below).
Supported values:
SC_ONE_WRITER (default)
SC_MANY_WRITERS (allow multiple writers in different deltas)
SC_UNCHECKED_WRITERS (non-standard, disable all checks)
Note: Only effective when building an application.
Note: This setting needs to be consistently set across all
translation units of an application.
* SC_DISABLE_ASYNC_UPDATES -
Exclude the "async_request_update" support
Note: This option is usually set by the `configure` option
--disable-async-update, or
--enable-async-update=no
On non-Automake platforms (e.g. Visual C++), this preprocessor
symbol can be used to manually build the library with this feature.
Note: Only effective during library build.
* SC_DISABLE_VIRTUAL_BIND -
Keep the "bind" function of sc_ports non-virtual
When this symbol is defined, the "bind" function in sc_ports is
kept non-virtual (although it is required to be 'virtual' since
IEEE 1666-2011).
Note: This symbol needs to be consistently defined in the library
and any application linking against the built library.
* SC_DISABLE_COPYRIGHT_MESSAGE -
Do not print the copyright message when starting the application
Note: This does not remove the copyright from the binary.
sc_core::sc_copyright() still works as expected.
Note: Only effective during library build.
See : Environment variable SC_COPYRIGHT_MESSAGE
* SC_ENABLE_IMMEDIATE_SELF_NOTIFICATIONS -
Allow a process to trigger itself immediately
Allow a method process to trigger itself immediately by using
next_trigger( ev ); // or a static sensitivity
ev.notify();
This behaviour has been disabled by default in IEEE 1666-2011 and
can be reenabled by this option.
Note: Only effective during library build.
* SC_ENABLE_EARLY_MAXTIME_CREATION -
Allow creation of sc_time objects with a value of sc_max_time()
before finalizing the time resolution
In IEEE 1666-2011, it is not allowed to create sc_time objects with
a non-SC_ZERO_TIME value before setting/changing the time resolution.
This preprocessor switch activates an extension to allow the
initialization of sc_time variables with sc_max_time() while
still accepting changes to the time resolution afterwards.
sc_time t = sc_max_time();
sc_set_time_resolution( 1, SC_NS ); // OK, with this extension
The time resolution will still be fixed, once you have explicitly or
implicitly relied on the physical value (i.e. the relation to seconds)
of any sc_time object.
Note: Only effective during library build.
* SC_ENABLE_SIMULATION_PHASE_CALLBACKS (experimental)
SC_ENABLE_SIMULATION_PHASE_CALLBACKS_TRACING (experimental) -
Enable a generic simulation phase callback mechanism.
Note: This option is usually set by the `configure` option
--enable-phase-callbacks, or
--enable-phase-callbacks=tracing
See the RELEASENOTES for more information about this feature.
The *_TRACING variant of this flag enables the sc_trace
implementation use these callbacks, instead of hard-coded updates
from the main simulator loop.
Note: Setting tracing flag includes the generic phase callback
infrastructure automatically.
Note: Only effective during library build.
* SC_INCLUDE_DYNAMIC_PROCESSES -
Enable dynamic process support (sc_spawn, sc_bind)
To improve compilation times, the functions for spawing dynamic
processes are not included by default in an SystemC application.
Define this symbol before including the SystemC header in your
application, if you want to use dynamically spawned processes.
Note: Can be optionally set per translation unit in an application.
Note: Some TLM convenience sockets require this feature and define
the symbol for you if needed.
* SC_INCLUDE_FX -
Enable SystemC fix-point datatypes
To improve compilation times, the fixpoint datatypes are not enabled
by default in an SystemC application.
Define this symbol before including the SystemC header in your
application, if you want to use the SystemC fixpoint types.
Note: Is by default always defined during the library build to enable
later use of the fixpoint datatypes in an application.
Note: Can be optionally set per translation unit in an application.
* SC_INCLUDE_STRSTREAM -
Include (deprecated) <strstream> header from <systemc.h>
Pre-standard C++ compilers had support for an old stringstream
implementation called 'strstream'. In the unlikely case that your
application still relies on this deprecated class and that <systemc.h>
includes this header for you automatically, you now need to define this
symbol when building your application.
Note: Only effective when building an application.
* SC_INCLUDE_WINDOWS_H -
Explicitly include <windows.h> header from <systemc> header
Previous versions of SystemC always included the full <windows.h>
header on all Windows platforms. This adds unnecessary bloat to
many SystemC applications, reducing compilation times.
If you rely on the inclusion of the <windows.h> header in your
application, you can add this symbol to the list of preprocessor
switches for your compiler.
Note: Only effective when building an application.
* SC_OVERRIDE_DEFAULT_STACK_SIZE=<size> -
Define the default stack size used for SystemC (thread) processes
Note: Only effective during library build.
* SC_USE_SC_STRING_OLD / SC_USE_STD_STRING -
Define 'sc_string' symbol.
Pre-IEEE-1666 versions of SystemC included an 'sc_string' class for
string objects. This class has been superseeded by 'std::string' these
days.
If your application still relies on 'sc_string' being available, set one
of the two supported preprocessor switches to provide it:
SC_USE_SC_STRING_OLD -
Uses old implementation `sc_string_old' to provide `sc_string':
typedef sc_string_old sc_string;
SC_USE_STD_STRING -
Provide `sc_string' as an alias to `std::string':
typedef std::string sc_string;
Influential environment variables
=================================
Currently, three environment variables are checked at library load time
and influence the SystemC library's behaviour:
1) SC_COPYRIGHT_MESSAGE=DISABLE -
Run-time alternative to SC_DISABLE_COPYRIGHT_MESSAGE (see above).
2) SC_SIGNAL_WRITE_CHECK=DISABLE
Run-time alternative to SC_DEFAULT_WRITER_POLICY=SC_UNCHECKED_WRITERS
(see above)
3) SC_DEPRECATION_WARNINGS=DISABLE
Do not issue warnings about using deprecated features as of
IEEE 1666-2011.
Usually, it is not recommended to use any of these variables in new or
on-going projects. They have been added to simplify the transition of
legacy code.
// Taf!