INSTALL.swift 6.58 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32

                                Building SWIFT
                                ==============

SWIFT is built from a clean source repository using the commands:

   ./autogen
   ./configure
   make

and from a distribution tarball using:

   ./configure
   make

The compiler choice is GCC by default, but that can be changed using the "CC"
environment variable. This can be just set, or passed on the ./configure
command line, i.e.:

   bash:
      export CC=icc
      ./configure

   [t]csh:
      setenv CC=icc
      ./configure

or:

   ./configure CC=icc

to use an Intel compiler. The main "programs" can be found in the "examples/"
33
directory. See README for run parameters.
34

35 36
SWIFT has been successfully built and tested with the following compilers:

37
  - GCC 4.8.x
38
  - Intel ICC 15.0.x
39
  - clang 3.4.x
40 41

More recent versions and slightly older ones should also be able to
42
build the software.
43

44 45 46 47
It has also been built with Intel and GNU C++ compilers, but that currently
requires the --disable-vec and, for Intel, --disable-compiler-warnings
configure options.

48
By default an attempt to choose suitable set of optimizing compiler flags
49
will be made, targeted for the host machine of the build. If this doesn't
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67
work or the binaries will for another architecture then you can stop the
selection of flags using:

   ./configure --disable-optimization

and then supply your own flags using the "CFLAGS" environment variable, as for
CC.

Note that any CFLAGS that you supply will be added to those determined by
configure in all circumstances. To build SWIFT with debugging support you
can use:

    ./configure --enable-debug --disable-optimization

You could also add some additional flags:

    ./configure --enable-debug --disable-optimization CFLAGS="-O2"

68
for instance. GCC address sanitizer flags can be included using the
69 70 71 72

    ./configure --enable-sanitizer

option. Note this requires a GCC compiler version of at least 4.8.
73

74 75 76 77 78 79 80 81
By default vectorization is switched on. The highest instruction set
available on the platform will be automatically used. However, not all
implementations of SPH available in the code have vectorized
routines. Vectorization will have to be switched off for these. It can
also be switched off for benchmarking purposes. To do so, you can use:

    ./configure --disable-vec

82 83 84
Please note that to build SWIFT on MacOS, you will need to configure
using

85 86 87 88
    ./configure --disable-compiler-warnings

due to the incorrect behaviour of the LLVM compiler on this platform
that raises warnings when the pthread flags are passed to the linker.
89 90


91

92 93
                                 Dependencies
                                 ============
94

95
SWIFT depends on a number of third party libraries that should be available
96
before you can build it.
97 98


99 100 101
 - HDF5:
	A HDF5 library (v. 1.8.x or higher) is required to read and
        write particle data. One of the commands "h5cc" or "h5pcc"
102
        should be available. If "h5pcc" is located then a parallel
103 104
        HDF5 built for the version of MPI located should be
        provided. If the command is not available then it can be
105
        located using the "--with-hdf5" configure option. The value
106
        should be the full path to the "h5cc" or "h5pcc" commands.
107 108
        SWIFT makes effective use of parallel HDF5 when running on more than
        one node, so this option is highly recommended.
109 110 111

 - MPI:
	To run on more than one node an MPI library that fully
112 113
        supports MPI_THREAD_MULTIPLE is required.  Before running configure
        the "mpirun" command should be available in the shell. If your
114 115 116
        command isn't called "mpirun" then define the "MPIRUN"
        environment variable, either in the shell or when running
        configure.
117

118 119 120
	The MPI compiler can be controlled using the MPICC variable,
	much like the CC one. Use this when your MPI compiler has a
	none-standard name.
121

122 123 124
 - GSL:
	To use cosmological time integration, a version of the GSL
	must be available.
125

126
 - FFTW 3.x:
127
	To run with periodic gravity forces, a build of the FFTW 3
128 129 130
	library must be available. Note that SWIFT does not make use
	of the parallel capability of FFTW. Calculations are done by
	single MPI nodes independently.
131

132 133
- libtool:
	The build system relies on libtool as well as the other autotools.
134 135 136



137 138
                           Optional Dependencies
                           =====================
139 140


141 142 143 144 145 146 147 148 149
 - METIS/ParMETIS:
	a build of the METIS or ParMETIS library should be used to
        optimize the load between MPI nodes. This should be found in the
        standard installation directories, or pointed at using the
        "--with-metis" or "--with-parmetis" configuration options.
        In this case the top-level installation directory of the build
        should be given. Note to use METIS or ParMETIS you should supply at
        least "--with-metis". ParMETIS is preferred over METIS when there
        is a choice.
150 151 152 153 154 155 156 157

- libNUMA:
	a build of the NUMA library can be used to pin the threads to
        the physical core of the machine SWIFT is running on. This is
        not always necessary as the OS scheduler may do a good job at
        distributing the threads among the different cores on each
        computing node.

158 159 160 161 162 163
        Note that if you have libNUMA outside of the system include
        directories it may fail to compile as the headers do not pass
        the -Wstrict-prototype check of GCC. In that case you will need
        to use --enable-compiler-warnings=yes configure option to stop
        this being an error.

164 165 166 167 168 169 170 171 172 173 174
 - tcmalloc / jemalloc / TBBmalloc:
	a build of the tcmalloc library (part of gperftools), jemalloc
	or TBBmalloc can be used be used to obtain faster and more
	scalable allocations than the standard C malloc function part
	of glibc. Using one of these is highly recommended on systems
	with many cores per node. One of the options
	"--with-tcmalloc", "--with-jemalloc" or "--with-tbbmalloc"
	should be passed to the configuration script to use it.

 - gperftools:
	a build of gperftools can be used to obtain good profiling of
175
        the code. The option "--with-profiler" needs to be passed to
176 177 178 179 180 181 182 183 184
        the configuration script to use it.

 - DOXYGEN:
	the doxygen library is required to create the SWIFT API
        documentation.

 - python:
	Examples and solution script use python and rely on the numpy
	library version 1.8.2 or higher.
185 186 187 188 189 190



                             SWIFT Coding style
                             ==================

191
The SWIFT source code uses a variation of 'Google' style. The script
192
'format.sh' in the root directory applies the clang-format-10 tool with our
193 194
style choices to all the SWIFT C source file. Please apply the formatting
script to the files before submitting a merge request.