-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathNOTES
295 lines (256 loc) · 14 KB
/
NOTES
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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
-------------------------------------------------------------------------------
MB-SYSTEM INSTALLATION NOTES FILE:
-------------------------------------------------------------------------------
Version: $Id: NOTES 2159 2014-01-18 23:19:37Z caress $
-------------------------------------------------------------------------------
This file contains installation notes for the MB-System open source software
package for the processing and display of swath sonar data. This file is located
at the top of the MB-System source code distribution directory structure.
-------------------------------------------------------------------------------
THE MB-SYSTEM SOURCE CODE DISTRIBUTION:
-------------------------------------------------------------------------------
MB-System is distributed as a compressed tar archive named according to the
release version. For example, release 5.4.2081 was distributed in a file named:
mbsystem-5.4.2081.tar.gz
Here the major release is 5, the minor release is 4, and the third number is the
corresponding revision number for the source code archive (which is managed
using the Subversion package).
The source code archive can be accessed directly at:
http://svn.ilab.ldeo.columbia.edu
The tar utility is used to extract the distribution:
% tar xvzf mbsystem-5.4.2081.tar.gz
yielding a directory named "mbsystem-5.4.2081".
Listing the contents of the top directory and then the src directory below
reveals:
% cd mbsystem-5.4.2081
% ls -s
total 2920
8 AUTHORS 8 NEWS 40 configure.in
16 COPYING 16 NOTES 48 depcomp
224 ChangeLog 56 README 32 install-sh
72 GPL 88 config.guess 64 install_makefiles
32 INSTALL 72 config.sub* 576 libtool*
48 Makefile.in 944 configure 560 ltmain.sh
8 Makefile.template 8 configure.cmd* 0 src/
% ls -s src
total 80
48 Makefile.in 8 mbsystem_config.h
8 Makefile.template 8 mbsystem_config.h.in
0 gmt/ 0 mbvelocitytool/
0 gsf/ 0 mbview/
0 html/ 0 mr1pr/
0 macros/ 0 otps/
0 man/ 0 proj/
0 mbaux/ 0 ps/
0 mbedit/ 0 share/
0 mbio/ 8 stamp-h1
0 mbnavadjust/ 0 surf/
0 mbnavedit/ 0 utilities/
The src/html, src/man, and src/ps directories contain documentation in web page,
man page, and postscript formats respectively. The other directories under src
contain either C source files that are compiled into programs or Perl script
source files.
-------------------------------------------------------------------------------
MB-SYSTEM BUILD SYSTEMS:
-------------------------------------------------------------------------------
MB-System source distributions come with two build systems. Both create a
set of recursive makefiles so that the make utility can be used to compile and
install the package. The primary build system uses a configure script that has
been created using the GNU autotools package. Users customize the makefiles for
the local system by using arguments to configure. The older approach uses a
perl script called install_makefiles that must first be edited to reflect the
local system. The install_makefiles script is maintained for backward
compatibility, but we expect most users to use the configure script.
-------------------------------------------------------------------------------
BUILDING AND INSTALLING MB-SYSTEM WITH CONFIGURE
-------------------------------------------------------------------------------
The basic steps for building MB-System using the configure script are:
1. Move to the top of the MB-System distribution directory:
% cd mbsystem-5.4.2081
2. Run the configure script to generate the Makefile files throughout the
distribution directory structure. The command line options for configure
are discussed below.
% [...pre-options...]./configure [...options...]
3. Run the make utility to build the software within the source distribution.
% make
4. Run the make utility with the install option to install the software
within the target location that was specified while running configure.
% make
% make install
The configure script is intended to discern the enviroment, locate prerequisite
packages, and construct the makefiles with a minimum of user intervention. In
practice, users generally need to set at least some options when using the
configure script in order to successfully build, install, and run MB-System.
If NetCDF and GMT installations cannot be located, MB-System cannot be built. If
FFTW3, Motif, or OpenGL cannot be found MB-System will be built, but without
the applications that depend on these packages.
Depending on how user permissions are set on your system and where the package
is to be installed, it may be necessary to execute some or all of the above
commands with superuser privileges. On older styles of Unix and Linux, this
was typically accomplished by using the su command to become root, or
superuser, a step that requires knowing the root password for the system.
Following a successful invocation of su in a command shell, all commands have
superuser privileges. On MacOsX and other "modern" flavors of Unix and Linux,
it's more common to use the sudo command in front of other commands in order
to execute them with superuser privileges. An administrator password is
required for the first instance of sudo, but not for subsequent instances (at
least for a period of time, typically five minutes). In this case, the commands
become:
% sudo ./configure
% sudo make
% sudo make install
The available configure options are:
--prefix=install - location for mbsystem (/usr/local/mbsystem)"])
--with-netcdf-lib - location of NetCDF libs"])
--with-netcdf-include - location of NetCDF headers"])
--with-proj-lib - location of PROJ libs"])
--with-proj-include - location of PROJ headers"])
--with-gmt-lib - location of GMT libs"])
--with-gmt-include - location of GMT headers"])
--with-fftw-lib - location of FFTW3 libs (optional)"])
--with-fftw-include - location of FFTW3 headers (optional)"])
--with-motif-lib - location of Motif libs (optional)"])
--with-motif-include - location of Motif headers (optional)"])
--with-opengl-lib - location of OpenGL libs (optional)"])
--with-opengl-include - location of OpenGL headers (optional)"])
--with-otps-dir - location of OTPS installation (optional)"])
--without-gsf - build without including or supporting GSF"])
--enable-bundledproj - build using bundled proj package - the
default is to link with libproj"])
Users can also define custom compiler flags on the command line to be used by
configure. For example, the command:
% CFLAGS="-g -W -DBYTESWAPPED" ./configure \
--prefix=/usr/local/mbsystem
will override the system default CFLAGS with "-g, -W, and -DBYTESWAPPED", build
the package in the distribution directory with shared libraries, and install
the package in /usr/local/mbsystem. The destination directories will be:
/usr/local/mbsystem/bin executable binaries and scripts
/usr/local/mbsystem/lib libraries
/usr/local/mbsystem/include header files
/usr/local/mbsystem/share/mbsystem projection and levitus data
/usr/local/mbsystem/share/doc/mbsystem/html web page documentation
/usr/local/mbsystem/share/doc/mbsystem/ps postscript documentation
/usr/local/mbsystem/man man page documentation
If one is installing on a Mac in which some or all of the prerequisite packages
have been installed with Fink or MacPorts, then the locations of those
prerequisite packages must be explicitly defined. Fink installs packages in
/sw, and MacPorts installs into /opt. An example for installing in a Fink-centric
system is:
% CFLAGS="-g -I/opt/X11/include" \
LDFLAGS="-L/opt/X11/lib" \
./configure \
--prefix=/Users/caress/sandbox/mbsystem \
--with-netcdf-include=/sw/include \
--with-netcdf-lib=/sw/lib \
--with-proj-include=/sw/include \
--with-proj-lib=/sw/lib \
--with-gmt-include=/sw/include \
--with-gmt-lib=/sw/lib \
--with-fftw-include=/sw/include \
--with-fftw-lib=/sw/lib \
--with-motif-include=/sw/include \
--with-motif-lib=/sw/lib \
--with-otps-dir=/usr/local/OTPS
This is for MacOSX 10.9 (Mavericks), in which X11 must be obtained from X.org
and is installed in /opt. Previous versions of MacOsX installed X11 in /usr/X11R6.
The only non-Fink package specified is OTPS (which is not available through
package managers) in /usr/local.
-------------------------------------------------------------------------------
BUILDING AND INSTALLING MB-SYSTEM WITH INSTALL_MAKEFILES:
-------------------------------------------------------------------------------
The original, and now alternate, method for generating the makefiles is to use
a script named install_makefiles that is also present at the top of the
MB-System distribution. In contrast to configure, which can be controlled by
command line options, install_makefiles must be customized to the local
environment by manual editing before this perl script is executed.
In order to configure your installation. In particular, the user must explicitly
set the library locations, header file locations, compile flags, and link flags.
The important parameters to be set in install_makefiles are:
Required parameters:
$MBSYSTEM_HOME - absolute path to the MB-System installation location
$OS - Operating system (e.g. DARWIN, LINUX).
$CFLAGS - Compile flags for C source files.
$LFLAGS - Load flags for all object files.
$NETCDFLIBDIR - Location of NetCDF library.
$NETCDFINCDIR - Location of NetCDF header files.
$GMTLIBDIR - Location of GMT libraries.
$GMTINCDIR - Location of GMT header files.
Required parameters for spectrogram program mbsegypsd
- mbsegypsd will not be built if these are commented out
$FFTWLIBDIR - Location of the FFTW3 library.
$FFTWINCDIR - Location of FFTW3 header files.
Required parameters for graphical tools
- graphical tools will not be built if these
are commented out
$MOTIFINCDIR - Location of the Motif header files.
$MOTIFLIBS - Location of the Motif libraries.
Required parameter for visualization tools
- visualization tools will not be built if this
is commented out
$OPENGLLIBS - Link flags for the OpenGL libraries: "-lGLU -lGL";
Required parameter for mblevitus program
$LEVITUS - Location of the Levitus library (usually "$MBSYSTEM_HOME/share/LevitusAnnual82.dat").
Required parameter for mbotps program
$OTPSDIR - Location of the OTPSnc installation (usually "/usr/local/OTPSnc").
Optional name of C compiler (if other than "cc").
$CC - Usually "cc", but could be "gcc".
Optional parameters for use of independent GSF library installation
- GSF library included with MB-System will be used
if these are commented out
$GSFLIB - Location of GSF library.
$GSFINCDIR - Location of GSF header files.
Optional parameters for use of independent PROJ4 library installation
- PROJ4 library included with MB-System will be used
if these are commented out
$PROJLIB - Location of PROJ4 library.
$PROJINCDIR - Location of PROJ4 header files.
An example of the parameters for installing a distribution in /usr/local on a
current (MacOs X 10.8) Fink-centric Mac is:
$MBSYSTEM_HOME = "/usr/local/mbsystem-5.4.2081";
$OS = "DARWIN";
$CFLAGS = "-I/usr/X11R6/include ";
$LFLAGS = "-lm -L/sw/lib -lgdal";
$NETCDFLIBDIR = "/sw/lib";
$NETCDFINCDIR = "/sw/include";
$GMTLIBDIR = "/sw/lib";
$GMTINCDIR = "/usr/include";
$PROJECTIONS = "$MBSYSTEM_HOME/share/mbsystem/Projections.dat";
$FFTWLIBDIR = "/sw/lib";
$FFTWINCDIR = "/sw/include";
$MOTIFINCDIR = "/sw/include";
$MOTIFLIBS = "-L/sw/lib -L/usr/X11R6/lib -lXm -lXt -lX11";
$OPENGLLIBS = "-lGLU -lGL";
$LEVITUS = "$MBSYSTEM_HOME/share/mbsystem/LevitusAnnual82.dat";
$OTPSDIR = "/usr/local/OTPSnc";
To execute install_makefiles, do the following:
% cd mbsystem-5.4.2081
% ./install_makefiles
Because install_makefiles is a perl script, the executable perl must be
available in the installer's path. Once install_makefiles has been correctly
configured and run, give the command "make all" to generate the executable
programs:
% make all
The make command will descend recursively down through the directory structure,
compiling source files, linking object files, and copying executables and manual
pages to the appropriate directories.
The destination directories will be:
/usr/local/mbsystem-5.4.2081/bin executable binaries and scripts
/usr/local/mbsystem-5.4.2081/lib libraries
/usr/local/mbsystem-5.4.2081/include header files
/usr/local/mbsystem-5.4.2081/share/mbsystem projection and levitus data
/usr/local/mbsystem-5.4.2081/share/doc/mbsystem/html web page documentation
/usr/local/mbsystem-5.4.2081/share/doc/mbsystem/ps postscript documentation
/usr/local/mbsystem-5.4.2081/man man page documentation
-------------------------------------------------------------------------------
SETTING THE USER ENVIRONMENT:
-------------------------------------------------------------------------------
Naturally, in order for users to use the MB-System utilities, the directory
containing the executables must be included in their path. The executable perl
must also be available in the user's path for most of the macros to work. This
is generally achieved by editing the environment files in a user's home
directory. For csh users, the relevant files are .cshrc and .login; for sh or
bash users, the relevant files are .bashrc and .bash_profile.
Most users will also wish to specify which program they generally use to view
Postscript plots on their screen. This parameter can be set with the mbdefaults
program. The recommended Postscript viewer is a program called gv.
-------------------------------------------------------------------------------