wiki:MakefileDescription

Using GNU make to compile Cloudy

The skinny on building Cloudy with make If you are using g++ on Linux, a Mac, or Cygwin then building the code is trivial since everything is already set up. Open a command prompt window, cd into the source directory, and type make. The code will be built and you are done. 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.

This rest of this page outlines how to use the makefile for Cloudy that is supplied in the source directory. It requires GNU make (which may be called gmake on your system) and is set up for g++, but will also work for other compilers. It is based on experiences of Peter van Hoof and Robin Williams in building the code.

Before you compile

Configuring for a specific compiler

Before you compile Cloudy, first you need to decide which compiler you want to use. The Makefile in the source directory has been set up for an optimized compilation with g++. For most platforms this is the best choice, provided you have a working version of the compiler (see the CompileCode page for more details on this point). You may however choose to use another compiler and/or different compiler options. The easiest way to do this is to use (and possibly edit) the Makefile.conf file that is supplied in the distribution for a number of important compilers (only present in C08 and later, instructions for earlier versions of Cloudy are further down). They are located in directories called sys_xxx under the source directory. Here "xxx" is the name of your compiler, e.g. sys_icc.

You can now do two things. You can change directory into the sys_xxx directory and type make there, or you can copy the Makefile.conf file into the source directory and run make there. Both methods are completely equivalent (except that the resulting object files and binary are in a different place of course), and it is up to you which one you prefer. However, note that some older debuggers require the source and object files to be in the same directory.

If you want to use different compiler options, or a compiler that is not covered by us, an existing Makefile.conf file can be altered for other compilers or compiler options by editing the CXX, CXXFLAGS, LDFLAGS, and LDLIBS fields in the file. Users of releases before C08 should edit the Makefile itself and alter the CXX, CXXFLAGS, LDFLAGS, and LDLIBS fields in that file, but otherwise the instructions below apply to them as well. Alternatively you can set environment variables with the same name in your shell, these will override the default settings in the makefile if you replace make with make -e everywhere below. How to set variables depends on the shell you are using. Here is an example for some commonly used shells:

csh/tcsh:

setenv CXX pgCC

bash/sh/ksh/...

export CXX="pgCC" (no spaces around the "="!)

A third option is to override the setting in the make command itself, e.g.:

make CXX=pgCC CXXFLAGS=-g

What is the OPT field for?

All Makefile.conf files are set up for optimized compilations. If you decide that you need a debug compilation instead (e.g. because you modified the code and ran into problems), you can do that without having to modify the Makefile.conf file by simply typing:

make OPT=-O0

Alternatively you can achieve the same thing by typing (only for releases after C08):

make debug

See also the section above on "Configuring for a specific compiler" for further options during the build process. Note that you need to clean the directory first if an earlier build was done. See the section "Cleaning up" below for more details.

Setting the data path

The makefile will automatically set the path to the data files for you, so the steps outlined here are usually not necessary. If you want a search path that differs from the default, you need to set an environment variable CLOUDY_DATA_PATH prior to compiling. It should contain the full path to the data directory, e.g.:

export CLOUDY_DATA_PATH="/path/to/cloudy/data"

In case you don't do this, the makefile will assume a standard directory layout and assume that the data reside in "/path/to/cloudy/source/../data/". For most people this default will be fine.

Starting with C08, you can supply multiple directories on the search path, separated by colons (semicolons for Windows users). This is convenient for storing locally produced data files, such as grain opacity and stellar atmosphere files. This described in detail on the EditPath page.

It may happen that for some reason you get an error message stating that it could not find a data file:

I Could not open the file phfit.dat


Although there may be other reasons you have received this error,
the most likely reason is that the path has not been properly set.
... etc ...

(the precise wording of the error message may change from version to version). When this happens, you don't need to recompile. If the environment variable CLOUDY_DATA_PATH is defined correctly at runtime, it will always override any other settings in the code and hence fix the problem.

Building Cloudy

When you have finished the setup from the previous section, you can compile the code by simply typing

make

The resulting executable will be named cloudy.exe. The makefile will only work with GNU make, which may be named gmake on non-Linux Unix systems.

Parallel Builds

If you have a multi-core computer, you can take advantage of this by doing a parallel build with

make -j <n>

where <n> is the number of cores you want to use.

Setting macros

If you build in source you can edit Makefile and add macros to the end of this line:

OPT = -O3 -ftrapping-math -fno-math-errno -DMACRO 

where -DMACRO defines the macro MACRO. This cannot be done if you build in one of the sys_xxx subdirectories since Makefile.conf overrides the settings in Makefile. It is easier to compile with

make -j <n> EXTRA=-DMACRO 

File dependencies

In order for make to work correctly, it needs to know how each of the source files depends on the various header files. In versions C10 and older this is defined in the file Makefile.dep. When you have downloaded a fresh version of Cloudy, this file will not be present. The first time you execute the make command, the compiler will automatically create the Makefile.dep file for you. It will use the g++ compiler to do this, irrespective of the compiler you chose to create the Cloudy binary. This is because the compiler you chose may not be able to do this.

If you modify Cloudy and add new source files, or add new #include statements in existing source files, the dependencies of the code will change. The program make will have no way of knowing this, hence you will have to recreate Makefile.dep yourself by typing:

make depend

Starting with C13, the dependencies are no longer kept in a single dependencies file, but are distributed over many small files ending in ".d". These are kept up to date automatically every time you invoke make. Hence there should never be a need anymore to type make depend, though the command is still recognized. In C13 and later the dependencies can be built in parallel.

Building the Data

Starting with the C13 release, Cloudy includes data (e.g. molecular line lists) that need to be converted to internally supported data formats. Normally this is done automatically when you build the binary. If however, in exceptional cases, you need to build the data separately, you can do that by typing

make [ -j <n> ] data

in the source directory, or you can go into the specific subdirectory containing the data and type make [ -j <n> ] there.

Cleaning up

You can clean up the source directory by issuing

make clean

This will remove all the object files and the cloudy.exe binary. You can also use

make distclean

which will revert everything to a pristine state, as if you had just downloaded Cloudy. Hence a full compilation from scratch can be forced by issuing the commands

make clean
make

A full compilation forcing the reconstruction of the file dependencies and the data files can be done with

make distclean
make

Last modified 3 years ago Last modified on 2014-11-17T14:15:51Z