tpism.rst - pism - [fork] customized build of PISM, the parallel ice sheet model (tillflux branch)
(HTM) git clone git://src.adamsgaard.dk/pism
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) LICENSE
---
tpism.rst (6910B)
---
1 .. include:: ../global.txt
2
3 .. _sec-install-pism:
4
5 Building PISM
6 -------------
7
8 To make sure that the key PETSc and MPI prerequisites work properly together, so that you
9 can run PISM in parallel, you might want to make sure that the correct ``mpiexec`` can be
10 found, by setting your ``PATH``. For instance, if you used the option
11 ``--download-mpich=1`` in the PETSc configure, the MPI ``bin`` directory will have a path
12 like ``$PETSC_DIR/$PETSC_ARCH/bin``. Thus the following lines might appear in your
13 ``.bashrc`` or ``.profile``, if not there already:
14
15 .. code-block:: bash
16
17 export PETSC_DIR=/home/user/petsc-3.10.2/
18 export PETSC_ARCH=opt
19 export PATH=$PETSC_DIR/$PETSC_ARCH/bin/:$PATH
20
21 From now on we will assume that the ``PETSC_ARCH`` and ``PETSC_DIR`` variables are set.
22
23 Follow these steps to build PISM:
24
25 #. Get the latest source for PISM using the Git_ version control system:
26
27 Check `PISM's website <PISM_>`_ for the latest version of PISM.
28
29 .. _git-clone:
30
31 Run
32
33 .. code-block:: bash
34
35 git clone git://github.com/pism/pism.git pism-stable
36
37 A directory called "``pism-stable``" will be created. Note that in the future when you
38 enter that directory, ``git pull`` will update to the latest revision of PISM. [#]_
39
40 #. Build PISM:[#]_
41
42 .. code-block:: bash
43
44 mkdir -p pism-stable/build
45 cd pism-stable/build
46 PISM_INSTALL_PREFIX=~/pism CC=mpicc CXX=mpicxx cmake ..
47 make install
48
49 Here ``pism-stable`` is the directory containing PISM source code while ``~/pism`` is
50 the directory PISM will be installed into.
51
52 Variables ``CC`` and ``CXX`` specify MPI compiler wrappers provided by your MPI
53 installation.
54
55 .. note::
56
57 When using MPI's compiler wrappers, make sure that ``mpicc`` and ``mpicxx`` you
58 select were used to compile the PETSc library: *PISM and PETSc have to use the same
59 MPI installation.*
60
61 All the temporary files created during the build process will be in
62 ``pism-stable/build`` created above.
63
64 Commands above will configure PISM to be installed in ``~/pism/bin`` and
65 ``~/pism/lib/`` then compile and install all its executables and scripts.
66
67 If your operating system does not support shared libraries\ [#]_, then set
68 ``Pism_LINK_STATICALLY`` to "ON". This can be done by either running
69
70 .. code-block:: bash
71
72 cmake -DPism_LINK_STATICALLY=ON ..
73
74 or by using ``ccmake``\ [#]_ run
75
76 .. code-block:: bash
77
78 ccmake ..
79
80 and then change ``Pism_LINK_STATICALLY`` (and then press ``c`` to "configure" and ``g``
81 to "generate Makefiles"). Then run ``make install``.
82
83 Object files created during the build process (located in the ``build`` sub-directory)
84 are not automatically deleted after installing PISM, so run "``make clean``" if space
85 is an issue. You can also delete the build directory altogether if you are not planning
86 on re-compiling PISM.
87
88 .. note::
89
90 When using Intel's compiler high optimization settings such as ``-O3``, ``-fp-model
91 precise`` may be needed to get reproducible model results. Set it using ``ccmake``
92 or by setting ``CFLAGS`` and ``CXXFLAGS`` environment variables when building PISM's
93 prerequisites and PISM itself.
94
95 .. code-block:: bash
96
97 export CFLAGS="-fp-model precise"
98 export CXXFLAGS="-fp-model precise"
99 cmake [other options] ..
100
101 .. note::
102
103 To achieve best performance it can be useful to tell the compiler to target the
104 "native" architecture. (This gives it permission to use CPU instructions that may
105 not work on older CPUs.)
106
107 .. code-block:: bash
108
109 export CFLAGS="-march=native"
110 export CXXFLAGS="-march=native"
111 cmake [other options] ..
112
113 #. PISM executables can be run most easily by adding the ``bin/`` sub-directory in your
114 selected install path (``~/pism/bin`` in the example above) to your ``PATH``. For
115 instance, this command can be done in the Bash_ shell or in your ``.bashrc`` file:
116
117 .. code-block:: bash
118
119 export PATH=~/pism/bin:$PATH
120
121 #. Now see section :ref:`sec-install-quick-tests` or :ref:`sec-start` to continue.
122
123 .. _sec-install-pism-cmake-options:
124
125 PISM's build-time configuration
126 ===============================
127
128 Some of PISM's features (the ones requiring additional libraries, for example) need to be
129 enabled when building PISM. This section lists important build-time options.
130
131 .. csv-table::
132 :header: Option, Description
133
134 ``CMAKE_BUILD_TYPE``, \"build type\": set to \"Debug\" for development
135 ``BUILD_SHARED_LIBS``, build shared (as opposed to static) libraries (this is the default)
136 ``Pism_LINK_STATICALLY``, set CMake flags to try to ensure that everything is linked statically
137 ``Pism_LOOK_FOR_LIBRARIES``, specifies whether PISM should look for libraries (disable this on Crays)
138 ``Pism_BUILD_EXTRA_EXECS``, build additional executables (needed to run ``make test``)
139 ``Pism_BUILD_PYTHON_BINDINGS``, build PISM's Python bindingd; requires ``petsc4py``
140 ``Pism_USE_PROJ``, use the PROJ_ library to compute latitudes and longitudes of grid points
141 ``Pism_USE_PIO``, use the ParallelIO_ library to write output files
142 ``Pism_USE_PARALLEL_NETCDF4``, use NetCDF_ for parallel file I/O
143 ``Pism_USE_PNETCDF``, use PnetCDF_ for parallel file I/O
144 ``Pism_DEBUG``, enables extra sanity checks in the code (this makes PISM a lot slower but simplifies development)
145
146 To enable PISM's use of PROJ_, for example, run
147
148 .. code-block:: bash
149
150 cmake -DPism_USE_PROJ [other options] ..
151
152 .. _sec-install-local-libraries:
153
154 Building PISM with libraries in non-standard locations
155 ======================================================
156
157 To build PISM with libraries installed in a non-standard location such as ``~/local/``,
158 use CMake's variable ``CMAKE_FIND_ROOT_PATH``. Set it to a semicolon-separated list of
159 directories.
160
161 For example, if ``netcdf.h`` is located in ``~/local/netcdf/include/`` and
162 ``libnetcdf.so`` is in ``~/local/netcdf/lib``, add ``~/local/netcdf`` to
163 ``CMAKE_FIND_ROOT_PATH``:
164
165 .. code-block:: bash
166
167 cmake -DCMAKE_FIND_ROOT_PATH=~/local/netcdf [other options] ..
168
169 To build PISM using parallel I/O libraries installed as described in
170 :ref:`sec-install-parallel-io-libs`, do this:
171
172 .. code-block:: bash
173
174 cmake -DCMAKE_FIND_ROOT_PATH="~/local/netcdf;~/local/pnetcdf;~/local/parallelio" \
175 -DPism_USE_PNETCDF \
176 -DPism_USE_PARALLEL_NETCDF4 \
177 -DPism_USE_PIO \
178 ..
179
180 .. rubric:: Footnotes
181
182 .. [#] Of course, after ``git pull`` you will ``make -C build install`` to recompile and
183 re-install PISM.
184
185 .. [#] Please report any problems you meet at these build stages by `sending us
186 <pism-email_>`_ the output.
187
188 .. [#] This might be necessary if you’re building on a Cray XT5 or a Sun Opteron Cluster,
189 for example.
190
191 .. [#] Install the ``cmake-curses-gui`` package to get ``ccmake`` on Ubuntu_.