Skip to content
Newer
Older
100644 220 lines (189 sloc) 11.3 KB
5aa900c @novas0x2a turn on autoreconf --force, and rename our install file so autoreconf…
novas0x2a authored
1 # __BEGIN_LICENSE__
426c2c3 all: Relicense VW as Apache 2
Zack Moratto authored
2 # Copyright (c) 2006-2012, United States Government as represented by the
3 # Administrator of the National Aeronautics and Space Administration. All
4 # rights reserved.
5 #
6 # The NASA Vision Workbench is licensed under the Apache License,
7 # Version 2.0 (the "License"); you may not use this file except in
8 # compliance with the License. You may obtain a copy of the License at
9 # http://www.apache.org/licenses/LICENSE-2.0
10 #
11 # Unless required by applicable law or agreed to in writing, software
12 # distributed under the License is distributed on an "AS IS" BASIS,
13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 # See the License for the specific language governing permissions and
15 # limitations under the License.
5aa900c @novas0x2a turn on autoreconf --force, and rename our install file so autoreconf…
novas0x2a authored
16 # __END_LICENSE__
17
18
19 Requirements
20 ============
21
426c2c3 all: Relicense VW as Apache 2
Zack Moratto authored
22 If you are reading this document then you already have a copy of the
23 Vision Workbench sources. You may want to confirm that you have the
24 most most up-to-date distribution, which will always be available from
5aa900c @novas0x2a turn on autoreconf --force, and rename our install file so autoreconf…
novas0x2a authored
25 the NASA Ames open-source software website, at:
426c2c3 all: Relicense VW as Apache 2
Zack Moratto authored
26 http://irg.arc.nasa.gov/nasa-vision-workbench
5aa900c @novas0x2a turn on autoreconf --force, and rename our install file so autoreconf…
novas0x2a authored
27 There you will also be able to download an up-to-date copy of the
28 user's guide, called the Vision Workbook, which contains a more
29 complete description of how to get started with the Vision Workbench.
30
31 You will also need to obtain and install whichever pre-requisite
32 libraries you will need. The only strict requirement is the Boost C++
33 Libraries, a set of extensions to the standard C++ libraries that is
34 available at www.boost.org. Many modern Linux systems come with some
35 version of Boost already installed, generally in the directory
36 /usr/include/boost. The Vision Workbench has been tested with Boost
37 versions 1.32 and later.
38
39 Other libraries are required only if you want to use particular
40 features of the Vision Workbench. A summary of the various libraries
41 that the Vision Workbench will detect and use if present is given in
42 following table. It lists the particular Vision Workbench module that
43 uses the library, whether it is required or optional for that module,
44 and where the library can be obtained. If you are just starting out
45 with the Vision Workbench, it is generally fine to begin only with
46 Boost and support for one or two file formats. You can always go back
47 and rebuild the Vision Workbench with support for additional features
48 later if you discover that you need them.
49
50 Name | Used By | Source
51 ---------+-----------------------+------------------------------------
7fd42b8 @jwakely Fix typo in URI scheme.
jwakely authored
52 Boost | All | http://www.boost.org/
5aa900c @novas0x2a turn on autoreconf --force, and rename our install file so autoreconf…
novas0x2a authored
53 LAPACK | Portions of Math, HDR | See notes below
54 PNG | FileIO (opt.) | http://www.libpng.org/
55 JPEG | FileIO (opt.) | http://www.ijg.org/
56 TIFF | FileIO (opt.) | http://www.libtiff.org/
57 OpenEXR | FileIO (opt.) | http://www.openexr.com/
58 PROJ.4 | Cartography (req.) | http://www.remotesensing.org/proj/
59 GDAL | Cartography (opt.) | http://www.remotesensing.org/gdal/
60
61 One dependency that is worth discussing briefly is LAPACK, which
62 provides the Vision Workbench with a computational linear algebra back
63 end. LAPACK is a comprehensive and widely-used linear algebra support
64 library in the public domain. LAPACK also requires the Basic Linear
65 Algebra Subroutines (BLAS) library, which is usually bundled with
66 LAPACK.
67
68 The basic matrix and vector algebra in the Math module does not depend
69 on LAPACK and BLAS. However, the routines in <vw/Math/LinearAlgebra.h>
70 will only be built if LAPACK is detected by the build system. For
71 your convenience, we provide a stand-alone LAPACK and BLAS
72 distribution on the Vision Workbench website listed at the top of this
73 document. This distribution has been tested with the Vision
74 Workbench, so we recommend its use if you are installing LAPACK for
75 the first time. However, other versions of LAPACK and BLAS that come
76 pre-installed on your system will probably work just as well. In
77 particular, Mac OS X users {\em do not} need to install LAPACK;
78 optimized linear algebra support is provided by Apple's "veclib"
79 framework on Mac OS X. Remember to add the "-framework veclib" flag
80 when linking your application against the Vision Workbench if you are
81 using these functions on the Mac platform.
82
83
84 Building the Vision Workbench
85 =============================
86
87 First configure the build system by running "./configure" from the
88 base directory of the source distribution. This script will examine
89 your machine to determine what build tools to use and what libraries
90 are installed as well as where they are located. Near the end of its
91 output it will list whether or not it was able to find each library
92 and which Vision Workbench modules it is going to build. You should
93 examine this output to confirm that it was able to find all the
94 libraries that you had expected it to. If not then you may need to
95 configure the build system to search in the right places, as discussed
96 in the next section.
97
98 Assuming the output of the configure script looks good, you can now
99 proceed to build the Vision Workbench itself by running "make". Most
100 of the Vision Workbench is header-only, so "building" the Vision
101 Workbench should be relatively quick. Once the build is complete,
102 confirm that things are working properly by building and running the
103 unit tests by typing "make check". If there are no errors, the final
104 step is to install the Vision Workbench headers, library, and sample
105 programs using "make install". By default the installation location
106 is the directory /usr/local, so you will need to obtain the necessary
107 privileges to write to this directory using a command such as "sudo"
108 or "su". If you do not have administrator privileges on you computer
109 then see the next section for information on how to specify an
110 alternative installation directory.
111
112 Building the Vision Workbench under Windows is possible, but it is not
113 currently automatically supported. The easiest thing to do is to
114 include the .cc files from the Vision Workbench modules that you want
115 to use directly in your own project file. You will of course still
116 need to install the Boost libraries as well as any other libraries you
117 want to use. Pre-built Windows versions of a number of libraries,
118 such as the JPEG, PNG, and TIFF libraries, are available online from
119 the GnuWin32 project at gnuwin32.sourceforge.net. You will need to
120 configure your project's include file and library search paths
121 appropriately. Also be sure to configure your project to define the
122 preprocessor symbol "NOMINMAX" to disable the non-portable Windows
123 definitions of min() and max() macros, which interfere with the
8879c42 @novas0x2a make some windows compat fixes
novas0x2a authored
124 standard C++ library functions of the same names. In addition, you
125 will need to define the preprocessor symbol "_USE_MATH_DEFINES" to
126 ensure that math.h defines constants such as M_PI.
5aa900c @novas0x2a turn on autoreconf --force, and rename our install file so autoreconf…
novas0x2a authored
127
128
129 Configuring the Build System
130 ============================
131
132 The Vision Workbench build system offers a variety of configuration
133 options that you provide as command-line flags to the "configure"
134 script. We'll discuss a few of the most important options here, but
135 for a complete list you can run "./configure --help". As an
136 alternative to specifying command-line flags every time, you may
137 instead create a file called "config.options" with your preferences in
138 the base directory of the Vision Workbench repository. A file called
139 "config.options.example" is provided that you can copy and edit to
140 your liking. Note that none of this has any impact on Visual Studio
141 users, who must instead configure their projects by hand.
142
143 The single most important option is the "--with-paths=PATHS" flag,
144 where you replace "PATHS" with a whitespace-separated list of paths
145 that the build system should search when looking for installed
146 libraries. For example if you specify "--with-paths=/foo/bar" then it
147 will search for header files in "/foo/bar/include", library files in
148 "/foo/bar/lib", and so on. The default search path includes a number
149 of common locations for user-installed libraries, such as
150 "/usr/local", "$(HOME)/local", and "/sw". The "PKG_PATHS"
151 configuration file variable has the same effect as this option.
152
153 The next most important options have the form "--enable-module-foo[=no]",
154 where "foo" is replaced by the lower-case name of a module such as
155 "mosaic" or "hdr". This allows you to control whether or not certain
156 modules are built. Disabling modules that you do not use can speed up
157 compilation and testing time, which is especially useful if you are
158 making changes to the Vision Workbench source and need to recompile
159 often. The corresponding configuration file variables have the form
160 "ENABLE_MODULE_FOO", in all-caps, and are set to either "yes" or "no".
161
162 Two handy options, "--enable-optimize" and "--enable-debug", determine
163 the compiler options used when building the few library files. You
164 can again specify an optional argument of the form "=no" to disable
165 the corresponding feature, and you can also specify a particular
166 optimization level in the same manner. For example, if you want to
167 make it as easy as possible to debug Vision Workbench code using a
168 debugger you might use "--enable-optimize=no --enable-debug" to
169 disable all optimizations and include debugging symbols. The
170 corresponding configuration file variables are "ENABLE_OPTIMIZE" and
171 "ENABLE_DEUBG". Keep in mind that since most Vision Workbench code is
172 header-only you should remember to configure your own project
173 similarly or you may not notice any difference. For normal
174 non-debugging use, we strongly recommend that you enable moderate
175 compiler optimization; much of the heavily templatized and generic
176 Vision Workbench code requires basic optimizations such as function
177 inlining to achieve a reasonable level of performance.
178
179 Finally, to specify that the build system should install the Vision
180 Workbench someplace other than "/usr/local", specify the path using
181 the "--prefix=PATH" option. The corresponding configuration file
182 variable is, of course, called "PREFIX".
183
184
185 Common Problems
186 ===============
187
426c2c3 all: Relicense VW as Apache 2
Zack Moratto authored
188 * I have (library X) installed in one location that I want to use, and
189 there's another version installed system-wide. How do I get Vision
5aa900c @novas0x2a turn on autoreconf --force, and rename our install file so autoreconf…
novas0x2a authored
190 Workbench to build with the version I want?
191
426c2c3 all: Relicense VW as Apache 2
Zack Moratto authored
192 Due to limitations in the underlying build system tools, the
193 autodetection will always detect the system-installed library and ignore
194 different installations, even if the PKG_PATHS environment variable is
195 set. To get around this, set the following environment variables (where
196 X is the name of the library as known by the configure script's
5aa900c @novas0x2a turn on autoreconf --force, and rename our install file so autoreconf…
novas0x2a authored
197 --with-X, in caps):
198
199 HAVE_PKG_X=yes
200 PKG_X_CPPFLAGS="-I/path/to/include/directory"
201 PKG_X_LDFLAGS="-L/path/to/library/directory"
202
426c2c3 all: Relicense VW as Apache 2
Zack Moratto authored
203 (These can be set in the config.options file.) Vision Workbench should
5aa900c @novas0x2a turn on autoreconf --force, and rename our install file so autoreconf…
novas0x2a authored
204 then link against the library in the location specified in this manner.
205
206
207 * Vision Workbench crashes when opening a TIFF/GeoTIFF file!
208
426c2c3 all: Relicense VW as Apache 2
Zack Moratto authored
209 When linking against a GDAL library that uses an internal libtiff, the
210 opening of TIFF files can fail to function correctly when Vision
211 Workbench also links against another libtiff. To see whether or not
212 GDAL is using an internal libtiff, run ldd on the gdal library and
213 check its linkage; if it does not link, then check gdalinfo --format.
214 If GTiff is supported, and ldd says that the gdal library is not linked
5aa900c @novas0x2a turn on autoreconf --force, and rename our install file so autoreconf…
novas0x2a authored
215 against libtiff, then GDAL is using an internal libtiff library.
216
426c2c3 all: Relicense VW as Apache 2
Zack Moratto authored
217 In that case, you will want to disable libtiff. Add "--without-tiff" to
218 the ./configure command line. This does not effect the functionality of
5aa900c @novas0x2a turn on autoreconf --force, and rename our install file so autoreconf…
novas0x2a authored
219 Vision Workbench, as it will use GDAL to open TIFF files instead.
Something went wrong with that request. Please try again.