blob: a5231d4892f15f51c843533ec3bb0db10af2c6e4 [file] [log] [blame]
Matthias Jungaa651c72017-03-01 18:39:56 +01001 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!