[ViewVC] Annotation of: OpenMD/trunk/INSTALL

Compiling OpenMD

  OpenMD is written in C++. Compiling is the process of turning this
  C++ into instructions that the computer’s processor can understand.

Requirements

  To build OpenMD, you need the following:

   * The source code for the latest release of OpenMD
   * A C++ compiler
   * CMake 2.8.5 or newer

  OpenMD uses CMake as its build system. CMake is an open source
  cross-platform build system from KitWare.

  You need to install CMake 2.6 or newer. This is available as a
  binary package from the KitWare website; alternatively, it may be
  available through your package manager (on Linux). If necessary, you
  can also compile it yourself from the source code.

  The following are optional when compiling OpenMD, but if they are not
  available some features will be missing:

   * OpenMPI – A very good implementation of the MPI-2 specification
     for parallel computing.  A version of the MPI library is required
     if you want to run the multi-processor version of OpenMD

   * perl and python - interpreted scripting languages that some of
     the OpenMD utilities use to parse and process data files.

   * qhull – A computational geometry toolbox for computing convex
     hulls and Delaunay triangulations.  qhull is required for the
     LangevinHull integrator and for any of the tools that compute the
     Hull atoms or hull volumes of nanoparticles and clusters.

   * openbabel – a chemical toolbox for converting between different
     data formats.  This is required for building the atom2md program
     which helps prepare initial "metadata" or md files for
     simulations.

   * fftw - a library for computing discrete Fourier transforms.  This
     is required for surface undulation spectra (Hxy in
     staticProps). Get version 3.

   * zlib - required to support reading gzipped trajectory files

  You’ll also likely want to download and compile the following useful
  tools for interacting with the data:

   * Jmol
   * xmgr
   * grace
   * NumPy
   * vmd

  If you are going to be extending or developing OpenMD, you’ll need
  the following tools:

   * antlr – our tool for parsing meta-data files.  You’ll want
     version 2, not 3.  

   * gengetopt - a tool to generate C code to parse the command line
     arguments argc and argv that are part of every C or C++ program


Basic build procedure

  The recommended way to build OpenMD is to use a separate source and
  build directory; for example, openmd-2.3 and build. The first step
  is to create these directories:

  $ tar zxf openmd-2.3.tar.gz   # (this creates openmd-2.3)
  $ mkdir build

  Now you need to run cmake to configure the build. The following will
  configure the build to use all of the default options:

  $ cd build
  $ cmake ../openmd-2.3

  If you need to specify a particular compiler, you can do that with
  environment variables before the cmake line

  $ export CC=/opt/local/lib/openmpi/bin/mpicc
  $ export CXX=/opt/local/lib/openmpi/bin/mpic++
  $ cmake ../openmd-2.3

  If you need to specify an option, use the -D switch to cmake. For
  example, the following line sets the value of CMAKE_INSTALL_PREFIX
  and CMAKE_BUILD_TYPE:

  $ cmake ../openmd-2.3 -DCMAKE_INSTALL_PREFIX=~/Tools -DCMAKE_BUILD_TYPE=DEBUG

  We will discuss various possible options later.

  At this point, it would be a good idea to compile OpenMD:

  $ make

  Have a coffee while the magic happens. If you have a multi-processor
  machine and would prefer an espresso, try a parallel build instead:

  $ make -j4    # parallel build across 4 processors

  And finally, as root (or using sudo) you should install it:

  # umask 0022 && make install

  Or:
  
  $ umask 0022
  $ sudo make install


Local build

  With the right sort of environment variable magic (see below), you
  can actually use OpenMD straight from the build folder. But life is
  a bit easier if you install it somewhere, either system-wide or
  locally.

  By default, OpenMD is installed in /usr/local on a Unix-like
  system. This requires root access (or sudo). Even if you do have
  root access, you may not want to overwrite an existing installation
  or you may want to avoid conflicts with a version of OpenMD
  installed by your package manager.

  The solution to all of these problems is to do a local install into
  a directory somewhere in your home folder. An additional advantage
  of a local install is that if you ever want to uninstall it, all you
  need to do is delete the installation directory; removing the files
  from a global install is more work.

  To configure cmake to install into ~/Tools/openmd-install, for
  example, you would do the following:

  $ cmake ../openmd-2.3 -DCMAKE_INSTALL_PREFIX=~/Tools/openmd-install

  Then you can run make and make install without needing root access:

  $ make && make install


Troubleshooting build problems

  * CMake caches some variables from run-to-run. How can I wipe the
    cache to start from scratch?

    Delete CMakeCache.txt in the build directory. This is also a very
    useful file to look into if you have any problems.

  * What environment variables affect how OpenMD finds force field and
    data files?

    FORCE_PARAM_PATH - Used to find the location of the data files
                       used for force fields and atom sizes, etc.

    If you get errors about not being able to find some .txt files,
    then you should set this to the name of the folder containing
    files such as Amber.frc and element.txt. These are typically
    installed to /usr/local/openmd/forceFields

  * CMake honors user umask for creating directories as of now:
        http://public.kitware.com/Bug/view.php?id=9620
    To get predictable results please set umask explicitly before
    running the make install command.

Advanced build options 

  * How do I do a debug build?

    -DCMAKE_BUILD_TYPE=Debug does a debug build (gcc -g). To revert to
     a regular build use -DCMAKE_BUILD_TYPE=Release.

  * How do I see what commands cmake is using to build?

    Run Make as follows:

    $ VERBOSE=1 make

  * How do I build the Doxygen documentation?

    If CMake found the "doxygen" program in your PATH, an optional
    build target called "doc" is created.  If the Doxygen executable
    was not on the PATH, you will need to specify its location with
    -DDOXYGEN_EXECUTABLE=wherever.  To build the documentation, type:

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