-
Notifications
You must be signed in to change notification settings - Fork 0
CompilingCloudy
_The skinny on compiling the code._ If you have GNU make and gcc installed you can use the makefiles provided. On Windows you must have Cygwin 1.7.x or newer installed. For more instructions go to the MakefileDescription page. You can then go on to the next step, RunCode.
Instructions for various compilers are given below.
Compilers we know don't work The code uses some fairly advanced parts of C++ and must be compiled with a standards-compliant C++ compiler. Testing shows that Visual Studio 2003; gcc 2.96, gcc 3.4.x; the IA32 version of icc 10.1, and Pathscale EKOPath 2.3.1 cannot successfully compile this version of the code. Cygwin 1.5.x features several broken g++ compilers: only the oldest version 3.3.3 compiler works correctly. Cygwin users are strongly encouraged to upgrade to version 1.7.x or newer of Cygwin.
Makefiles. The gnu make utility is now the preferred method of building Cloudy. A collection of makefiles for several compilers is included in the sys_xxx subdirectories of the source directory in the code distribution. The MakefileDescription page describes how to use the make utility to compile Cloudy.
Configure script. Starting with the C10 release a configure script will be included in the source directory. This script needs to be executed prior to compiling the code. If you compile with make as advertised above, the script will be executed automatically and nothing extra needs to be done. However if you compile by hand, you must first run the script configure.sh in the source directory. You must supply the compiler options as parameters to the script, with "-c *.cpp" omitted. So if you e.g. want to use the Intel compiler you need to type
./configure.sh icc -ansi -w1 -O3 -fp-model source -fp-model except -fp-speculation off
in the source directory before starting the compilation itself. The configure script helps us deal with platform dependencies and idiosyncrasies of certain compilers.
inlining functions At high levels of optimization all compilers will
inline functions.
Most do not inline at low levels of optimization.
The code will run about ten times more slowly without inlining.
Inlining is enabled in all examples below.
Make sure that inlining is enabled if you create your own compiler settings.
Floating point exceptions. Compile options should be set so that the machine throws an exception ("crashes") on division by zero, overflow, and invalid operations. Underflow is inevitable and should not be trapped. The compiler options below should do this. Cloudy has code in routine enable_traps (in the file cpu.cpp) that will set the proper floating point environment for nearly all systems. However, not all platforms are covered. Most notably floating point traps will not be enabled on G4/G5 (PowerPC) based systems.
A note on aggressive optimization. Safe levels of optimization, which we have seen work successfully, are shown in the following examples. If you try to use your compiler's very highest optimization levels you will just find compiler bugs, at least when compiling a code as large as Cloudy. Do a debug compile first, check that all went well by running the TestSuite, and recompile with optimization and run the test suite again. If that fails you will need to do a binary search to find the routine the compiler could not handle, by compiling half the code in debug, and half in optimized mode, eventually tracing down which files could not be compiled with aggressive optimization. The compiler vendor may fix the bug if you can isolate it down to a few lines of code. They won't help if you just tell them that a 200k-line code does not work with their compiler. My experience is that aggressive optimization only gains another 5 to 15 percent speedup and is generally not worth the bother. People time is far more expensive than machine time.
Warnings with routine ParseCrashDo. This routine contains logic that is designed to cause the code to crash. Good compilers will detect dangerous code and create a warning about the use of an uninitialized variable. This is not a problem, it only means that you have a good compiler.
A note on LAPACK. A translated C++ version of some LAPACK routines is included in the source distribution (the file lapack.cpp). Your machine may have a precompiled and optimized version of this library that is faster than mine (for links to these versions, see SupportLibraries). Cloudy actually calls a wrapper for LAPACK that is resolved to either the internal routines (which have slightly changed names to avoid collisions with the real LAPACK) or your system's LAPACK library. If you set the macro LAPACK on the compiler command line (usually with the option -DLAPACK) then the wrappers will resolve to your system's LAPACK library. If the vendor worked hard to generate optimized code then this may be faster than the version obtained by simply compiling the source that comes with the distribution. You may have to include an additional library on the link step to actually load your version of LAPACK.
The assert macro. Asserts are a feature of safe computer languages. They provide for a simple way to insure that variables have sane values. They do slow down the calculation a bit. They can be turned off if you are confident that your compiler produces an executable that behaves properly. Asserts are turned off with the command-line option -DNDEBUG. You would write the compiler command line as something like "g++ -DNDEBUG *.cpp" on the compile step. If you wish to turn off asserts it you should first run the test suite with optimized code and the asserts enabled. Once the test suite completes successfully the -DNDEBUG parameter can be added and the code recompiled. _NB_ - It is important to run the test suite at least once with the asserts included - this could reveal compiler problems that would go unnoticed otherwise.
Array bounds checking Versions C08 and later have the option to do array bounds checking. This is set with the command-line option -DBOUNDS_CHECK. This will enable bounds checking on all arrays derived from the multi_arr and flex_arr container classes, but none of the other arrays. It makes the code much slower, so should only be used for debugging and testing purposes.
The remainder of this page gives advice on compiling the code on various platforms. Note that in the command lines shown below the "o" or "O" is the letter "oh" not the number zero.
This is the preferred compiler. We recommend version 3.1 or later of g++, but not version 3.4 (see below). The code is tested with g++ on a regular basis.
Peter van Hoof found a way to _disable gradual underflows_ when using g++ _on ultrasparcs_ - this results in a major speedup. See the comments around the macro "HAVE_SUNMATH" in cpu.cpp.
Caveats
Starting with the C08 release, Cloudy no longer compiles correctly with g++ compilers from the 3.4.x series due to a serious compiler bug. All g++ versions except 2.96 and 3.4.x will work OK. The compiler will issue an error when you try to compile with a g++ compiler from the 3.4.x series. Linux users with an old installation that contains a g++ 3.4.x compiler will have to upgrade to a newer g++ version, or use another compiler, like e.g. the Sun Studio compiler for Linux (available free of charge). For other UNIX systems you can either use the native compiler, or upgrade to a newer g++ version.
Cygwin users are strongly encouraged to upgrade to Cygwin version 1.7.x or newer. Cygwin 1.5.x features several compilers that will not work. There may be more than one version of perl installed on a cygwin/windows machine. The make command must find the cygwin version of perl or errors will result. The path must be set up to find the cygwin perl.
To find out what version of g++ you have, issue the command "g++ -v".
Compiling the code on Itanium platforms may generate many warnings by the assembler that an "additional NOP may be necessary to work around the Itanium processor A/B step errata". These warnings appear to be benign.
Versions before 2.1 of the Linux glibc library have _problems with floating point precision on Intel processors_. Make sure that you have version 2.1 or later if you plan to work on an Intel box. This should be OK unless you have a really ancient Linux installation.
debug compile
g++ -ansi -Wall -g -finline -c *.cpp
g++ -o cloudy.exe *.o
optimized compile
g++ -ansi -c -O3 -ftrapping-math -fno-math-errno -Wall *.cpp
g++ -o cloudy.exe *.o
The code is tested with g++ on a regular basis. However it is not feasible to test every version of the code against every version of g++ on every platform. It is therefore important that you run the test suite to test the particular combination that you are using.
This compiler is one of the very few that includes native array bounds checking in a C/C++ code. The compiler web site is here. A debug compile with array bounds checking is done with
debug compile with array bounds checking:
pgCC -Minform=warn -Ktrap=fp -Mbounds -DBOUNDS_CHECK -g -O2 -c *.cpp
pgCC -o cloudy.exe *.o
optimized compile:
pgCC -Ktrap=fp -Munroll -O3 -c *.cpp
pgCC -o cloudy.exe *.o
The -A option detects code that does not conform to the ANSI/ISO C++ standard. It produces many errors concerning header files in the PGI distribution we use. Many thanks to Mitchell Martin for testing this compiler.
We tested versions 9.x, 10.x, and 11.0 of icc (the latter only on the development version of the code). The default level of optimization enables rather aggressive forms of floating-point optimization that interfere with the correct execution of Cloudy. It is essential to use the "-fp-model source -fp-model except -fp-speculation off" flags in order to disable those optimizations. The following options were used:
debug compile:
icc -ansi -w1 -g -O0 -c *.cpp
icc -o cloudy.exe *.o -lstdc++
Note that the -O0 command line option needs to given explicitly since the default level of optimization is -O2, and not -O0 as with most other compilers.
optimized compile (icc 10.0 and later):
icc -ansi -w1 -O3 -fp-model source -fp-model except -fp-speculation off -c *.cpp
icc -o cloudy.exe *.o -lstdc++
optimized compile (prior to icc 10.0):
icc -ansi -w1 -O3 -mp -c *.cpp
icc -o cloudy.exe *.o -lstdc++
The icc 9.0 compiler needs an additional parameter "-O0" during the link stage to disable the multi-file optimizer.
Versions prior to icc 9.0 are not supported. They may not work correctly unless you use lower levels of optimization ("-O1 -mp" or even "-O0"). Make sure you run the test suite if you use such a compiler. Support for icc 9.x will be dropped after the C08 release.
WARNING: Testing with the C08 release has shown that the IA32 version of icc 10.1 is incapable of compiling the code correctly with any level of optimization. We recommend that you use another version of icc, or g++, or the Sun C++ compiler instead. This problem is only present on IA32 platforms, and not on any of the 64-bit platforms, and occurs only with icc 10.1.
Many thanks to Peter van Hoof and Ryan Porter for testing this compiler.
Sun provides a C++ compiler for Linux that can be obtained free of charge from the Sun Download Center. When downloaded as a tarball it has the advantage that it can be installed without any root privileges (but patches are not supplied for the tarball-version, only for the rpm-version). It can produce code for both IA32 and AMD64/EM64T platforms. We tested the Sun Studio 12 compiler.
debug compile:
CC -ftrap=common -g -library=stlport4 -c *.cpp
CC -ftrap=common -g -library=stlport4 -Yl,/usr/bin -o cloudy.exe *.o
optimized compile:
CC -fast -fnonstd -g -library=stlport4 -c *.cpp
CC -fast -fnonstd -g -library=stlport4 -Yl,/usr/bin -o cloudy.exe *.o
The -Yl,/usr/bin flag is needed to work around an incompatibility between the (modified) linker supplied by Sun and the object file format in recent Linux distributions. It is only needed on 64-bit systems. See this bug report for further details.
The -library=stlport4 selects a more modern STL implementation that is fully compatible with the ANSI/ISO standard instead of the default Rogue Wave implementation. Cloudy will not compile correctly with the Rogue Wave version of the STL.
Important. The latest release of the Sun Studio compiler (version 12.1) will not work correctly on modern Linux distributions that have g++ 4.4.0 or higher. The symptom is that you get lots of errors like:
"/usr/include/stdio.h", line 480: Error: "(" expected instead of "__attribute__".
"/usr/include/stdio.h", line 480: Error: "(" expected instead of "__attribute__".
"/usr/include/stdio.h", line 480: Error: ")" expected instead of "__attribute__".
... etc ...
The work-around is to modify the file /path/to/sunstudio12.1/prod/include/cc/sys/cdefs.h and apply the following patch:
*** cdefs.h.org 2009-06-04 05:07:18.000000000 +0200
--- cdefs.h 2010-04-20 15:03:13.768273355 +0200
***************
*** 14,20 ****
--- 14,25 ----
* for compilers which don't define __GNUC__. We don't define __GNUC__
* but want attributes support, hence the interposed header.
*/
+ /*
+ disabled until both compilers can accept attributes syntax
+ */
+ #ifndef __cplusplus
#undef __attribute__
+ #endif
/*
* use REDIRECT only for C++/C99 as it uses C99 _Pragma operator
See this thread for more details. The correct fix is in reply 14 of 15.
This compiler can produce code for both IA32 and AMD64/EM64T platforms.
debug compile:
pathCC -c -g -Wall *.cpp
pathCC -o cloudy.exe *.o
optimized compile:
We were not able to get the test suite to pass with any optimization using version 2.3.1 of the compiler either in 32-bit or 64-bit mode.
We do not recommend using the Pathscale EKOPath compiler on either IA32 or AMD64/EM64T platforms. We were able to get the test suite to pass only with the low level of optimization shown above. We recommend g++ on these platforms.
These versions cannot compile the current version of Cloudy. Consider using the Visual C++ 2005 or 2008 Express Edition which are free at http://msdn.microsoft.com/vstudio/express/visualc/.
Use file/new to create a new project.
In "Project Types" select "Visual C++ Projects" / Win32.
Enter a name for the project and browse to a location. Click OK. The project will be in a folder under that specified in the location.
Under "application settings" select "console application" and "empty project", then "finish"
Add all the source and header files to the project with the "project/add existing files" option.
under "project / properties / configuration properties" set the following for all configurations:
"c/c++ / preprocessor / preprocessor definitions" add the following:
CLOUDY_DATA_PATH="\"c:\\projects\\cloudy\\trunk\\data\\\\\""
The string in the CLOUDY_DATA_PATH macro should be modified to give the actual location of the code's data directory. Define the macro OLD_ASSERT if you wish to use old-style asserts.
Under "c/c++ / optimization " make sure that "inline function expansion" is set to "only __inline".
The code will run about ten times more slowly if this is not set.
Under "c/c++/general" set "Debug Information Format" to "Program Database (Z/i)"
The code is developed on this platform.
[mailto:[email protected] Donglai Gong] first ran Cloudy on a Mac. The following is based on his experiences. MacOS X users will first need to download Apple Developer's Tools (free with registration from Apple's developer website) which includes a C++ compiler. When you get to this web site go to the Download section and follow the link to Mac OS X, you'll see the developer tools listed. Douglai Gong stated that Apple's compiler suite (as of OS X 10.2) is basically the GNU compiler collection, version 3.1. All Macs shipping with Mac OS X 10.2 supposedly have the developer tools included on one of the install CD's, although it's not installed by default.
As an alternative you can also download the compilers that are included in the Fink project.
debug compile:
c++ -ansi -c -Wall -g *.cpp
c++ -o cloudy.exe *.o
optimized compile (for PowerPC Mac) :
c++ -ansi -c -Wall -no-cpp-precomp -O3 -fno-math-errno *.cpp
c++ -o cloudy.exe *.o
Megan Donahue found that several test cases ended with a seg fault on her G4. This was because the default kernel setup on her machine had a limited stacksize (512k). A solution is to issue the command "limit stacksize unlimited" (in tcsh) or "ulimit -s unlimited" (in bash) before executing Cloudy. That did the trick. The command should be included in the startup file for your shell on all operating systems.
Jane Rigby tested Cloudy on an Intel Mac Running OS X 10.4 with g++ 4.0.1. She found that the standard compilation options for Linux / g++ also work fine on this platform:
optimized compile (for Intel Mac):
g++ -ansi -c -Wall -O3 -ftrapping-math -fno-math-errno *.cpp
g++ -o cloudy.exe *.o
Many thanks to Donglai Gong, Megan Donahue and Jane Rigby for testing the code on this platform & Peter van Hoof for suggesting compiler options.
With the Sun Studio compiler use the following options:
debug compile:
CC -ftrap=common -g -library=stlport4 -c *.cpp
CC -ftrap=common -g -library=stlport4 -o cloudy.exe *.o
optimized compile:
CC -fast -fnonstd -g -library=stlport4 -c *.cpp
CC -fast -fnonstd -g -library=stlport4 -o cloudy.exe *.o
The warning "/usr/include/ieeefp.h", line 123: warning: dubious reference to enum typedef: fp_rnd" appears to be benign.
Optimized compile with g++ on Sun Sparc stations
g++ -ansi -c -O3 -ftrapping-math -fno-math-errno -Wall *.cpp
g++ *.o
With g++ 3.1 and later, the option -funsafe-math-optimizations will disable gradual underflow. This will lead to a 10 to 20% speedup of the code. However, with g++ 4.3.0 and later, this option is no longer safe and should not be used. For an alternative way of disabling gradual underflow, see the comments around the macro HAVE_SUNMATH in cpu.cpp.
The code is tested on an Ultrasparc II platform on irregular intervals.
This machine uses the Itanium 64 bit processor.
debug compile:
CC -c -g -Aa +e +z -D_HPUX_SOURCE +DD64 *.cpp
CC +FPZO +FPZ -o cloudy.exe *.o -lm
optimized compile:
CC -Aa -O -c +z -D_HPUX_SOURCE +DD64 +e *.cpp
CC +FPZO +FPZ -o cloudy.exe *.o -lm
The code was well tested on this platform until Feb 2007. The HP compiler optimizer was very buggy and could not compile the entire code with much optimization. We worked very hard to locate the source files which confused the compiler. We introduced pragmas to disable optimization in the problematic files. It is possible that HP will have fixed these bugs after our machine was turned off. Search the code for the symbol __HP_aCC
and you will find all places where we had to disable optimization. You might experiment with turning optimization back on to check if the compiler has been fixed.
optimized compile:
xlC -O2 -qarch=auto -qtune=auto -c *.cpp
xlC -o cloudy.exe *.o
Performance may be significantly improved if the IBM Mathematical Acceleration Subsystem (MASS) library is used. This is available at http://www-306.ibm.com/software/awdtools/mass and is included by specifying the additional option "-lmass" in the first step.
RunCode describes how to run the code
Return to StepByStep instructions.