INSTALL revision 12027
1                INSTALL NOTES FOR SystemC Release 2.3
2                -------------------------------------
3
4Contents:
5
6        1. Installation Notes for Unix 
7
8        2. Installation Notes for Windows
9
10        3. SystemC Library Configuration Switches
11
12
131. Installation Notes for Unix
14------------------------------
15
16
17System Requirements
18===================
19
20SystemC can be installed on the following UNIX, or UNIX-like platforms:
21
22  o Linux
23    * Architectures
24      - x86 (32-bit)
25      - x86_64 (64-bit)
26      - x86 (32-bit) application running on x86_64 (64-bit) kernel
27        (../configure --host=i686-linux-gnu)
28    * Compilers
29      - GNU C++ compiler
30      - Clang C++ compiler
31      - or compatible
32
33  o Mac OS X
34    * Architectures
35      - x86 (32-bit)
36      - x86_64 (64-bit)
37      - powerpc (32-bit)   [deprecated]
38      - powerpc64 (64-bit) [deprecated]
39    * Compilers
40      - GNU C++ compiler
41      - Clang C++ compiler
42      - or compatible
43
44  o Solaris
45    * Architectures
46      - SPARC (32-bit)
47    * Compilers
48      - GNU C++ compiler
49      - Sun/Solaris Studio
50
51  o BSD
52    * Architectures
53      - x86 (32-bit)
54      - x86_64 (64-bit)
55    * Compilers
56      - GNU C++ compiler
57      - Clang C++ compiler
58      - or compatible
59
60  o Windows
61    * Compatibility layer
62      - Cygwin
63      - MinGW / MSYS
64    * Architectures
65      - x86 (32-bit)
66      - x86_64 (64-bit)
67    * Compilers
68      - GNU C++ compiler
69      - or compatible
70
71Note: Not all combinations are equally well-tested and some combinations
72      may not work as expected.  Please report your findings by following
73      the instructions in the README file.
74
75The README file contains a list of detailed platforms, architectures,
76and compiler versions that have been used for testing this release.
77
78
79Sources for Compilers and Related Tools
80=======================================
81
82To build, install, and use SystemC on UNIX platforms, you need
83the following tools:
84
85  1. GNU C++ compiler, version 3.4 or later
86     or
87     Clang C++ compiler version 3.0 or later
88
89  2. GNU Make (gmake)
90
91GCC, Clang, and gmake are free software that you can
92obtain from the following sources:
93
94  GCC           http://www.gnu.org/software/gcc/gcc.html
95
96  Clang         http://clang.llvm.org/
97
98  gmake         http://www.gnu.org/software/make/make.html
99
100
101Basic SystemC Installation
102==========================
103
104To install SystemC on a UNIX system, do the following steps:
105
106  1. Change to the top level directory (systemc-2.3.1)
107
108  2. Create a temporary directory, e.g.,
109
110        > mkdir objdir
111
112  3. Change to the temporary directory, e.g.,
113
114        > cd objdir
115
116  4. Choose your compiler by setting the CXX environment variable
117     (the configure script tries to guess the default compiler, if
118      this step is omitted):
119
120     If you use a POSIX-compatible shell (e.g. bash):
121
122        > export CXX="<compiler>"
123
124     e.g. for GCC compilers
125
126        > export CXX=g++
127
128     The Clang compiler is usually named 'clang++', thus e.g.
129
130        > export CXX=clang++
131
132     When using a C shell (e.g. csh/tcsh), the syntax to set the
133     environment variable is different:
134
135        > setenv CXX g++
136
137     For the Sun/Solaris Studio compilers, use
138
139        > setenv CXX CC
140
141     You can also specify an absolute path to the compiler of your choice.
142
143     See also the Section "Compilation and Linking Options" below.
144
145
146  5. Configure the package for your system, e.g.,
147     (The configure script is explained below.)
148
149        > ../configure
150
151     While the 'configure' script is running, which takes a few moments, 
152     it prints messages to inform you of the features it is checking.
153     It also detects the platform.
154     
155     Note for System V users: 
156     If you are using `csh' on an older version of System V, you might 
157     need to use the `sh ../configure' command instead of '../configure'.
158     Otherwise, `csh' will attempt to `configure' itself.
159
160     SystemC 2.3 includes a fixed-point package that is always built.
161     When compiling your applications with fixed-point types, you still have
162     to use compiler flag -DSC_INCLUDE_FX. Note that compile times increase
163     significantly when using this compiler flag.
164
165     In case you want to install the package in another place than the
166     top level directory (systemc-2.3.1), configure the package e.g. as
167     follows:
168
169        > ../configure --prefix=/usr/local/systemc-2.3.1
170
171     Note: make sure you have created the target directory before installing
172           the package. Do _not_ use /usr/local as a prefix, unless you
173           follow the Unix/FHS directory layouts (see below).
174
175     A fine grained configuration of the installation directories can
176     be achieved via additional options, given to the configure script.
177
178     By default, the files are installed directly to the PREFIX directory
179     root and the library is installed to PREFIX/lib-<TARGETARCH>,
180     depending on the current target architecture.  This may be undesired
181     in cases where the package is meant to be installed in a system-wide
182     location as part of shared (default) library and include hierarchies
183     (e.g. /usr/local, /usr, /opt, ...).  To follow the Unix/FHS directory
184     standards, you can use the following options:
185
186       --with-unix-layout     use Unix directory layout for installation
187                              [default=no]
188         when "yes", the following (fine-grained) settings will be used:
189
190       --includedir=DIR       C++ header files      [PREFIX/include]
191       --libdir=DIR           object code libraries [EPREFIX/lib]
192       --docdir=DIR           documentation root    [DATAROOTDIR/doc/systemc]
193
194     The library destination itself can be further and separately configured
195     by using the following option:
196
197       --with-arch-suffix     add suffix to library installation directory
198                              [default=-<TARGETARCH>]
199
200     With this option, one can easily follow e.g. the "multi-arch"
201     conventions on some platforms:
202
203       ../configure --with-arch-suffix=32                # lib32
204       ../configure --with-arch-suffix=/x86_64-linux-gnu # lib/x86_64-linux-gnu
205
206
207
208     Several options are available to the configure script to modify
209     the compiler configuration and the selection of certain features:
210
211       --disable-shared        do not build shared library (libsystemc.so)
212       --enable-debug          include debugging symbols
213       --disable-optimize      disable compiler optimization
214       --disable-async-updates disable request_async_update support
215       --enable-pthreads       use POSIX threads for SystemC processes
216       --enable-phase-callbacks
217                               enable simulation phase callbacks (experimental)
218
219
220     See the section on the general usage of the configure script and
221     "../configure --help" for more information.
222
223     Note: If you change the configuration after having compiled the
224           package already, you should run a "gmake clean" before
225           recompiling.
226
227  6. Compile the package.
228
229        > gmake
230
231     Note: The explicit gmake targets "opt" and "debug", etc. have
232           been removed in this package.  Use the corresponding
233           options to the configure script instead.
234
235  7. At this point you may wish to verify the compiled package by
236     testing the example suite.
237
238        > gmake check
239
240     This will compile and run the examples in the subdirectory
241     examples.
242
243  8. Install the package.
244
245        > gmake install
246
247  9. You can now remove the temporary directory, .e.g,
248
249        > cd ..
250        > rm -rf objdir
251
252     Alternatively, you can keep the temporary directory to allow you to:
253
254     a) Experiment with the examples.
255
256     b) Later uninstall the package. To clean up the temporary 
257        directory, enter:
258
259            > gmake clean
260
261        To uninstall the package, enter:
262
263            > gmake uninstall
264
265
266Running the Examples
267====================
268
269Copies of the examples reside in the temporary directory - see
270instruction 7 above for details on building and running them.
271
272In addition, a copy of the example code resides in the directory
273examples at the highest level of the installation (or in the
274shared documentation install directory).
275
276Use the makefiles provided in  the 'examples' directory as templates 
277for makefiles you need for compiling your own examples.
278
279
280Using the Configure Script
281==========================
282 
283The `configure' shell script tries to determine the correct values for
284various system-dependent variables used during compilation. It uses
285these values to create a `Makefile' in each directory of the package.
286It also creates one or more `.h' files containing system-dependent
287definitions if needed. Then, it creates the following files:
288
289  config.status         A shell script that you can run at another time to
290                        recreate the current configuration.
291
292  config.cache          A file in which the configure test results are
293                        saved to speed up reconfiguration.
294
295                        Data is appended to the config.cache file. 
296                        You can remove unwanted data.
297
298  config.log            A file in which compiler output is saved.
299                        This is used to debug the configure script.
300
301If you need to use other commands to successfully compile the package
302on your system, please try to determine if the configure script can be used 
303for these commands. Then, send either a diff file or instructions about
304the commands you used to the email address provided in the README file.
305This information will be used to improve the installation process in
306the next release.
307
308The `configure.ac' file is provided in case you want to change or regenerate
309the `configure' script, for example to use a newer version of `autoconf'. 
310The `configure.ac' file is used by the `autoconf' program to create the
311`configure' script.
312
313Note for (key) developers:
314
315  In case you have changed the `configure.ac' file or one of the
316  `Makefile.am' files:
317
318  - Use the `config/distclean' script to remove the generated `configure'
319    script, the generated `aclocal.m4' file and the generated `Makefile.in'
320    files.
321
322  - Use the `config/bootstrap' script to generate the `configure' script
323    and the necessary `Makefile.in' files. This script makes use of the
324    GNU auto-tools `aclocal', `automake', and `autoconf'.
325
326
327Compilation and Linking Options
328===============================
329
330Some systems require compilation or linking options that the `configure'
331script does not define. You can define the initial values for these
332options by setting them in your environment before running the
333`configure' script.
334
335Instead of passing the variables via the environment, it is preferred
336to pass the values as options to the configure script:
337
338  > ../configure CXX=g++-4.4 LIBS=-lposix
339
340
341Specifying the System Type
342==========================
343
344Some features cannot be automatically determined by `configure' unless
345it can detect the host type on which the package will run.
346If it prints a message that it cannot determine the host type, 
347use the `--host=TYPE' option to define it. TYPE can either be a 
348short system name, such as `sun4', or a canonical name with three fields:
349
350     CPU-COMPANY-SYSTEM
351
352See the `config.sub' file for details about the values of each field. If
353the `config.sub' file is not included in the package, the package does not
354need to know the host type.
355
356If you are building compiler tools for cross-compiling, you can also
357use the `--target=TYPE' option to select the type of system for which
358the code is produced and the `--build=TYPE' option to select the type of
359system on which you are compiling the package.
360
361
362Sharing Defaults
363================
364
365You can set the default values that `configure' scripts share by
366creating a site shell script called `config.site'. This file contains the
367default values for variables like `CC', `cache_file', and `prefix'.
368The `configure' script looks for the `config.site' file in the following 
369search precedence:
370
371  1. PREFIX/share/config.site
372
373  2. PREFIX/etc/config.site
374
375Alternatively, you can set the `CONFIG_SITE' environment variable to the
376site script path.
377
378Note: The `configure' script for some systems does not look for a site script.
379
380
381Operation Controls
382==================
383
384The `configure' script recognizes the following additional options to control
385its operation:
386
387`--cache-file=FILE'
388        Use and save the test results in FILE instead of
389        `./config.cache'. Set FILE to `/dev/null' to disable caching
390        when debugging `configure'.
391
392`--help'
393        Print a summary of `configure' options and exit.
394
395`--quiet'
396`--silent'
397`-q'
398        Do not print messages about checks being made.
399        To suppress all normal output, redirect it to `/dev/null'.
400        Error messages continue to print.
401
402`--srcdir=DIR'
403        Look for the package's source code in directory DIR.
404        Typically `configure' determines the directory automatically.
405
406`--version'
407        Print the version of `autoconf' used to generate the `configure'
408        script and exit.
409
410Other options that are rarely used are available in the `configure' script.
411Use the `--help' option to print a list.
412
413
414
4152. Installation Notes for Windows
416---------------------------------
417
418This release has been tested on Visual C++ versions 2005 through 2013,
419running on Windows 7.
420
421
422Note: This section covers the installation based on Microsoft Visual C++.
423      For Cygwin or MinGW-based installations, see Section 1.
424
425
426Note: If you experience spurious errors about missing files in the
427      downloaded archive, please make sure to either download the
428      ZIP archive from accellera.org or use a reliable archive software,
429      fully supporting modern tar archive versions.
430
431      Some paths in the SystemC archive are longer than the historical
432      99 character limit, and several Windows archivers (e.g. WinZip)
433      have been reported to trip over this.  The open source archiver
434      7-zip (http://7-zip.org) is known to work.
435
436
437Microsoft Visual C++ 2005 (compiler version 8.0) or later
438---------------------------------------------------------
439
440The download directory contains two subdirectories: 'msvc80' and
441'examples'.
442
443The 'msvc80' directory contains the project and workspace files to
444compile the 'systemc.lib' library. Double-click on the 'SystemC.sln'
445file to launch Visual C++ 2005 with the workspace file. The workspace file
446will have the proper switches set to compile for Visual C++ 2005.
447Select `Build SystemC' under the Build menu or press F7 to build
448`systemc.lib'.
449
450The `examples' directory contains the project and workspace files to
451compile the SystemC examples. Go to one of the examples subdirectories
452and double-click on the .vcproj file to launch Visual C++ with the
453workspace file. The workspace file will have the proper switches set
454to compile for Visual C++ 2005. Select 'Build <example>.exe' under the
455Build menu or press F7 to build the example executable.
456
457For convenience, a combined solution file 'SystemC-examples.sln' with
458all example projects can be found in the 'msvc80' directory.  A similar
459solution file for the TLM examples is located in 'examples/tlm/build-msvc'.
460
461The provided project files are prepared for both the 32-bit 'Win32' and
46264-bit 'x64' configurations.  Please refer to the Microsoft Visual Studio
463documentation for details about 64-bit builds.
464
465
466Creating SystemC Applications
467-----------------------------
468
4691. Start Visual Studio. From the Start Page select New Project and Win32 
470   Console Project. Type the project name and select a suitable location 
471   then click OK.
472
4732. Select the Application Settings page of the Win32 Application Wizard 
474   and make sure the 'Empty project' box is ticked. Click 'Finish' to 
475   complete the wizard.
476   
4773. Add new/existing C++ files to the project and edit code.
478
4794. Display the project Property Pages by selecting 'Properties...' from 
480   the Project menu. 
481   
4825. From the C/C++ tab, select the General properties and set 
483   'Detect 64-bit Portability Issues' to No
484
4856. From the C/C++ tab, select the Language properties and set 
486   'Enable Run-Time Type Info' to Yes
487
4887. From the C/C++ tab, select the Command Line properties and add /vmg
489   to the 'Additional Options:' box.
490
4918. From the Linker tab, select the Input properties and type 'systemc.lib' 
492   in the 'Additional Dependencies' box.
493
4949. Click OK
495
496
497Also make sure that the compiler and linker can find the SystemC header 
498and library files respectively. There are two ways to do this:
499
500To update the include file and library directory search paths for all
501projects:
502
5031. Select Tools -> Options... and the Projects -> VC++ Directories tab
504   
5052. Select show directories for: Library files
506
5073. Select the 'New' icon and browse to: C:\systemc-2.3.1\msvc80\systemc\debug
508
5094. Select show directories for: Include files
510
5115. Select the 'New' icon and browse to: C:\systemc-2.3.1\src
512
513To add the include file and library directory search paths for the current
514project only:
515
5161. Display the project Property Pages by selecting 'Properties...' from 
517   the Project menu. 
518
5192. From the C/C++ tab, select the General properties and type the path to the 
520   SystemC 'src' directory in the text entry field labeled
521  'Additional include directories' (e.g. the examples use '..\..\..\src').
522
5233. From the Linker tab, select the General properties and type the path to 
524   the SystemC library:   ...\systemc-2.3.1\msvc80\systemc\debug'systemc.lib' 
525   in the 'Additional Library Directories:' box.
526
5279. Click OK
528
529
530
531
5323. SystemC Library Configuration Switches
533-----------------------------------------
534
535In addition to the explicitly selectable feature given as options to
536the `configure' script (see 1.), some aspects of the library
537implementation can be controlled via
538
539 - preprocessor switches given during library build
540 - preprocessor switches added while building a SystemC application
541 - environment variables
542
543The currently supported switches are documented in this section.
544
545Preprocessor switches
546=====================
547
548Additional preprocessor switches for the library build can be passed
549to the configure script via the CXXFLAGS variable:
550
551  ../configure CXXFLAGS="-DSC_OVERRIDE_DEFAULT_STACK_SIZE=0x80000"
552
553In Visual C++, the preprocessor symbols can be added to the project
554configuration via the 'C/C++' tab under the 'Preprocessor' properties
555in the 'Preprocessor definitions' setting.
556
557
558 * SC_DEFAULT_WRITER_POLICY=<sc_writer_policy> -
559   Override default value for the signal writer policy
560
561   This setting allows deactivating the multiple writer checks for
562   sc_signals at (application) compile time.  This mechanism supersedes
563   the old environment variable SC_SIGNAL_WRITE_CHECK (see below).
564
565   Supported values:
566      SC_ONE_WRITER        (default)
567      SC_MANY_WRITERS      (allow multiple writers in different deltas)
568      SC_UNCHECKED_WRITERS (non-standard, disable all checks)
569
570   Note: Only effective when building an application.
571
572   Note: This setting needs to be consistently set across all
573         translation units of an application.
574
575
576 * SC_DISABLE_ASYNC_UPDATES -
577   Exclude the "async_request_update" support
578
579   Note: This option is usually set by the `configure` option
580     --disable-async-update, or
581     --enable-async-update=no
582
583   On non-Automake platforms (e.g. Visual C++), this preprocessor
584   symbol can be used to manually build the library with this feature.
585
586   Note: Only effective during library build.
587
588
589 * SC_DISABLE_VIRTUAL_BIND - 
590   Keep the "bind" function of sc_ports non-virtual
591
592   When this symbol is defined, the "bind" function in sc_ports is
593   kept non-virtual (although it is required to be 'virtual' since
594   IEEE 1666-2011).
595
596   Note: This symbol needs to be consistently defined in the library
597         and any application linking against the built library.
598
599
600 * SC_DISABLE_COPYRIGHT_MESSAGE -
601   Do not print the copyright message when starting the application
602
603   Note: This does not remove the copyright from the binary.
604         sc_core::sc_copyright() still works as expected.
605   Note: Only effective during library build.
606   See : Environment variable SC_COPYRIGHT_MESSAGE
607
608
609 * SC_ENABLE_IMMEDIATE_SELF_NOTIFICATIONS -
610   Allow a process to trigger itself immediately
611
612   Allow a method process to trigger itself immediately by using
613      next_trigger( ev ); // or a static sensitivity
614      ev.notify();
615
616   This behaviour has been disabled by default in IEEE 1666-2011 and
617   can be reenabled by this option.
618
619   Note: Only effective during library build.
620
621
622 * SC_ENABLE_EARLY_MAXTIME_CREATION -
623   Allow creation of sc_time objects with a value of sc_max_time()
624   before finalizing the time resolution
625
626   In IEEE 1666-2011, it is not allowed to create sc_time objects with
627   a non-SC_ZERO_TIME value before setting/changing the time resolution.
628
629   This preprocessor switch activates an extension to allow the
630   initialization of sc_time variables with sc_max_time() while
631   still accepting changes to the time resolution afterwards.
632
633     sc_time t = sc_max_time();
634     sc_set_time_resolution( 1, SC_NS ); // OK, with this extension
635
636   The time resolution will still be fixed, once you have explicitly or
637   implicitly relied on the physical value (i.e. the relation to seconds)
638   of any sc_time object.
639
640   Note: Only effective during library build.
641
642
643 * SC_ENABLE_SIMULATION_PHASE_CALLBACKS         (experimental)
644   SC_ENABLE_SIMULATION_PHASE_CALLBACKS_TRACING (experimental) -
645   Enable a generic simulation phase callback mechanism.
646
647   Note: This option is usually set by the `configure` option
648     --enable-phase-callbacks, or
649     --enable-phase-callbacks=tracing
650
651   See the RELEASENOTES for more information about this feature.
652
653   The *_TRACING variant of this flag enables the sc_trace
654   implementation use these callbacks, instead of hard-coded updates
655   from the main simulator loop.
656
657   Note: Setting tracing flag includes the generic phase callback
658         infrastructure automatically.
659   Note: Only effective during library build.
660
661
662 * SC_INCLUDE_DYNAMIC_PROCESSES -
663   Enable dynamic process support (sc_spawn, sc_bind)
664
665   To improve compilation times, the functions for spawing dynamic
666   processes are not included by default in an SystemC application.
667
668   Define this symbol before including the SystemC header in your
669   application, if you want to use dynamically spawned processes.
670
671   Note: Can be optionally set per translation unit in an application.
672
673   Note: Some TLM convenience sockets require this feature and define
674         the symbol for you if needed.
675
676
677 * SC_INCLUDE_FX -
678   Enable SystemC fix-point datatypes
679
680   To improve compilation times, the fixpoint datatypes are not enabled
681   by default in an SystemC application.
682
683   Define this symbol before including the SystemC header in your
684   application, if you want to use the SystemC fixpoint types.
685
686   Note: Is by default always defined during the library build to enable
687         later use of the fixpoint datatypes in an application.
688
689   Note: Can be optionally set per translation unit in an application.
690
691
692 * SC_INCLUDE_STRSTREAM -
693   Include (deprecated) <strstream> header from <systemc.h>
694
695   Pre-standard C++ compilers had support for an old stringstream
696   implementation called 'strstream'.  In the unlikely case that your
697   application still relies on this deprecated class and that <systemc.h>
698   includes this header for you automatically, you now need to define this
699   symbol when building your application.
700
701   Note: Only effective when building an application.
702
703
704 * SC_INCLUDE_WINDOWS_H -
705   Explicitly include <windows.h> header from <systemc> header
706
707   Previous versions of SystemC always included the full <windows.h>
708   header on all Windows platforms.  This adds unnecessary bloat to
709   many SystemC applications, reducing compilation times.
710
711   If you rely on the inclusion of the <windows.h> header in your
712   application, you can add this symbol to the list of preprocessor
713   switches for your compiler.
714
715   Note: Only effective when building an application.
716
717
718 * SC_OVERRIDE_DEFAULT_STACK_SIZE=<size> -
719   Define the default stack size used for SystemC (thread) processes
720
721   Note: Only effective during library build.
722
723
724 * SC_USE_SC_STRING_OLD / SC_USE_STD_STRING -
725   Define 'sc_string' symbol.
726
727   Pre-IEEE-1666 versions of SystemC included an 'sc_string' class for
728   string objects.  This class has been superseeded by 'std::string' these
729   days.
730
731   If your application still relies on 'sc_string' being available, set one
732   of the two supported preprocessor switches to provide it:
733
734   SC_USE_SC_STRING_OLD -
735     Uses old implementation `sc_string_old' to provide `sc_string':
736       typedef sc_string_old sc_string; 
737
738   SC_USE_STD_STRING -
739     Provide `sc_string' as an alias to `std::string':
740       typedef std::string sc_string;
741
742
743Influential environment variables
744=================================
745
746Currently, three environment variables are checked at library load time
747and influence the SystemC library's behaviour:
748
749 1) SC_COPYRIGHT_MESSAGE=DISABLE -
750    Run-time alternative to SC_DISABLE_COPYRIGHT_MESSAGE (see above).
751
752 2) SC_SIGNAL_WRITE_CHECK=DISABLE
753    Run-time alternative to SC_DEFAULT_WRITER_POLICY=SC_UNCHECKED_WRITERS
754    (see above)
755
756 3) SC_DEPRECATION_WARNINGS=DISABLE
757    Do not issue warnings about using deprecated features as of
758    IEEE 1666-2011.
759
760Usually, it is not recommended to use any of these variables in new or
761on-going projects.  They have been added to simplify the transition of
762legacy code.
763
764
765// Taf!
766