NOTE: For a tutorial on using CMake and Visual Studio for building and installing Sundials v 2.4.0 (which now includes the required CMake configuration files with the source distribution), see this page.
|
Table of Contents
|
Using CMake as a build system for the SUNDIALS library has the advantage that GUI based build configuration is possible. Also build files for Windows development environments can be easily generated. On the Windows platform compilers such as the Borland C++ compiler or Visual C++ compiler are natively supported.
The installation options are very similar to the options mentioned above. Note, however, that CMake may not support all features and plattforms that are supported by the autotools build system.
Prerequisites
You may need to get CMake if it isn't available on your system already. And you will definitely need to download the cmake build files from this page.
Getting CMake
In order to use the CMake build system, you need a fairly recent CMake version. You can download it from www.cmake.org. If you are building cmake from sources on Linux/Unix, make sure to have curses (including development libraries) installed, so that ccmake gets compiled as well. Build instructions for cmake (only necessary for *nix and linux systems) can be found on the CMake page. Once you have CMake installed, you should be able to use CMakeSetup.exe on Windows and ccmake on Linux/Unix.
Getting the build files
The tarball sun_cmake.tar.gz contains the necessary cmake configuration files. It must be copied and expanded in the top level SUNDIALS source directory (note that if you have not downloaded the entire suite but only one solver you may want to expand this tarball in a separate directory and copy the relevant cmake configuration files in their appropriate locations in the SUNDIALS source tree.)
Building on Linux/Unix
Place the sundials archive and the CMake build file archive in one directory:
% ls
sun_cmake.tar.gz sundials-2.3.0.tar.gz
Extract the sundials archive, change into the newly created directory and extract the content of the sun_cmake archive into the directory as well:
% tar xfz sundials-2.3.0.tar.gz
% cd sundials-2.3.0
% tar xfz ../sun_cmake.tar.gz
Now create a subdirectory 'build' inside the sundials directory (you can also create the build directory anywhere else, simply substitute the .. in the next command with the sundials source directory). Next change into that directory and run ccmake.
% mkdir build
% cd build
% ccmake ..
You should now see the ccmake curses interface. Press 'c' to configure your build with the default options. You should see an option listing like in the following screenshot.
(If you don't have curses on your system and cannot use ccmake, you can configure cmake with command line options very similar to ./configure of the autotools. You can read about this on the cmake webpage.)
In the dialog you can adjust the build options. For details see the options above in the autotools section. To adjust advanced options press 't' to show all the options and settings CMake offers.
After adjusting some options, for instance enabling the examples by turning ENABLE_EXAMPLES ON, you need to press 'c' again. Depending on the options, you will see new options at the top of the list, marked with a star. After adjusting the new options, press 'c' again. Once all options have been set, you can press 'g' to generate the make files.
Now you can build and install the sundials library:
% make
% make install
You should see the typical cmake output as shown below:
Building on Windows
The first part in this section is a step-by-step compilation and usage guide for Visual Studio users (namely Visual Studio 2005 aka VC8). In the second part we have a guide on how to build Sundials using Mingw32 GCC or other compilers, which is very similar to the method used on Linux/Unix system.
The first common part is the extraction of the archives, which is due to a lack of native support of tag.gz files not quite as trivial as on Linux.
Extracting the archives
Begin with downloading the sundials archive and the cmake build file archives (from this page, see above). Place them in one directory on your harddrive, for instance C:\sundials:
If you simply double-click the files, chances are that you will get the helpful "unknown file type" window:
Don't bother searching for a program on a standard install, tar.gz files are not supported natively on windows. Instead, download one of the many zip utilities. The one I use is the open source tool 7-zip (7-Zip homepage), which will be used below. After installing 7-zip you get a handy context menu entry:
Use the "Extract here" option to extract the sundials-2.x.x and the sun_cmake archives. Two tar archives will be extracted:
Use the "Extract here" option again on the sundials-2.x.x.tar file and all the files will be extracted into a new sundials-2.x.x subdirectory. Now the sun_cmake.tar needs to be extracted into the new sundials-2.x.x directory. So use the "Extract files…" option from the 7-zip context menu and select the sundials-2.x.x directory (in my case C:\sundials\sundials-2.3.0) as target directory. After the files were extracted you should see a CMakeLists.txt file in the directory listing of the sundials-2.x.x directory.
Building and using Sundials with Visual Studio
Configuration of the Sundials build
Now you need to open a console window.
Note: In order for the correct path variables to be set, you need to open the command line via the link provided as Visual Studio start menu option:
Inside that command window change into your source directory (where the Sundials sources were extracted to) and run CMakeSetup.exe. Here are the commands for my example case:
In the case that CMakeSetup.exe doesn't start the CMake configuration utility, check that the CMake bin directory is in your path environment variable.
Now you should see the CMake configuration dialog. First select the sundials-2.x.x as the source directory. Then copy this directory over in the "build" directory and append the directory name 'build'.
Now you can start the configuration process by clicking on 'configure'. You will be prompted with a number of make file generator options:
Select 'Visual Studio 8 2005" (or select a different make file generator, if you work with a different version). The CMakeSetup.exe tool will now verify the build tool chain and determine the compilation options. Once completed, you will see a list of build options to select. (If the build chain detection fails, there is probably some problem with the VC8 installation or some missing/wrong environmental variables).
You can now adjust the listed options to your needs. Once you are finished, simply click 'configure' again. All options, that are fully configured will turn grey, indicating that you are ready to generate the makefiles. For instance, you can turn compilation of the examples on.
Finally press 'OK' to generate the VC project files. The content of the build directory will now show the following files:
Building the library (and examples)
Now simply double click on the ALL_BUILD.vcproj project file and Visual Studio will open with a (long) list of generated projects.
Simply build the whole solution and after a while the build log will confirm that everything went alright:
Having the libs compiled, now it is fairly easy to use them in your own projects.
Using the Sundials library
Three tasks are involved in order to use a solver of the Sundials library in your own code:
- set include directories in your project
- add required Sundials library project files to your solution
- set Sundials libraries as Dependencies
Done. It is as simple as that. Here's a small step-by-step example:
First close the current solution and create a new Win32 console project. In the "New project" wizard set the following Application options to create an empty project.
Let's build a CVODE based application using one of the CVODE examples. For that we need the CVODE and NVECSERIAL libraries. Use the "Add->Existing project…" option from the solution context menu and select the project files
C:\Sundials\sundials-2.3.0\build\src\cvode\sundials_cvode_static.vcproj
and
C:\Sundials\sundials-2.3.0\build\src\nvec_ser\sundials_nvecserial_static.vcproj
Also add the example program C:\Sundials\sundials-2.3.0\examples\cvode\serial\cvbanx.c to your empty console project.
Now we still need to adjust some of our project settings, because compilation of the example project still fails because the Sundials headers cannot be found. Open the project properties and go to the C++ options:
Here you need to select the include directory of the sundials source directory and the include directory in the sundials 'build' directory:
Now also verify that the linker options show that "Link Library Dependencies" is enabled:
Last but not least set the project dependencies. Open "Project Dependencies" from the context menu of your example project, and check both Sundials libraries:
That's all. Now just compile your project and run it… here"s the result of the test run on my computer:
Building Sundials with Mingw32-GCC or other compilers
This requires a console window with a correctly set path variable for mingw.
First create a subdirectory 'build' inside the sundials source directory (you can also create the build directory anywhere else). Next run CMakeSetup.exe with the sundials source directory as command line argument. Or simply run CMakeSetup.exe and select the source and build directory from the directory combo boxes.
When pressing 'configure' for the first time you will be prompted with a choice of build systems. Select the compiler/build system you want to use and press 'OK'.
In the dialog you can now adjust the build options. For details see the options above in the autotools section. Check the "Show advanced values" checkbox if you want to set advanced options.
After adjusting all options press configure again (all lines should become grey) and Ok to generate make files and quit the GUI.
Now you can run your build systems make tool, e.g. mingw32-make for mingw, make for Borland C++. To use the Intel Compiler you need to create nmake build files and you must start the console window from the provided start menu entry.
If all goes well you will see an output like:
A few observations
- Due to a bug in cmake (which also parses the comments in Fortran source files), some of the Fortran examples in SUNDIALS will not build unless they are slightly modified: you must remove all occurrences of "use" and "module" in comments. The affected files are fcvdenx.f, fcvkryx.f, fcvkryx_bp.f (in examples/cvode/fcmix_serial) and fidadenx.f (in examples/ida/fcmix_serial).
- The installation of examples follows a new philosophy (which will be adopted in the next release also for the autotools-based build system): If examples are enabled by the user, "make" will build all pertinent examples together with the SUNDIALS libraries, but "make install" will export (in a subdirectory of the installation directory) the example sources and sample outputs together with automatically generated configuration files that reference the installed SUNDIALS headers and libraries (and which can therefore be used as "templates" for your own problems). The configure script will install makefiles. CMake installs CMakeLists.txt files and also (as an option available only under *NIX) makefiles. Note: the exported example makefiles are generated from templates (also included in the attached tarball).
- As with autotools, even if generation of shared libraries is enabled, only static libraries are created for the FCMIX modules (due to the use of fixed names for the Fortran user-provided subroutines, FCMIX shared libraries would result in "undefined symbol" errors at link time).
- Since the CMake based build system is fairly new and has only been tested under Linux and Windows (and there only for VC8 and the Intel Compiler) any feedback on how it works on other platforms is appreciated
