cogito/calculet-npu-research-archive
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d2677d2205d50aab55fdbd1cbe559a6584989433
calculet-npu-research-archive/source/repositories-complete/systemc-exact/systemc/cmake/INSTALL_USING_CMAKE
T

440 lines
18 KiB
Plaintext
Raw Blame History

Install Notes for SystemC Using CMake to Configure the Build Process
Torsten Maehne, Bern University of Applied Sciences, Switzerland
2017-02-22
Table of Contents
=================
1. Introduction
2. Installation Steps
3. Cross compilation
3.1 Cross Compilation for 32-bit on a 64-bit platform using GCC
3.2 Cross Compilation on OS X
3.3 Generic Cross Compilation to a Target System
4. Finding and Using SystemC with CMake
5. Known Problems
6. Ressources
1. Introduction
===============
WARNING: The CMake build scripts are only provided as a preview to
gather feedback from the community! They are a work in
progress and have not been as thoroughly tested as the
other build options for SystemC (i.e., the traditional
autotools-based build system and the MSVC solutions). There
are known open issues (see section 4).
The original autotools-based build system of the SystemC distribution
only supports a limited number of OS/processor/compiler platforms and
initially did not allow the compilation of shared libraries. This was
the motivation to implement a more flexible configuration system for
SystemC using CMake <http://www.cmake.org/>. Depending on the
operating system, processor, compiler, and available dependency
libraries, it can configure the sources and generate the necessary
files to compile/install SystemC using GNU Make, Ninja, or an IDE such as
Eclipse, Xcode, MS Visual Studio C++, or Kdevelop.
The CMake build scripts are compatible with CMake >=3.1 and have been
tested on the following OS/processor/compiler platforms:
- Mac OS X >= 10.5 (GCC, Clang): i386, x86_64, ppc
- Linux (GCC, Clang): i386, x86_64
- Linux (GCC): aarch64
- Windows (MSYS2 with the MinGW-W32 or MinGW-W64 GCC toolchains): x86, AMD64
Currently untested, but considered by the build script (based on the
autotools scripts) are:
- *BSD (GCC, Clang): i386, x86_64
- Linux (GCC, Clang): sparc, powerpc
- Linux (Clang): aarch64
- Mac OS X <= 10.5 (GCC): ppc64
- Windows (Cygwin GCC, MinGW-W32 GCC, MinGW-W64 GCC, Visual C++): x86, AMD64
- Solaris (GCC and native compiler): sparc
- HP-UX (GCC and native compiler): hppa
The build process can be configured by the users through the
configuration variables offered to the user in the CMake console and
GUI (ccmake and cmake-gui, respectively).
CMake suggests to prefer out-of-source builds in contrast to in-source
builds to clearly separate the source from the generated files. Thus,
the build can be cleaned easily by deleting the build directory.
2. Installation Steps
=====================
Typically, the following steps need to be followed to compile the
sources using CMake:
1.) Download and install CMake from <http://www.cmake.org/> (Linux
distributions provide often a package). Note, the CMake script have been
developed for CMake >= 3.1.
2.) Create a build subdirectory:
$ pwd
.../systemc/
$ mkdir build
3.) Launch the interactive cmake console program ccmake (on Unix) or
the CMake GUI (Unix, Mac OS X, Windows) and specify the source
(.../systemc) and build directory (.../systemc/build). For
the console based ccmake, this is done by changing into the build
directory and launching ccmake with the relative path to the source root
directory as an argument:
$ cd build/
$ ccmake ..
For cmake-gui, the same approach works:
$ cd build/
$ cmake-gui ..
Alternatively, the CMake GUI allows to directly enter the paths to the
sources and build directoy in the top of its main window.
4.) Configure the sources by pressing 'c' or clicking on
"Configure". Depending on the operating system, CMake will ask the user
what it should generate Makefiles or IDE project files (Eclipse,
Xcode, Kdevelop, MS Visual Studio C++). CMake will parse the file
CMakeLists.txt in the source root directory and configure the sources
accordingly carrying out all necessary platform-specific checks.
The CMake build scripts detect the actual features provided by the
target (Unix or Windows) platform. On Unix (including OS X), shared
libraries can be built. If the QuickThreads library provides support
for the target processor, it will be automatically used. Otherwise, we
rely on Pthreads on Unix and Fiber on Windows. By default, the SystemC
library installation will follow the GNU standard installation layout
so that also other SystemC libraries (SystemC, SCV, TLM, AMS
extensions) can be installed into the same directory hierarchy (Unix:
/opt/systemc/; Windows: $ENV{ProgramFiles}/SystemC/). The target
platform's conventions are respected meaning usually include/ for the
headers and lib/, lib64/, or lib/<multiarch-tuple>/ for the libraries.
The lib-${SYSTEMC_TARGET_ARCH})/ convention is not used by default, as
${SYSTEMC_TARGET_ARCH} does not reliably encode the
OS/processor/compiler tuple.
The build process can be configured through the configuration
variables offered to the user in the CMake console and GUI (ccmake and
cmake-gui, respectively). Each variable is annotated with a brief
documentation string. The most important variables are:
BUILD_SHARED_LIBS Build shared instead of static libraries
(default: ON if not targetting Windows).
BUILD_SOURCE_DOCUMENTATION Build source code documentation using Doxygen
(default: OFF).
CMAKE_BUILD_TYPE Specifies the build type on single-configuration
generators. (default: Release).
CMAKE_CXX_STANDARD C++ standard to build all targets. Supported
values are 98, 11, and 14. (default: 98)
CMAKE_CXX_STANDARD_REQUIRED The with CMAKE_CXX_STANDARD selected C++ standard
is a requirement. (default: ON)
CMAKE_INSTALL_PREFIX Root directory of the SystemC libraries
installation (defaults to $ENV{SYSTEMC_HOME}
if set to an absolute path and otherwise to either
/opt/systemc/ (Unix-like platforms including
CYGWIN), $ENV{ProgramFiles}/SystemC/ (on Windows
systems), or ${CMAKE_INSTALL_PREFIX}/systemc.
CMAKE_OSX_ARCHITECTURES Architectures for cross-compilation on Mac OS X
(default: empty, i.e., only for the system
processor).
CMAKE_VERBOSE_MAKEFILE Generate a verbose Makefile (default: OFF).
DISABLE_ASYNC_UPDATES Disable async_request_update() support.
DISABLE_COPYRIGHT_MESSAGE Do not print the copyright message when starting
the application. (default: OFF)
DISABLE_VIRTUAL_BIND Disable the definition of bind() member
functions of ports and exports as "virtual",
which is incompatible with old TLM library
implementations (< 2.0.2).
ENABLE_ASSERTIONS Always enable the `sc_assert' expressions
(default: ON)
ENABLE_IMMEDIATE_SELF_NOTIFICATIONS Enable immediate self-notification of
processes, which is no longer supported due to
changes in IEEE Std 1666-2011 (see
sc_event::notify, 5.10.6).
ENABLE_PTHREADS Use POSIX threads for SystemC processes instead
of QuickThreads on Unix or Fiber on Windows.
SystemC_TARGET_ARCH Target architecture according to the
Accellera SystemC conventions set either from
$ENV{SYSTEMC_TARGET_ARCH}, $ENV{SYSTEMC_ARCH},
or detected by CMake.
INSTALL_TO_LIB_BUILD_TYPE_DIR Install the libraries to lib-${CMAKE_BUILD_TYPE}
to enable parallel installation of the different
build variants. (default: OFF)
INSTALL_TO_LIB_TARGET_ARCH_DIR Install the libraries to lib-<target-arch>
to facilitate linking applications, which
build systems assume to find SystemC in
lib-<target-arch>. (default: OFF)
INSTALL_LIB_TARGET_ARCH_SYMLINK On Unix, install a symlink lib-<target-arch>
to lib-${CMAKE_BUILD_TYPE} facilitating the
linking of user code, which build system assumes
to find the SystemC libraries under
lib-<target-arch>. (default: OFF)
Other configuration variables will be proposed by CMake depending on the OS
and detected processor, compiler, and libraries. For more information, please
refer to the CMake documentation or <http://www.cmake.org/>.
The configuration step needs to be repeated until no new configuration
variables appear.
5.) Generate the Makefiles or IDE project files by pressing 'g' or
clicking on "Generate".
6.) Compile, test, and install the libraries using make or the IDE:
$ make
$ make check
$ sudo make install
More documentation on using CMake is available from the the CMake Wiki
<http://www.cmake.org/Wiki/CMake>.
3. Cross Compilation
====================
CMake supports cross compilation on a host system for a different
target architecture. Depending on the scenario, different approaches
can be used.
3.1 Cross Compilation for 32-bit on a 64-bit platform using GCC
---------------------------------------------------------------
This section is primarily relevant for users of 64-bit versions of
Linux and Windows.
On 64-bit platforms like Linux x86_64 and Windows AMD64, the OS
provides usually for backward-compatability the capability to execute
64-bit and 32-bit applications. To this end, it provides 32-bit and
64-bit versions of all runtime libraries (on Linux, they can be
usually found in the lib/ and lib64/ directories). On these platforms,
the GCC toolchain is usually installed in a multilib variant, which
supports the compilation and linking of 64-bit and 32-bit applications
and libraries. The word width of the target architecture is simply
chosen with the "-m64" or "-m32" option, which has to be consistently
passed at each compiler and linker call.
Therefore, it is in principle sufficient to add "-m32" to the
corresponding CMake variables containing the flags to be passed to the
linker and compiler:
CMAKE_C_FLAGS
CMAKE_CXX_FLAGS
CMAKE_EXE_LINKER_FLAGS
CMAKE_MODULE_LINKER_FLAGS
CMAKE_SHARED_LINKER_FLAGS
CMAKE_STATIC_LINKER_FLAGS
These flags should be already set upon the first CMake invocation in a
new build directory, as most system introspection results are cached
over multiple CMake runs. You can do so via the "-D<VAR>=<VALUE>"
option of cmake, ccmake, and cmake-gui.
In a similar way, the particular C or C++ compiler can be chosen by
providing the name (optionally preceded by the path) of the compiler
executables:
CMAKE_C_COMPILER
CMAKE_CXX_COMPILER
However, it is very handy to know that CMake honors the standard
environment variables CC (C compiler), CXX (C++ compiler), CFLAGS (C
compiler flags), CXXFLAGS (C++ compiler flags), and LDFLAGS (linker
flags), which are also used by other tools such as GNU Make, to
initialize the above variables upon its first call in a new build
directory. Note, that CPPFLAGS is currently ignored by CMake
<http://www.cmake.org/Bug/view.php?id=12928>.
On certain platforms, CMake might have trouble to find the right
library for the target processor architecture when using
find_package() or find_library() in the CMake scripts. In that case, it
can help to explicitly set the following global property in your CMake
file before issuing any find_package() or find_library() in your CMake
script:
set_property (GLOBAL FIND_LIBRARY_USE_LIB64_PATHS <TRUE|FALSE>)
If set to TRUE, it will look for the library in lib64/ instead of lib/.
This property is usually automatically set on platforms known to need
it, but depending on the chosen compiler options, it may need adjustment.
3.2 Cross Compilation on OS X
-----------------------------
On OS X, a similar approach as in section 3.1 can be adopted. However,
it has to be noted that Apple's versions of GCC and Clang don't support
"-m32" and "-m64", but the more flexible "-arch
<i386|x86_64|ppc|ppc64>" parameter. The latter can be even repeated
several times on the command line to create universal binaries able to
run on several processor architectures. CMake has native support for
this command line option, which value can be set centrally in the
CMake scripts and will be then passed on to the compilers and linker.
It is sufficient to set the variable CMAKE_OSX_ARCHITECTURES to the
desired target architecture(s). Multiple architectures are separated
with a ';'. You can do so already on the command line
$ cmake .. -DCMAKE_OSX_ARCHITECTURES=x86_64;i386;ppc
or in variable editors of ccmake and cmake-gui.
If you are using MacPorts or Homebrew versions of GCC, you will have
to make sure that you install universal variants of the compiler
toolchain. Then, you can follow the instruction in section 3.1.
3.3 Generic Cross Compilation to a Target System
------------------------------------------------
As CMake cannot guess the target system, a number of variables have to
be preset so that the correct compiler toolchain and libraries are
found. It is recommended to do this with a so-called toolchain file,
which is passed as an argument to cmake, ccmake or cmake-gui using the
option "-DCMAKE_TOOLCHAIN_FILE=<path-to-file>". The file in CMake
syntax has to define the following variables:
CMAKE_SYSTEM_NAME (mandatory), e.g., "Linux", "Windows", "Darwin"
CMAKE_SYSTEM_VERSION (optional)
CMAKE_SYSTEM_PROCESSOR (optional), e.g., "i386", "x86_64", "ppc", "ppc64"
CMAKE_C_COMPILER (mandatory), name of C compiler executable
CMAKE_CXX_COMPILER (mandatory), name of C compiler executable
CMAKE_FIND_ROOT_PATH (optional), root to target include and library directories
CMAKE_FIND_ROOT_PATH_MODE_PROGRAM, either "NEVER", "ONLY", or "BOTH" (default)
CMAKE_FIND_ROOT_PATH_MODE_LIBRARY, either "NEVER", "ONLY", or "BOTH" (default)
CMAKE_FIND_ROOT_PATH_MODE_INCLUDE, either "NEVER", "ONLY", or "BOTH" (default)
The necessary steps are discussed in detail on the CMake Wiki
<http://www.cmake.org/Wiki/CMake_Cross_Compiling>.
4. Finding and Using SystemC with CMake
=======================================
The CMake build scripts install CMake package config files to facilitate finding
the SystemC and TLM libraries. The packages are called SystemCLanguage and
SystemCTLM. As the TLM support is compiled into the SystemC library, the package
SystemCTLM just finds the matching SystemC library as a dependency. As SystemC
is usually installed in its own directory tree, you have to tell CMake where to
look for the package config files by setting the variable CMAKE_PREFIX_PATH to
the root directory of your SystemC installation before calling find_package().
The SystemCLanguage package provides the imported target SystemC::systemc to
which an application or library should link to. Linking to an imported target
ensures that all necessary preprocessor definitions, compiler options, and
transitive link libraries are used when compiling and linking the application.
The SystemCLanguage package exports a number of variables:
SystemC_TARGET_ARCH Target architecture according to the Accellera
SystemC conventions
SystemC_CXX_STANDARD Preferred C++ standard
SystemC_CXX_STANDARD_REQUIRED Determine whether the selected C++ standard is
a requirement
The SystemC_CXX_STANDARD and SystemC_CXX_STANDARD_REQUIRED variables should be
used to initialize the respective CMAKE_CXX_STANDARD and
CMAKE_CXX_STANDARD_REQUIRED variables in the CMake build scripts of the
application/library. Alternatively, the CXX_STANDARD and CXX_STANDARD_REQUIRED
target properties can be set directly.
As an example, here is a minimal CMakeLists.txt to compile the simple_perf
SystemC example as a stand-alone application:
--- Start: CMakeLists.txt ---
cmake_minimum_required(VERSION 3.1)
project(simple_perf CXX)
set (CMAKE_PREFIX_PATH /opt/systemc)
find_package(SystemCLanguage CONFIG REQUIRED)
set (CMAKE_CXX_STANDARD ${SystemC_CXX_STANDARD} CACHE STRING
"C++ standard to build all targets. Supported values are 98, 11, and 14.")
set (CMAKE_CXX_STANDARD_REQUIRED ${SystemC_CXX_STANDARD_REQUIRED} CACHE BOOL
"The with CMAKE_CXX_STANDARD selected C++ standard is a requirement.")
add_executable(simple_perf simple_perf.cpp)
target_link_libraries(simple_perf SystemC::systemc)
--- End: CMakeLists.txt ---
5. Known Problems
=================
- The CMake build scripts require more thorough testing of the various build
configurations on as many platforms as possible. For the moment, testing
has been primarily done on OS X (x86_64 and i686) and Linux (x86_64 and
i686) as well as to a lesser degree on Windows 7 using MSYS2 + MingGW-W64
and MSVC 2013 / 2015 (x86_64 and i686).
- The CMake build scripts do not yet support the compilation of the SystemC
libraries as a DLL on Windows. To make it work, the SystemC library has to
be at least split into libsystemc-core.dll and a static libsystemc.lib.
- The CMake build scripts don't yet configure and install systemc.pc and
tlm.pc for pkg-config.
6. Ressources
=============
[1] CMake - Cross Platform Make Homepage <http://www.cmake.org>
[2] CMake Documentation <http://www.cmake.org/cmake/help/documentation.html>
[3] CMake Wiki <http://www.cmake.org/Wiki/CMake/>
|4] Ken Martin, Bill Hoffman: "Mastering CMake", Kitware.
<http://www.cmake.org/cmake/help/book.html>
[5] The MacPorts Project Homepage <http://www.macports.org>
[6] Homebrew -- The missing package manager for OS X. <http://brew.sh>
Reference in New Issue View Git Blame Copy Permalink