12345qiupeng
/
gtsam
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated install instructions for cmake

release/4.3a0
Alex Cunningham 2012-03-27 18:45:03 +00:00
parent 3baba11815
commit 74a5a81745
2 changed files with 117 additions and 293 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

237
INSTALL
View File

@ -1,237 +0,0 @@
Installation Instructions
*************************
Copyright (C) 1994, 1995, 1996, 1999, 2000, 2001, 2002, 2004, 2005,
2006 Free Software Foundation, Inc.
This file is free documentation; the Free Software Foundation gives
unlimited permission to copy, distribute and modify it.
Basic Installation
==================
IMPORTANT NOTE: GTSAM has some special compilation requirements, see
the README file.
Briefly, the shell commands `./configure; make; make install' should
configure, build, and install this package. The following
more-detailed instructions are generic; see the `README' file for
instructions specific to this package.
The `configure' shell script attempts to guess correct values for
various system-dependent variables used during compilation. It uses
those values to create a `Makefile' in each directory of the package.
It may also create one or more `.h' files containing system-dependent
definitions. Finally, it creates a shell script `config.status' that
you can run in the future to recreate the current configuration, and a
file `config.log' containing compiler output (useful mainly for
debugging `configure').
It can also use an optional file (typically called `config.cache'
and enabled with `--cache-file=config.cache' or simply `-C') that saves
the results of its tests to speed up reconfiguring. Caching is
disabled by default to prevent problems with accidental use of stale
cache files.
If you need to do unusual things to compile the package, please try
to figure out how `configure' could check whether to do them, and mail
diffs or instructions to the address given in the `README' so they can
be considered for the next release. If you are using the cache, and at
some point `config.cache' contains results you don't want to keep, you
may remove or edit it.
The file `configure.ac' (or `configure.in') is used to create
`configure' by a program called `autoconf'. You need `configure.ac' if
you want to change it or regenerate `configure' using a newer version
of `autoconf'.
The simplest way to compile this package is:
1. `cd' to the directory containing the package's source code and type
`./configure' to configure the package for your system.
Running `configure' might take a while. While running, it prints
some messages telling which features it is checking for.
2. Type `make' to compile the package.
3. Optionally, type `make check' to run any self-tests that come with
the package.
4. Type `make install' to install the programs and any data files and
documentation.
5. You can remove the program binaries and object files from the
source code directory by typing `make clean'. To also remove the
files that `configure' created (so you can compile the package for
a different kind of computer), type `make distclean'. There is
also a `make maintainer-clean' target, but that is intended mainly
for the package's developers. If you use it, you may have to get
all sorts of other programs in order to regenerate files that came
with the distribution.
Compilers and Options
=====================
Some systems require unusual options for compilation or linking that the
`configure' script does not know about. Run `./configure --help' for
details on some of the pertinent environment variables.
You can give `configure' initial values for configuration parameters
by setting variables in the command line or in the environment. Here
is an example:
./configure CC=c99 CFLAGS=-g LIBS=-lposix
*Note Defining Variables::, for more details.
Compiling For Multiple Architectures
====================================
You can compile the package for more than one kind of computer at the
same time, by placing the object files for each architecture in their
own directory. To do this, you can use GNU `make'. `cd' to the
directory where you want the object files and executables to go and run
the `configure' script. `configure' automatically checks for the
source code in the directory that `configure' is in and in `..'.
With a non-GNU `make', it is safer to compile the package for one
architecture at a time in the source code directory. After you have
installed the package for one architecture, use `make distclean' before
reconfiguring for another architecture.
Installation Names
==================
By default, `make install' installs the package's commands under
`/usr/local/bin', include files under `/usr/local/include', etc. You
can specify an installation prefix other than `/usr/local' by giving
`configure' the option `--prefix=PREFIX'.
You can specify separate installation prefixes for
architecture-specific files and architecture-independent files. If you
pass the option `--exec-prefix=PREFIX' to `configure', the package uses
PREFIX as the prefix for installing programs and libraries.
Documentation and other data files still use the regular prefix.
In addition, if you use an unusual directory layout you can give
options like `--bindir=DIR' to specify different values for particular
kinds of files. Run `configure --help' for a list of the directories
you can set and what kinds of files go in them.
If the package supports it, you can cause programs to be installed
with an extra prefix or suffix on their names by giving `configure' the
option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.
Optional Features
=================
Some packages pay attention to `--enable-FEATURE' options to
`configure', where FEATURE indicates an optional part of the package.
They may also pay attention to `--with-PACKAGE' options, where PACKAGE
is something like `gnu-as' or `x' (for the X Window System). The
`README' should mention any `--enable-' and `--with-' options that the
package recognizes.
For packages that use the X Window System, `configure' can usually
find the X include and library files automatically, but if it doesn't,
you can use the `configure' options `--x-includes=DIR' and
`--x-libraries=DIR' to specify their locations.
Specifying the System Type
==========================
There may be some features `configure' cannot figure out automatically,
but needs to determine by the type of machine the package will run on.
Usually, assuming the package is built to be run on the _same_
architectures, `configure' can figure that out, but if it prints a
message saying it cannot guess the machine type, give it the
`--build=TYPE' option. TYPE can either be a short name for the system
type, such as `sun4', or a canonical name which has the form:
CPU-COMPANY-SYSTEM
where SYSTEM can have one of these forms:
OS KERNEL-OS
See the file `config.sub' for the possible values of each field. If
`config.sub' isn't included in this package, then this package doesn't
need to know the machine type.
If you are _building_ compiler tools for cross-compiling, you should
use the option `--target=TYPE' to select the type of system they will
produce code for.
If you want to _use_ a cross compiler, that generates code for a
platform different from the build platform, you should specify the
"host" platform (i.e., that on which the generated programs will
eventually be run) with `--host=TYPE'.
Sharing Defaults
================
If you want to set default values for `configure' scripts to share, you
can create a site shell script called `config.site' that gives default
values for variables like `CC', `cache_file', and `prefix'.
`configure' looks for `PREFIX/share/config.site' if it exists, then
`PREFIX/etc/config.site' if it exists. Or, you can set the
`CONFIG_SITE' environment variable to the location of the site script.
A warning: not all `configure' scripts look for a site script.
Defining Variables
==================
Variables not defined in a site shell script can be set in the
environment passed to `configure'. However, some packages may run
configure again during the build, and the customized values of these
variables may be lost. In order to avoid this problem, you should set
them in the `configure' command line, using `VAR=value'. For example:
./configure CC=/usr/local2/bin/gcc
causes the specified `gcc' to be used as the C compiler (unless it is
overridden in the site shell script).
Unfortunately, this technique does not work for `CONFIG_SHELL' due to
an Autoconf bug. Until the bug is fixed you can use this workaround:
CONFIG_SHELL=/bin/bash /bin/bash ./configure CONFIG_SHELL=/bin/bash
`configure' Invocation
======================
`configure' recognizes the following options to control how it operates.
`--help'
`-h'
Print a summary of the options to `configure', and exit.
`--version'
`-V'
Print the version of Autoconf used to generate the `configure'
script, and exit.
`--cache-file=FILE'
Enable the cache: use and save the results of the tests in FILE,
traditionally `config.cache'. FILE defaults to `/dev/null' to
disable caching.
`--config-cache'
`-C'
Alias for `--cache-file=config.cache'.
`--quiet'
`--silent'
`-q'
Do not print messages saying which checks are being made. To
suppress all normal output, redirect it to `/dev/null' (any error
messages will still be shown).
`--srcdir=DIR'
Look for the package's source code in directory DIR. Usually
`configure' can determine that directory automatically.
`configure' also accepts some other, not widely useful, options. Run
`configure --help' for more details.

173
README
View File

@ -13,33 +13,33 @@ Please see USAGE for an example on how to use GTSAM.
The code is organized according to the following directory structure:
3rdparty local copies of third party libraries - Eigen3 and CCOLAMD
base provides some base Math and data structures, as well as test-related utilities
geometry points, poses, tensors, etc
inference core graphical model inference such as factor graphs, junction trees, Bayes nets, Bayes trees
linear inference specialized to Gaussian linear case, GaussianFactorGraph etc...
nonlinear non-linear factor graphs and non-linear optimization
slam SLAM and visual SLAM application code
3rdparty local copies of third party libraries - Eigen3 and CCOLAMD
base provides some base Math and data structures, as well as test-related utilities
geometry points, poses, tensors, etc
inference core graphical model inference such as factor graphs, junction trees, Bayes nets, Bayes trees
linear inference specialized to Gaussian linear case, GaussianFactorGraph etc...
nonlinear non-linear factor graphs and non-linear optimization
slam SLAM and visual SLAM application code
This library contains unchanged copies of two third party libraries, with documentation
of licensing in LICENSE and as follows:
- CCOLAMD 2.73: Tim Davis' constrained column approximate minimum degree ordering library
- http://www.cise.ufl.edu/research/sparse
- Licenced under LGPL v2.1, provided in gtsam/3rdparty/CCOLAMD/Doc/lesser.txt
- Eigen 3.0.3: General C++ matrix and linear algebra library
- Eigen 3.0.5: General C++ matrix and linear algebra library
- Licenced under LGPL v3, provided in gtsam/3rdparty/Eigen/COPYING.LGPL
All of the above contain code and tests, and build local shared libraries that are then
bundled in a top-level shared library libgtsam.la. After this is built, you can also run
the more involved tests, which test the entire library:
All of the above contain code and tests, and produce a single library libgtsam.
After this is built, you can also run the more involved tests, which test the entire library:
tests more involved tests that depend on slam
examples Demo applications as a tutorial for using gtsam
tests more involved tests that depend on slam
examples Demo applications as a tutorial for using gtsam
cmake CMake scripts used within the library, as well as for finding GTSAM by dependent projects
Finally, there are some local libraries built needed in the rest of the code:
CppUnitLite unit test library
m4 local M4 macros
CppUnitLite unit test library customized for use with gtsam
wrap code generation utility for the Matlab interface to gtsam
Important Installation Notes Specific to GTSAM
----------------------------------------------
@ -47,8 +47,14 @@ Important Installation Notes Specific to GTSAM
1)
GTSAM requires the following libraries to be installed on your system:
- BOOST version 1.40 or greater (install through Linux repositories or MacPorts)
- Automake
- libtool
GTSAM uses CMake (http://www.cmake.org/) for build automation
- Installed cmake version must be 2.6 or higher
Tested compilers
- gcc
- clang
- OSX gcc
2)
GTSAM makes extensive use of debug assertions, even for checking input of
@ -71,54 +77,109 @@ gtsam will need to be compiled with _GLIBCXX_DEBUG as well, due to the use of
header-only Eigen.
3)
Putting the above together, here are some sample ./configure commands for
compiling gtsam:
GTSAM has been written to support the creation of API documentation using
doxygen. To create html documentation for GTSAM, run the the script
makedoc.sh.
NOTE: If checked out from SVN, before attempting to compile run the command ./autogen.sh
4)
For developers, we primarily use the Eclipse IDE for development, and provide
an Eclipse project file with a variety of make targets to build and debug
from within Eclipse.
For Debugging (native Snow Leopard g++ compiler):
./configure CXXFLAGS="-fno-inline -g -Wall" \
LDFLAGS="-fno-inline -g -Wall"
5)
After installing prerequisites for building GTSAM, you can configure and build
GTSAM using CMake with the default options with the quickstart options. For
details on the full functionality of CMake, see the CMake documentation.
For Debugging (Linux or MacPorts g++ compilers):
./configure CXXFLAGS="-fno-inline -g -Wall -D_GLIBCXX_DEBUG" \
LDFLAGS="-fno-inline -g -Wall"
For Performance:
./configure CXXFLAGS="-DNDEBUG -O3" LDFLAGS="-O3"
After that (this would be for an in-source build, see next for out-of-source):
$ make
$ make check (optional, runs unit tests)
$ make install
Out-of-source build:
--------------------
The above will put object files and executables in the source directories. If you like, it is
very easy to configure the libraries to put all these in a parallel build tree so they do not
clutter the source tree. To do this, instead of running configure in the gtsam directory itself,
run it in sub-directory of choice, e.g., starting out in the main GTSAM folder:
- CMake Quickstart
Installs to the default system install path and builds all components. From a terminal,
starting in the root library folder, execute commands as follows for an out-of-source
build:
$] mkdir build
$] cd build
if you want to install:
$] ../configure ..... (command as above)
$] cmake ..
$] make check (optional, runs unit tests)
$] make install
or if you dont want to install then you can:
This will build the library and unit tests, run all of the unit tests, and then install
the library itself, as well as the Matlab toolbox.
$] ../configure ..... (command as above)
$] ../configure --disable-shared
$] make (or make check)
- Additional CMake Options and Details
Built-in Unit Tests:
--------------------
There is one more optional step in which you can invoke the unit tests included in the gtsam libraries.
$] make check
By verifying all the test results are positive, you can make sure that the functionalities of the GTSAM
libraries are correct.
The cmake scripts force a out-of-source build, so inside gtsam,
create a new folder called "build", and run cmake. From the command line:
$] mkdir build
$] cd build
$] cmake ..
Note the ".." after the cmake command - it tells cmake to look for the
root CMakeLists.txt file in the root gtsam folder instead of in the build folder.
This is a necessary argument for starting cmake in all of its variations.
There a few ways of actually doing the configuration to make adjusting options easier.
cmake the regular command-line version of cmake, allows configuration with scripts
ccmake the curses GUI for cmake, which lets you see the various options, change them, and run configuration.
cmake-gui a real GUI for cmake, which has a similar interface to ccmake, but with easier controls.
Note that during configuration, the settings get cached so if you rerun cmake later,
it will keep your previous settings. In particular, you can use the "cmake" build target
within the Eclipse project to update the configuration, which will be necessary
when file structures change.
While it is possible to use command-line arguments to cmake to change configuration
options, it is usually easier to use cmake-gui or ccmake to set parameters and use the other flags.
Important CMake configuration options:
CMAKE_INSTALL_PREFIX: this is the folder where installed files will go, and for
our development purposes, should be set to the home folder, like so
$] cmake -DCMAKE_INSTALL_PREFIX:PATH=$HOME ..
GTSAM_TOOLBOX_INSTALL_PATH: When the library is installed with "make install",
the generated matlab toolbox code (created by wrap) gets installed as well in
this path. For example, use "/home/username/borg/toolbox" to install the
toolbox in your borg/toolbox folder. The matlab toolbox will get installed
into borg/toolbox/gtsam.
$] cmake -DGTSAM_TOOLBOX_INSTALL_PATH:PATH=$HOME/borg/toolbox ..
GTSAM_BUILD_CONVENIENCE_LIBRARIES: This is a build option to allow for tests in
subfolders to be linked against convenience libraries rather than the full libgtsam.
Set with the command line as follows:
$] cmake -DGTSAM_BUILD_CONVENIENCE_LIBRARIES:OPTION=ON ..
ON (Default) This builds convenience libraries and links tests against them. This
option is suggested for gtsam developers, as it is possible to build
and run tests without first building the rest of the library, and
speeds up compilation for a single test. The downside of this option
is that it will build the entire library again to build the full
libgtsam library, so build/install will be slower.
OFF This will build all of libgtsam before any of the tests, and then
link all of the tests at once. This option is best for users of GTSAM,
as it avoids rebuilding the entirety of gtsam an extra time.
Build and Install
After configuring, you use make just as you normally would, and the all, check and
install targets work as in autotools. Note that all targets are at the root level
of the build folder. You can also build any of the subfolders individually as
individual targets, such as "make geometry slam" to build both geometry and slam.
Running "make install" will install the library to the prefix location.
Check
As with autotools, "make check" will build and run all of the tests. You can also
run "make timing" to build all of the timing scripts. To run check on a particular
subsection, there is a convention of "make check.[subfolder]", so to run just the
geometry tests, run "make check.geometry". Individual tests can be run by
appending ".run" to the name of the test, for example, to run testMatrix,
run "make testMatrix.run".
The make target "wrap" will build the wrap binary, and the "wrap_gtsam" target will
generate code for the toolbox. By default, the toolbox will be created and installed
by the install target for the library. To change the install folder for the toolbox,
choose a different setting during cmake settings for the toolbox install path.