From bab21cb5575c0d89297b7dcad02fd78c64d111b4 Mon Sep 17 00:00:00 2001
From: Angel Santamaria-Navarro <asantamaria@iri.upc.edu>
Date: Mon, 20 Mar 2017 19:14:42 +0100
Subject: [PATCH] Update README.md. Ready to be merged.
---
README.md | 329 +++++++++++++++++++++---------------------------------
1 file changed, 126 insertions(+), 203 deletions(-)
diff --git a/README.md b/README.md
index 1ac693b13..a9d46d063 100644
--- a/README.md
+++ b/README.md
@@ -39,317 +39,250 @@ Dependencies
#### Eigen
- [Eigen](http://eigen.tuxfamily.org). Linear algebra, header library. Eigen 3.2 is also a depencency of ROS-Hydro. In case you don't have ROS in your machine, you can install Eigen by typing:
+[Eigen](http://eigen.tuxfamily.org). Linear algebra, header library. Eigen 3.2 is also a depencency of ROS-Hydro. In case you don't have ROS in your machine, you can install Eigen by typing:
- ```terminal
$ sudo apt-get install libeigen3-dev
- ```
-
+
#### Ceres (5 steps)
[Ceres](http://www.ceres-solver.org/) is an optimization library. Currently, this dependency is optional, so the build procedure of Wolf skips part of compilation in case this dependency is not found on the system. **Installation** is desctibed at [Ceres site](http://www.ceres-solver.org/building.html). However we report here an alternative step by step procedure to install Ceres.
- **(1)** Skip this step if Cmake 2.8.0+ and Eigen3.0+ are already installed. Otherwise install them with *apt-get*.
-
- **(2) GFLAGS**
-
- - Git clone the source:
-
- ```terminal
- $ git clone [https://github.com/gflags/gflags.git](https://github.com/gflags/gflags.git)
- ```
-
- - Build and install with:
-
- ```terminal
- $ cd gflags
- $ mkdir build
- $ cd build
- $ cmake -DCMAKE_CXX_FLAGS="${CMAKE_CXX_FLAGS} -fPIC" -DGFLAGS_NAMESPACE="google" ..
- $Â make
- $ sudo make installÂ
- ```
+**(1)** Skip this step if Cmake 2.8.0+ and Eigen3.0+ are already installed. Otherwise install them with *apt-get*.
- libgflags.a will be installed at **/usr/local/lib**
+**(2) GFLAGS**
- **(3) GLOG**
+- Git clone the source:
- - Git clone the source:
+ $ git clone [https://github.com/gflags/gflags.git](https://github.com/gflags/gflags.git)
+
+- Build and install with:
+
+ $ cd gflags
+ $ mkdir build
+ $ cd build
+ $ cmake -DCMAKE_CXX_FLAGS="${CMAKE_CXX_FLAGS} -fPIC" -DGFLAGS_NAMESPACE="google" ..
+ $Â make
+ $ sudo make installÂ
+
+libgflags.a will be installed at **/usr/local/lib**
- ```terminal
- $ git clone [https://github.com/google/glog.git](https://github.com/google/glog.git)
- ```
+**(3) GLOG**
- - Build and install with:
+- Git clone the source:
- ```terminal
- $ cd glog
- $ ./configure --with-gflags=/usr/local/
- $Â make
- $ sudo make install
- ```
+ $ git clone [https://github.com/google/glog.git](https://github.com/google/glog.git)
+
+- Build and install with:
- libglog.so will be installed at **/usr/local/lib**
+ $ cd glog
+ $ ./configure --with-gflags=/usr/local/
+ $Â make
+ $ sudo make install
+
+libglog.so will be installed at **/usr/local/lib**
- - Tourbleshooting:
+- Tourbleshooting:
If the `make` command fails with the error: `/bin/bash: aclocal-1.14: command not found`, install Glog with the following commands:
- ```terminal
- $ cd glog
- $ sudo apt-get install autoconf
- $ autoreconf --force --install
- $ ./configure --with-gflags=/usr/local/
- $Â make
- $ sudo make install
- ```
-
- **(4) SUITESPARSE**
-
- - Easy way!:
+ $ cd glog
+ $ sudo apt-get install autoconf
+ $ autoreconf --force --install
+ $ ./configure --with-gflags=/usr/local/
+ $Â make
+ $ sudo make install
+
+**(4) SUITESPARSE**
- ```terminal
- $ sudo apt-get install libsuitesparse-dev
- ```
+- Easy way!:
- **(5) CERES**
+ $ sudo apt-get install libsuitesparse-dev
- - Git clone the source:
+**(5) CERES**
+
+- Git clone the source:
- ```terminal
- $ git clone [https://ceres-solver.googlesource.com/ceres-solver](https://ceres-solver.googlesource.com/ceres-solver)
- ```
+ $ git clone [https://ceres-solver.googlesource.com/ceres-solver](https://ceres-solver.googlesource.com/ceres-solver)
- - Build and install with:
-
- ```terminal
- $ cd ceres-solver
- $ mkdir build
- $ cd build
- $ cmake -DCMAKE_CXX_FLAGS="${CMAKE_CXX_FLAGS} -fPIC" ..
- $Â make
- $ sudo make installÂ
- ```
-
- libceres.a will be installed at **/usr/local/lib** and headers at **/usr/local/include/ceres**
+- Build and install with:
+
+ $ cd ceres-solver
+ $ mkdir build
+ $ cd build
+ $ cmake -DCMAKE_CXX_FLAGS="${CMAKE_CXX_FLAGS} -fPIC" ..
+ $Â make
+ $ sudo make installÂ
+
+libceres.a will be installed at **/usr/local/lib** and headers at **/usr/local/include/ceres**
#### Yaml-cpp
Wolf uses YAML files for configuration and for saving and loading workspaces. To obtain it run:
- - Ubuntu:
-
- ```terminal
- $ sudo apt-get install libyaml-cpp-dev
- ```
+- Ubuntu:
- - Mac:
+ $ sudo apt-get install libyaml-cpp-dev
+
+- Mac:
- ```terminal
- $ brew install yaml-cpp
- ```
+ $ brew install yaml-cpp
We are shipping the CMAKE file `FindYamlCpp.cmake` together with Wolf. Find it at `[wolf]/cmake_modules/FindYamlCpp.cmake`
#### Optional: Laser Scan Utils (Install only if you want to use IRI's laser scan utils)
- **(1)** Git clone the source:
+**(1)** Git clone the source:
- ```terminal
- $ git clone [https://gitlab.iri.upc.edu/mobile_robotics/laser_scan_utils.git](https://gitlab.iri.upc.edu/mobile_robotics/laser_scan_utils.git)
- ```
+ $ git clone [https://gitlab.iri.upc.edu/mobile_robotics/laser_scan_utils.git](https://gitlab.iri.upc.edu/mobile_robotics/laser_scan_utils.git)
- **(2)** Build and install:
-
- ```terminal
- $ cd laser_scan_utils/trunk/build
- $ cmake ..
- $Â make
- $ sudo make install
- ```
+**(2)** Build and install:
+ $ cd laser_scan_utils/trunk/build
+ $ cmake ..
+ $Â make
+ $ sudo make install
+
#### Optional: Raw GPS Utils (Install only if you want to use IRI's raw gps utils)
- **(1)** Git clone the source:
+**(1)** Git clone the source:
- ```terminal
$ git clone [https://github.com/pt07/raw_gps_utils.git](https://github.com/pt07/raw_gps_utils.git)
- ```
-
- **(2)** Build and install:
+
+**(2)** Build and install:
- ```terminal
$ cd raw_gps_utils/build
$ cmake ..
$Â make
$ sudo make install
- ```
-
-
+
Download and build
------------------
#### Wolf C++ Library
- **Download:**
+**Download:**
- ```terminal
$ git clone [https://gitlab.iri.upc.edu/mobile_robotics/wolf.git](https://gitlab.iri.upc.edu/mobile_robotics/wolf.git)
- ```
-
- **Build:**
+
+**Build:**
- ```terminal
$ cd wolf
$ mkdir build
$ cd build
$ cmake ..
$Â make
$ sudo make install  //optional in case you want to install wolf library
- ```
-
- **Set the WOLF_ROOT environment variable**
+
+**Set the WOLF_ROOT environment variable**
- We need a platform-independent way to specify where is the WOLF project, so that code can locate relevant files at run-time.
- For example, if we want to use YAML files for configuring sensors, `YAML::LoadFile(filename)` needs an absolute path to a `filename`. This name is platform-specific, and many times user-specific.
+We need a platform-independent way to specify where is the WOLF project, so that code can locate relevant files at run-time.
+For example, if we want to use YAML files for configuring sensors, `YAML::LoadFile(filename)` needs an absolute path to a `filename`. This name is platform-specific, and many times user-specific.
- Usually, these files are out of the WOLF project. But for testing purposes, some of these files exist within the WOLF directories.
+Usually, these files are out of the WOLF project. But for testing purposes, some of these files exist within the WOLF directories.
- Proceed as follows:
+Proceed as follows:
- 1. To run from __Terminal__ (the default), you need to create an environment variable WOLF_ROOT pointing to where the wolf project is.
+**(1)** To run from __Terminal__ (the default), you need to create an environment variable WOLF_ROOT pointing to where the wolf project is.
- Edit file `~/.bashrc`, or `~/.bash_profile`, and add these lines:
- ```
- export WOLF_ROOT="/abs/path/to/wolf"
- ```
+Edit file `~/.bashrc`, or `~/.bash_profile`, and add this line: `export WOLF_ROOT="/abs/path/to/wolf" `
- Then you need to source the file to get effect,
- ```
+Then you need to source the file to get effect,
+
source ~/.bash_profile // or ~/.bashrc, of course
- ```
- 2. If you are using Eclipse or other __GUIs__ and you want this environment variable to be accessed by them, edit the file `/etc/environment` (you need to use `sudo`) and add this line:
+**(2)** If you are using Eclipse or other __GUIs__ and you want this environment variable to be accessed by them, edit the file `/etc/environment` (you need to use `sudo`) and add this line: `WOLF_ROOT="/abs/path/to/wolf"`
- ```
- WOLF_ROOT="/abs/path/to/wolf"
- ```
- Then reboot your machine.
+Then reboot your machine.
- Alternatively, you can set up the environment variables in your GUIs only. Follow these guidelines:
+Alternatively, you can set up the environment variables in your GUIs only. Follow these guidelines:
- - If you run your application from __eclipse__, do:
- - Menu Run > Run configurations...
- - Add, or edit, a run configuration for the executable you want to run
- - Click on tab 'Environment'
- - Add a variable named `WOLF_ROOT`, with value `/abs/path/to/wolf`
+- If you run your application from __eclipse__, do:
+ - Menu Run > Run configurations...
+ - Add, or edit, a run configuration for the executable you want to run
+ - Click on tab 'Environment'
+ - Add a variable named `WOLF_ROOT`, with value `/abs/path/to/wolf`
- - If you run from __QtCreator__
- - Click on Left bar > Projects > Tab 'Build'
- - Under 'Build Environment', click 'Details'
- - Add variable `WOLF_ROOT` with value `/abs/path/to/wolf`
- - Click on Tab 'Run'
- - Select your Run configuration
- - Under 'Run Environment', make sure it says 'Use Build Environment'
- - If not, click on 'Details'
- - Under 'Base environment for this run configuration', select 'Build Environment'
+- If you run from __QtCreator__
+ - Click on Left bar > Projects > Tab 'Build'
+ - Under 'Build Environment', click 'Details'
+ - Add variable `WOLF_ROOT` with value `/abs/path/to/wolf`
+ - Click on Tab 'Run'
+ - Select your Run configuration
+ - Under 'Run Environment', make sure it says 'Use Build Environment'
+ - If not, click on 'Details'
+ - Under 'Base environment for this run configuration', select 'Build Environment'
#### Wolf ROS Node
- - Git clone the source (inside your ROS workspace):
+- Git clone the source (inside your ROS workspace):
- ```terminal
$ git clone [https://github.com/IRI-MobileRobotics/wolf_ros.git](https://github.com/IRI-MobileRobotics/wolf_ros.git)
- ```
Using the `catkin_tools` package
--------------------------------
- **(1)** Install `catkin_tools` :
+**(1)** Install `catkin_tools` :
- [`installation webpage.`](https://catkin-tools.readthedocs.io/en/latest/installing.html)
+[`installation webpage.`](https://catkin-tools.readthedocs.io/en/latest/installing.html)
- . Installing on Ubuntu with `apt-get`
+- Installing on Ubuntu with `apt-get`
- ```terminal
$ sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu `lsb_release -sc` main" > /etc/apt/sources.list.d/ros-latest.list'
$ wget http://packages.ros.org/ros.key -O - | sudo apt-key add -
$ sudo apt-get update
$ sudo apt-get install python-catkin-tools
- ```
-
- . Installing with [`pip`](https://pip.pypa.io/en/stable/installing/)
+
+- Installing with [`pip`](https://pip.pypa.io/en/stable/installing/)
- ```terminal
$ sudo pip install -U catkin_tools
- ```
-
- **(2)** Create a `catkin workspace` :
+
+**(2)** Create a `catkin workspace` :
- ```terminal
$ cd
$ mkdir -p wolf_ws/src
$ cd wolf_ws/src
$ catkin_init_workspace
$ cd ..
$ catkin_make
- ```
- **(3)** Setup your `bash_rc`:
+**(3)** Setup your `bash_rc`:
- Add at the end of the ~/.bashrc file with the following command:
+Add at the end of the ~/.bashrc file with the following command:
- ```terminal
- echo "source ~/wolf_ws/devel/setup.bash" >> ~/.bashrc
- ```
+ $ echo "source ~/wolf_ws/devel/setup.bash" >> ~/.bashrc
- Source your bash:
+Source your bash:
- ```terminal
source ~/.bashrc
- ```
+**(3)** Download `Ceres` :
- **(3)** Download `Ceres` :
-
- In the previously created directory `~/my_workspace_directory/wolf_ws/src/` clone `Ceres` & `wolf`.
+In the previously created directory `~/my_workspace_directory/wolf_ws/src/` clone `Ceres` & `wolf`.
- ```terminal
$ git clone [https://github.com/artivis/ceres_solver.git](https://github.com/artivis/ceres_solver.git)
- ```
- **(4)** Download `wolf` :
+**(4)** Download `wolf` :
- ```terminal
$ git clone [https://gitlab.iri.upc.edu/mobile_robotics/wolf.git](https://gitlab.iri.upc.edu/mobile_robotics/wolf.git)
- ```
- At this point you might need to switch to the `catkin_build` branch of the wolf project.
+At this point you might need to switch to the `catkin_build` branch of the wolf project.
- ```terminal
$ cd wolf
$ git checkout catkin_build
- ```
- (optional) Download `wolf_ros` :
+(optional) Download `wolf_ros` :
- ```terminal
$ git clone [https://github.com/IRI-MobileRobotics/Wolf_ros.git](https://github.com/IRI-MobileRobotics/Wolf_ros.git)
- ```
- **(5)** Let's Compile !
+**(5)** Let's Compile !
The command below can be launch from any sub-directory in `~/my_workspace_directory/wolf_ws/`.
- ```terminal
$ catkin build
- ```
- **(6)** Run tests:
+**(6)** Run tests:
- ```terminal
$ catkin run_tests
- ```
Inspiring Links
---------------
@@ -369,53 +302,43 @@ Kcachegrind is a graphical frontend for profiling your program and optimizing yo
- Ubuntu:
- Get the programs with
+Get the programs with
- ```terminal
$ sudo apt-get install valgrind kcachegrind
- ```
- Mac OSX
- In Mac, you can use qcachegrind instead. To get it through Homebrew, type
+In Mac, you can use qcachegrind instead. To get it through Homebrew, type
- ```terminal
$ brew install valgrind qcachegrind
- ```
-
- I don't know if these packages are available through MacPorts. Try
- ```terminal
+I don't know if these packages are available through MacPorts. Try
+
$ ports search --name valgrind
$ ports search --name qcachegrind
- ```
- If they are available, just do
+If they are available, just do
- ```terminal
$ sudo port install valgrind qcachegrind
- ```
#### Do the profiling and watch the reports
Type in your `wolf/bin/` directory:
- ```terminal
$ cd bin/
$ valgrind --tool=callgrind ./my_program <my_prg_params>
- ```
this produces a log report called `callgrind.out.XXXX`, where XXXX is a number. Then type
- Ubuntu
- ```terminal
+ ```shell
$ kcachegrind callgrind.out.XXXX
```
- Mac OSX
- ```terminal
+ ```shell
$ qcachegrind callgrind.out.XXXX
```
--
GitLab