ViewVC Help
View File | Revision Log | Show Annotations | View Changeset | Root Listing
root/OpenMD/branches/development/INSTALL
Revision: 1652
Committed: Tue Sep 27 18:18:28 2011 UTC (13 years, 9 months ago) by gezelter
File size: 6169 byte(s)
Log Message:
added an INSTALL file, using svn2cl to get the ChangeLog target

File Contents

# Content
1 Compiling OpenMD
2
3 OpenMD is written in C++. Compiling is the process of turning this
4 C++ into instructions that the computer’s processor can understand,
5 machine code.
6
7 Requirements
8
9 To build OpenMD, you need the following:
10
11 * The source code for the latest release of OpenMD
12 * C++ and C compilers
13 * CMake 2.6 or newer
14
15 OpenMD uses CMake as its build system. CMake is an open source
16 cross-platform build system from KitWare.
17
18 You need to install CMake 2.6 or newer. This is available as a
19 binary package from the KitWare website; alternatively, it may be
20 available through your package manager (on Linux). If necessary, you
21 can also compile it yourself from the source code.
22
23 The following are optional when compiling OpenMD, but if they are not
24 available some features will be missing:
25
26 * OpenMPI – A very good implementation of the MPI-2 specification
27 for parallel computing. A version of the MPI library is required
28 if you want to run the multi-processor version of OpenMD
29
30 * perl and python - interpreted scripting languages that some of
31 the OpenMD utilities use to parse and process data files.
32
33 * qhull – A computational geometry toolbox for computing convex
34 hulls and Delaunay triangulations. qhull is required for the
35 LangevinHull integrator and for any of the tools that compute the
36 Hull atoms or hull volumes of nanoparticles and clusters.
37
38 * openbabel – a chemical toolbox for converting between different
39 data formats. This is required for building the atom2md program
40 which helps prepare initial "metadata" or md files for
41 simulations.
42
43 * fftw - a library for computing discrete Fourier transforms. This
44 is required for surface undulation spectra (Hxy in
45 staticProps). Get version 3.
46
47 * zlib - required to support reading gzipped trajectory files
48
49 You’ll also likely want to download and compile the following useful
50 tools for interacting with the data:
51
52 * Jmol
53 * xmgr
54 * grace
55 * NumPy
56 * vmd
57
58 If you are going to be extending or developing OpenMD, you’ll need
59 the following tools:
60
61 * antlr – our tool for parsing meta-data files. You’ll want
62 version 2, not 3.
63
64 * gengetopt - a tool to generate C code to parse the command line
65 arguments argc and argv that are part of every C or C++ program
66
67
68 Basic build procedure
69
70 The recommended way to build OpenMD is to use a separate source and
71 build directory; for example, openmd-2.0 and build. The first step
72 is to create these directories:
73
74 $ tar zxf openmd-2.0.tar.gz # (this creates openmd-2.0)
75 $ mkdir build
76
77 Now you need to run cmake to configure the build. The following will
78 configure the build to use all of the default options:
79
80 $ cd build
81 $ cmake ../openmd-2.0
82
83 If you need to specify a particular compiler, you can do that with
84 environment variables before the cmake line
85
86 $ export CC=/opt/local/lib/openmpi/bin/mpicc
87 $ export CXX=/opt/local/lib/openmpi/bin/mpic++
88 $ cmake ../openmd-2.0
89
90 If you need to specify an option, use the -D switch to cmake. For
91 example, the following line sets the value of CMAKE_INSTALL_PREFIX
92 and CMAKE_BUILD_TYPE:
93
94 $ cmake ../openmd-2.0 -DCMAKE_INSTALL_PREFIX=~/Tools -DCMAKE_BUILD_TYPE=DEBUG
95
96 We will discuss various possible options later.
97
98 At this point, it would be a good idea to compile OpenMD:
99
100 $ make
101
102 Have a coffee while the magic happens. If you have a multi-processor
103 machine and would prefer an espresso, try a parallel build instead:
104
105 $ make -j4 # parallel build across 4 processors
106
107 And finally, as root (or using sudo) you should install it:
108
109 # make install
110
111
112 Local build
113
114 With the right sort of environment variable magic (see below), you
115 can actually use OpenMD straight from the build folder. But life is
116 a bit easier if you install it somewhere, either system-wide or
117 locally.
118
119 By default, OpenMD is installed in /usr/local on a Unix-like
120 system. This requires root access (or sudo). Even if you do have
121 root access, you may not want to overwrite an existing installation
122 or you may want to avoid conflicts with a version of OpenMD
123 installed by your package manager.
124
125 The solution to all of these problems is to do a local install into
126 a directory somewhere in your home folder. An additional advantage
127 of a local install is that if you ever want to uninstall it, all you
128 need to do is delete the installation directory; removing the files
129 from a global install is more work.
130
131 To configure cmake to install into ~/Tools/openmd-install, for
132 example, you would do the following:
133
134 $ cmake ../openmd-2.0 -DCMAKE_INSTALL_PREFIX=~/Tools/openmd-install
135
136 Then you can run make and make install without needing root access:
137
138 $ make && make install
139
140
141 Troubleshooting build problems
142
143 * CMake caches some variables from run-to-run. How can I wipe the
144 cache to start from scratch?
145
146 Delete CMakeCache.txt in the build directory. This is also a very
147 useful file to look into if you have any problems.
148
149 * What environment variables affect how OpenMD finds force field and
150 data files?
151
152 FORCE_PARAM_PATH - Used to find the location of the data files
153 used for force fields and atom sizes, etc.
154
155 If you get errors about not being able to find some .txt files,
156 then you should set this to the name of the folder containing
157 files such as Amber.frc and element.txt. These are typically
158 installed to /usr/local/openmd/forceFields
159
160 Advanced build options
161
162 * How do I do a debug build?
163
164 -DCMAKE_BUILD_TYPE=Debug does a debug build (gcc -g). To revert to
165 a regular build use -DCMAKE_BUILD_TYPE=Release.
166
167 * How do I see what commands cmake is using to build?
168
169 Run Make as follows:
170
171 $ VERBOSE=1 make
172
173 * How do I build the Doxygen documentation?
174
175 If CMake found the "doxygen" program in your PATH, an optional
176 build target called "doc" is created. If the Doxygen executable
177 was not on the PATH, you will need to specify its location with
178 -DDOXYGEN_EXECUTABLE=wherever. To build the documentation, type:
179
180 $ make doc