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