Building the next Cloudy version - Compile the code with an ANSI C++11 compiler

The skinny on compiling the code. If you have a Linux computer, a Mac with LLVM or gcc, or Windows with  Cygwin, and so have g++ and make installed, then building the code is easy. Open a command prompt window, cd into the source directory, and type "make". If you have a multi-core system, you can type make -j <n> to do a parallel build, where <n> is the number of cores you want to use.

The code will be compiled and produce an executable named source/cloudy.exe. You can go to the next step, RunSmokeTest.

How to get the build tools.


For more information on the use of the makefiles go to the MakefileDescription page.

Instructions for various compilers are given below.

Compilers we know don't work The code is written in C++11 and must be compiled with a C++ compiler that fully supports this standard. For g++ that means version 4.8.1 or later, for LLVM/clang++ version 3.3 or later, for the Intel compiler version 15.0 or later, and for the Oracle Studio compiler version 12.5 or later. Older versions will not be able to compile Cloudy. Mac users may have the current, broken, version of Xcode and should check the OS X notes below. Cygwin users should use version 1.7.x or newer of  Cygwin and install the most recent compiler.

Supported platforms. We aim to keep the code working under Linux, Max OS X, Windows, and FreeBSD. We develop and frequently test under Linux and Mac OS X, while Windows and FreeBSD are less frequently tested. The code will likely also work under other BSD variants, but that is not tested. We accept bug reports for all these platforms. Note that under Mac OS X and FreeBSD the default system compiler is LLVM/clang++. You can install g++ on these systems and use it to compile Cloudy, but the compiler will be less tested and may break more easily. On these platforms clang++ is the preferred compiler, despite the fact that it doesn't trap floating point exceptions (see below for more details).

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 has been 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 switch to a different compiler (this includes upgrading to a newer version) then make sure to type make distclean before starting the compilation. 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 by default in all the makefiles.

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. Cloudy has code in the 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 and in binaries compiled with LLVM/clang++.

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 intentionally designed to cause the code to crash. Good compilers will detect dangerous code and create a warning about the use of an uninitialized variable called ‘A_variable_which_SHOULD_be_used_uninitialized’. 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++ <other compiler options> -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.


g++

To use this compiler, build in the source directory or in the sys_gcc subdirectory.

This is the preferred compiler under Linux and Windows/Cygwin?. It produces the fastest code on the machines we test on. We require version 4.8.1 or later of g++. The code is tested with g++ on a nightly basis.

To find out what version of g++ you have, issue the command "g++ -v".

Caveats

 Cygwin users should use Cygwin version 1.7.x or newer and install the most recent compiler. 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. The compilation should be done in a Cygwin terminal. MobaXterm is not supported.

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.


LLVM

To use this compiler, build in the sys_llvm subdirectory. Version 3.3 or later of this compiler is required. This is the native compiler on Mac OS X and FreeBSD systems and is therefore preferred on those platforms.

The  LLVM compiler can be downloaded free of charge from the  LLVM Download Page. LLVM is the name of the project. Their C++ compiler is clang++. Choose the clang binaries that are appropriate for your platform. This compiler has the advantage that it is really easy to install (even without root privileges) and is a very fast compiler. We regularly test recent versions of the compiler.

See the notes below about compiling on a Mac. The version of LLVM which shipped with Xcode 4.1 is broken and cannot compile the code. The LLVM version which shipped with Xcode 5.1 and later doesn't work either. Other versions do work.


Intel icc

To use this compiler, build in the sys_icc subdirectory. Version 15.0 or later of this compiler is required.

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.

Note that the default level of optimization is -O2, and not -O0 as with most other compilers.


Oracle Developer Studio compiler for Linux (formerly Solaris / Sun Studio compiler)

To use this compiler, build in the sys_oraclestudio subdirectory. Version 12.5 or later of the compiler is required.

Oracle provides a C++ compiler for Linux that can be obtained free of charge from the  Oracle download page. When downloaded as a tarball it has the advantage that it can be installed without any root privileges. We test the Solaris Studio 12.5 compiler on a regular basis.

The -Yl,/usr/bin flag is needed to work around an incompatibility between the (modified) linker supplied by Oracle and the object file format in recent Linux distributions. If the compiler does not recognize the linux version you have, it will still fall back to the modified linker included in the distribution. This modified linker will break your code and should never be used on modern Linux distributions. If you get this warning when compiling:

CC: Warning: failed to detect system linker version, falling back to custom linker usage

then you will get the broken linker. The workaround is to remove the broken linker and replace it with a symlink to the system linker.

cd /path/to/developerstudio12.5/lib/compilers/amd64
mv ld ld.broken
ln -s /usr/bin/ld .

MAC OS X

The current version of Xcode ships with a broken version of LLVM and Xcode no longer includes gcc. To get a working compiler see the CompilingCloudyOSX page.

Cloudy versions C13.04 and later will compile correctly with recent versions of Xcode.

You need the command line build tools which are a free download from  here. This includes make, gcc 4.2.1, and a recent version of LLVM.

Both gcc and LLVM compilers work well and are the recommended ways to build the code on a Mac. Note that Apple has  announced that it will stop providing gcc 4.2.1 in Xcode versions after 4.6 and recommends that LLVM be used in its place. The two compilers are highly compatible. From Xcode 5.0 onwards, g++ has been removed but a symbolic link g++ -> clang++ is provided which makes the change transparent to Cloudy users.

Notes

The versions of LLVM which ship with Xcode 4.1 and Xcode 5.1 and later are broken. Other versions do work. See the CompilingCloudyOSX page.


MS Visual Studio 2017

The Visual C++ Visual Studio is a free download at  https://www.visualstudio.com/ We tested Visual C++ 2017

Creating a new project

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. Then remove the files with names "Test*.cpp", and the files md5datafile.cpp and cloudy_lua.cpp, as they are not used.

Compiler options

under "project / properties / configuration properties" set the following for all configurations:

"c/c++ / preprocessor / preprocessor definitions" add the following:

CLOUDY_DATA_PATH="c:\\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. If there are problems setting the path, it can alternatively be set by editing the path.h file. Path.h contains instructions for setting the path depending on operating system.

Define the macro OLD_ASSERT if you wish to use old-style asserts.

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. Set Optimization to Maximize Speed.

c/c++ / Code generation set Basic runtime checks to default.

c/c++/general Set "Debug Information Format" to "Program Database (/Zi)"

configuration properties / c/c++ / advanced Disable warnings 4244; 4305; 4996; 4838 - these warn against double to realnum, and use of fopen;

"c/c++/general" To compile in multiple threads set "Multi-Processor Compilation" to "Yes (/MP)", but you will also have to under "c/c++/code generation" change "Enable Minimal Rebuild" to "No (/Gm-)" as the two options are incompatible. The /MP option is also incompatible with the #import, /E, /EP, /showIncludes, and /Yc, but in the versions tested these were not used by default.


RunCode describes how to run the code

Return to StepByStep instructions.

Return to  nublado.org