LibStmCpp Installation and Usage HOWTO ###################################### This document explains how to set up your development environment in order to use the package LibStmCpp provided by the setup program LibStmCppSetup-.exe. 0 Prerequisite packages ======================= The package LibStmCpp requires the following prerequisite packages available at http://www.SysToMath.com/etc/html/libraries.html: - LibStmC Download the Win32 package installer LibStmCSetup-.exe - Boost-1.34 Download the Win32 package installer Boost-1.34Setup-.exe 1 Download and install the package documentation, header and library files ========================================================================== - Download the Win32 package installer LibStmCppSetup-.exe from SysToMath (see http://www.SysToMath.com/etc/html/libraries.html). - Environment Variable LOCROOT This environment variable shall reside in the system environment (Settings, Control Panel, System, Enhanced, Environment, System Variables). As the Win32 executables and DLLs are installed in %LOCROOT%\bin\w32, it is recommended to add the value %LOCROOT%\bin\w32 to the system path. This has the advantage that all programs and DLLs located in %LOCROOT%\bin\w32 are found without stating an explicit directory path. It is further recommended that %LOCROOT% does not contain spaces and target an initially empty directory on a partition with at least 4 GB of free space. The directory %LOCROOT% shall be the installation path of all SysToMath packages installed on the system. - Be sure to have installed the prerequisite packages with the installation path %LOCROOT%. - Install the package with the installation path %LOCROOT% by executing the Win32 package installer LibStmCppSetup-.exe. 2 Download and install the SysToMath package sources (optional) =============================================================== - Download the Win32 package installer MakePkgSetup.exe from SysToMath (see http://www.SysToMath.com/etc/html/libraries.html). - Install the SysToMath package builder package MakePkg with the installation path %LOCROOT% by execuing MakePkgSetup-.exe - Download the SysToMath package source archive LibStmCppSrc-.tgz from SysToMath (see http://www.SysToMath.com/etc/html/libraries.html). - Environment Variable DEVLROOT This environment variable shall reside in the system environment (Settings, Control Panel, System, Enhanced, Environment, System Variables). %DEVLROOT% shall be different from %LOCROOT% but may be a subdirectory of it. It is further recommended that %DEVLROOT% does not contain spaces and target an initially empty directory on a partition with at least 4 GB of free space. - Expand the package source archive into the directory %DEVLROOT% or into a subdirectory thereof. For the correct functioning of the command makepkg it is important that all SysToMath package source archives are installed somewhere in the tree rooted by %DEVLROOT%. - Read the file ReleaseHowto.txt of the package source archive to learn about the procedures necessary to maintain and build the package. 3 Supported Tool Families ========================= The libraries contained in the package are designed to support the tool families: - Microsoft Visual Studio Tool Family on Win32 - GNU Tool Family on Win32 - GNU Tool Family on Linux Remember that depending on your choice during installation not all tool families and library configurations described in the following might be available. 3.1 Microsoft Visual Studio Tool Family on Win32 ------------------------------------------------ The Microsoft Visual Studio tool family on Win32 consists of the tool sets: - Microsoft Visual Studio .NET 2003 (vc71) - Microsoft Visual Studio 2005 (vc80) 3.1.1 Directory Paths ..................... In Tools, Options, Projects, VC++ Directories some entries are required: - Executable Files: $(LOCROOT)\bin\w32 - Include Files: $(LOCROOT)\include $(LOCROOT)\include\boost-1_34 - Library Files: $(LOCROOT)\lib\w32 3.1.2 Include Paths ................... The header files constituting the API of the SysToMath C++ libraries all reside in the directory %LOCROOT%\include\stm Provided the above recommendments apply, for instance one writes in a program using the SysToMath C++ library module filesysaids: #include 3.1.1 Automatic Linking with Microsoft Visual Studio .................................................... On Microsoft Visual Studio .NET 2003 (vc71) and Microsoft Visual Studio 2005 (vc80) the necessary libraries are linked automatically when header files of the libraries stmaids or stmtoolaids are included, unless this mechanism is suppressed by the definition of the preprocessor symbol STM_NO_LIB (for all libraries), STM_AIDS_NO_LIB (for library stmaids) or STM_TOOLAIDS_NO_LIB (for library stmtoolaids) before that inclusion. The choice of the library depends on the toolset used (vc71 or vc80) and on the system runtime library selected for the executable to be built. The SysToMath C++ libraries stmaids and stmtoolaids each provide two dynamic library configurations (dll files) and four static ones (lib files). In the following list library stands for aids or toolaids and vcnn stands for vc71 or vc80: - ReleaseDllMt: Dynamic release library stmlibrary-vcnn-mt.dll together with its import library stmlibrary-vcnn-mt.lib chosen when linking against the multithreaded release DLL runtime (Compiler switch /MD) and defining the preprocessor variable STM_DYN_LINK before the library header file inclusion. - ReleaseMt: Static release library libstmlibrary-vcnn-mt.lib chosen when linking against the multithreaded release DLL runtime (Compiler switch /MD). - ReleaseMtStaticRt: Static release library libstmlibrary-vcnn-mt-s.lib chosen when linking against the multithreaded static release runtime (Compiler switch /MT). - DebugDllMt: Dynamic debug library stmlibrary-vcnn-mt-gd.dll together with its import library stmlibrary-vcnn-mt-gd.lib and its debug database file stmlibrary-vcnn-mt-gd.pdb chosen when linking against the multithreaded debug DLL runtime (Compiler switch /MDd) and defining the preprocessor variable STM_DYN_LINK before the library header file inclusion. - DebugMt: Static debug library libstmlibrary-vcnn-mt-gd.lib together with its debug database file libstmlibrary-vcnn-mt-gd.pdb chosen when linking against the multithreaded debug DLL runtime (Compiler switch /MDd). - DebugMtStaticRt: Static debug library libstmlibrary-vcnn-mt-sgd.lib together with its debug database file libstmlibrary-vcnn-mt-sgd.pdb chosen when linking against the multithreaded static debug runtime(Compiler switch /MTd). 3.2 GNU Tool Family on Win32 ---------------------------- The GNU tool family on Win 32 consists of the tool sets: - GNU gcc for POSIX environment (cygwin) - GNU gcc for Microsoft environment (cygming) The tool set cygwin (chosen by gcc or g++ without option -mno-cygwin) produces libraries depending on the GPL licensed dynamic library cygwin1.dll and therefore is restricted to free open source software projects, whereas the tool set cygming (chosen by gcc or g++ with option -mno-cygwin) produces libraries only depending on the Microsoft runtime libraries and thus also allows commercial closed source software projects. In the following it is assumed that the environment variable CYGWINROOT designates the Cygwin root directory and Cygwin (www.cygwin.com) with at least the complete packages Base, Devel, Net and Text is installed in %CYGWINROOT% with default text file type set to UNIX/binary, that the values %CYGWINROOT%\usr\local\bin and %CYGWINROOT%\bin are contained in the system executable path before %SYSTEMROOT%\system32 in the above order and that you use gcc and g++ from within a bash console with the following additional environment: export locroot=$(cygpath -u "${LOCROOT//\\//}") 3.2.1 Include Paths ................... To find the include directories, use for gcc and g++ the following options: -I"${locroot}/include" -I"${locroot}/include/boost-1_34" 3.2.2 Library Paths ................... To find the libraries, use for gcc and g++ the following option: -L"${locroot}/lib/w32" 3.2.3 Linking with the GNU Tool Family ...................................... The libraries for the GNU tool family have to be linked explicitely. The choice of the libraries depends on the tool set used (cygwin or cygming) and on the system runtime library selected for the executable to be built. The SysToMath C++ libraries stmaids and stmtoolaids each provide two dynamic library configurations (dll files) and two static ones (a files). In the following list library stands for aids or toolaids and cygxxx stands for cygwin or cygming: - ReleaseDllMt: Dynamic release library stmlibrary-cygxxx-mt.dll together with its import library libstmlibrary-cygxxx-mt.dll.a to be chosen for multithreaded not debug enabled dynamically linked executables (the preprocessor variables NDEBUG and STM_DYN_LINK should be defined). - ReleaseMt: Static release library libstmlibrary-cygxxx-mt.a to be chosen for multithreaded not debug enabled statically linked executables (the preprocessor variable NDEBUG should be defined). - DebugDllMt: Dynamic debug library stmlibrary-cygxxx-mt-d.dll together with its import library libstmlibrary-cygxxx-mt-d.dll.a to be chosen for multithreaded debug enabled dynamically linked executables (the preprocessor variables _DEBUG and STM_DYN_LINK should be defined). - DebugMt: Static debug library libstmlibrary-cygxxx-mt-d.a to be chosen for multithreaded debug enabled statically linked executables (the preprocessor variable _DEBUG should be defined). 3.3 GNU Tool Family on Linux ---------------------------- The GNU tool family on Linux consists of the tool sets: - GNU gcc for glibc version >= 2.3 (libc23) - GNU gcc for glibc version >= 2.4 (libc24) In the following it is assumed that the directory tree rooted by the Win32 environment variable LOCROOT has been NFS exported to the Linux system by means of the Cygwin NFS server. Doing so translates the lnk files on the Win32 side to symbolic links on the Linux side. Further the Linux environment variable locroot is assumed to point to the root of that tree on the Linux system. 3.3.1 Include Paths ................... To find the include directories, use for gcc and g++ the following options: -I"${locroot}/include" -I"${locroot}/include/boost-1_34" 3.3.2 Library Paths ................... To find the libraries, use for gcc and g++ the following option: -L"${locroot}/lib/l32" 3.3.3 Linking with the GNU Tool Family ...................................... The libraries for the GNU tool family have to be linked explicitely. The choice of the libraries depends on the tool set used (libc23 or libc24) and on the system runtime library selected for the executable to be built. The SysToMath C++ libraries stmaids and stmtoolaids each provide two shared library configurations (so files) and two static ones (a files). In the following list library stands for aids or toolaids and libc2x stands for libc23 or libc24: - ReleaseDllMt: Shared release library stmlibrary-libc2x-mt.so to be chosen for multithreaded not debug enabled dynamically linked executables (the preprocessor variables NDEBUG and STM_DYN_LINK should be defined). - ReleaseMt: Static release library libstmlibrary-libc2x-mt.a to be chosen for multithreaded not debug enabled statically linked executables (the preprocessor variable NDEBUG should be defined). - DebugDllMt: Shared debug library stmlibrary-libc2x-mt-d.so to be chosen for multithreaded debug enabled dynamically linked executables (the preprocessor variables _DEBUG and STM_DYN_LINK should be defined). - DebugMt: Static debug library libstmlibrary-libc2x-mt-d.a to be chosen for multithreaded debug enabled statically linked executables (the preprocessor variable _DEBUG should be defined).