Updated install instructions for cmake
parent
3baba11815
commit
74a5a81745
237
INSTALL
237
INSTALL
|
@ -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
173
README
|
@ -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.
|
||||
|
||||
|
||||
|
|
Loading…
Reference in New Issue