From 7662059185f4230d93f5d7f8a87ce058efc7aa54 Mon Sep 17 00:00:00 2001 From: Richard Roberts Date: Sat, 4 Jan 2014 03:15:25 -0500 Subject: [PATCH] Working on markup README.md --- README.md | 187 +++++++++++------------------------------------------- 1 file changed, 36 insertions(+), 151 deletions(-) diff --git a/README.md b/README.md index 1f55b88d1..76c99e366 100644 --- a/README.md +++ b/README.md @@ -10,10 +10,33 @@ In the root library folder execute: $ mkdir build $ cd build $ cmake .. -$ make!check (optional, runs unit tests) +$ make check (optional, runs unit tests) $ make install ``` +Prerequisites: + +- [Boost](http://www.boost.org/users/download/) >= 1.43 (Ubuntu: `sudo apt-get install libboost-all-dev`) +- [CMake](http://www.cmake.org/cmake/resources/software.html) >= 2.6 (Ubuntu: `sudo apt-get install cmake`) + +Optional prerequisites - used automatically if findable by CMake: + +- [Intel Threaded Building Blocks (TBB)](http://www.threadingbuildingblocks.org/) (Ubuntu: `sudo apt-get install libtbb-dev`) +- [Intel Math Kernel Library (MKL)](http://software.intel.com/en-us/intel-mkl) + +Tested compilers + +- GCC 4.2-4.7 +- OSX Clang 2.9-3.2 +- OSX GCC 4.2 +- MSVC 2010, 2012 + +Tested systems: + +- Ubuntu 11.04 - 13.10 +- MacOS 10.6 - 10.9 +- Windows 7, 8 + See INSTALL for more detailed installation instructions. What is GTSAM? @@ -30,157 +53,19 @@ Please see the `examples/` directory and the USAGE file for examples on how to u The library 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 as follows: - - CCOLAMD 2.73: Tim Davis' constrained column approximate minimum degree ordering library +of licensing 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.2: General C++ matrix and linear algebra library - - Licenced under MPL2, provided in gtsam/3rdparty/Eigen/COPYING.README (some code that is 3rd-party to - Eigen is BSD and LGPL) - - -There are two supporting libraries: - - CppUnitLite unit test library customized for use with gtsam - wrap code generation utility for the Matlab interface to gtsam - -Important Installation Notes ----------------------------- - -1) -GTSAM requires the following libraries to be installed on your system: - - BOOST version 1.43 or greater (install through Linux repositories or MacPorts) - - Cmake version 2.6 or higher - - Support for XCode 4.3 command line tools on Mac requires CMake 2.8.8 or higher - -Optional dependent libraries: - - If TBB is installed and detectable by CMake GTSAM will use it automatically. - Ensure that CMake prints "Use Intel TBB : Yes". To disable the use of TBB, - disable the CMake flag GTSAM_WITH_TBB (enabled by default). On Ubuntu, TBB - may be installed from the Ubuntu repositories, and for other platforms it - may be downloaded from https://www.threadingbuildingblocks.org/ - -Tested compilers - - GCC 4.2-4.7 - - Clang 2.9-3.2 - - OSX GCC 4.2 - - MSVC 2010, 2012 - -Tested systems: - - Ubuntu 11.04, 11.10, 12.04, 12.10, 13.04 - - MacOS 10.6, 10.7 - - Windows 7 - -2) -GTSAM makes extensive use of debug assertions, and we highly recommend you work -in Debug mode while developing (enabled by default). Likewise, it is imperative -that you switch to release mode when running finished code and for timing. GTSAM -will run up to 10x faster in Release mode! See the end of this document for -additional debugging tips. - -3) -GTSAM has Doxygen documentation. To generate, run 'make doc' from your -build directory. - -4) -The instructions below install the library to the default system install path and -build 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 -$] cmake .. -$] make check (optional, runs unit tests) -$] make install - -This will build the library and unit tests, run all of the unit tests, -and then install the library itself. - -- CMake Configuration Options and Details - -GTSAM has a number of options that can be configured, which is best done with -one of the following: - - ccmake the curses GUI for cmake - cmake-gui a real GUI for cmake - -Important Options: - -CMAKE_BUILD_TYPE: We support several build configurations for GTSAM (case insensitive) - Debug (default) All error checking options on, no optimization. Use for development. - Release Optimizations turned on, no debug symbols. - Timing Adds ENABLE_TIMING flag to provide statistics on operation - Profiling Standard configuration for use during profiling - RelWithDebInfo Same as Release, but with the -g flag for debug symbols - -CMAKE_INSTALL_PREFIX: The install folder. The default is typically /usr/local/ -To configure to install to your home directory, you could execute: -$] cmake -DCMAKE_INSTALL_PREFIX:PATH=$HOME .. - -GTSAM_TOOLBOX_INSTALL_PATH: The Matlab toolbox will be installed in a subdirectory -of this folder, called 'gtsam'. -$] cmake -DGTSAM_TOOLBOX_INSTALL_PATH:PATH=$HOME/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. - -GTSAM_BUILD_UNSTABLE: Enable build and install for libgtsam_unstable library. -Set with the command line as follows: -$] cmake -DGTSAM_BUILD_UNSTABLE:OPTION=ON .. - ON When enabled, libgtsam_unstable will be built and installed with the - same options as libgtsam. In addition, if tests are enabled, the - unit tests will be built as well. The Matlab toolbox will also - be generated if the matlab toolbox is enabled, installing into a - folder called "gtsam_unstable". - OFF (Default) If disabled, no gtsam_unstable code will be included in build or install. - -Check - -"make check" will build and run all of the tests. Note that the tests will only be -built when using the "check" targets, to prevent "make install" from building the tests -unnecessarily. You can also run "make timing" to build all of the timing scripts. -To run check on a particular module only, run "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". - -MEX_COMMAND: Path to the mex compiler. Defaults to assume the path is included in your -shell's PATH environment variable. mex is installed with matlab at -$MATLABROOT/bin/mex - -$MATLABROOT can be found by executing the command 'matlabroot' in MATLAB - -Debugging tips: - -Another useful debugging symbol is _GLIBCXX_DEBUG, which enables debug checks -and safe containers in the standard C++ library and makes problems much easier -to find. - -NOTE: The native Snow Leopard g++ compiler/library contains a bug that makes -it impossible to use _GLIBCXX_DEBUG. MacPorts g++ compilers do work with it though. - -NOTE: If _GLIBCXX_DEBUG is used to compile gtsam, anything that links against -gtsam will need to be compiled with _GLIBCXX_DEBUG as well, due to the use of -header-only Eigen. +- Eigen 3.2: General C++ matrix and linear algebra library + - Licenced under MPL2, provided in gtsam/3rdparty/Eigen/COPYING.README (some code that is 3rd-party to Eigen is BSD and LGPL)