Building from the source code for Ubuntu Linux

Although there are lots of Linux distributions, currently Choreonoid officially supports Ubuntu Linux among them. Now we confirmed the building and execution for Ubuntu Linux 10.04 to 11.10. We will support the future later versions and older versions after the last desktop LTS version will be supported.

This document describes how to build Choreonoid for Ubuntu Linux from the source code. Choreonoid can probably be built on other distributions by considering key points of the building, so please try to do it if necessary.

Preparation

Getting and extracting the source code

Download a source archive from the ../download page and extract it in some directory.

For example, you can extract the archive by typing

$ unzip choreonoid-x.x.x.zip

in the command-line. (x.x.x corresponds the version number.)

Here we assume the directory to extract as ~/src/choreonoid, and set it to the current directory by the following command:

$ cd ~/src/choreonoid

Installing build tools and dependency libraries

To build Choreonoid, the following tools and libraries are necessary:

  • C/C++ build tool set:

    GCC Complementary build tools such as “Make” are also necessary. In Ubuntu Linux, you can install all of them by specifying the package named ‘build-essential’. Other Linux distribution may have a similar package.

  • CMake : This is used for generating Makefiles.
  • Doxygen : A tool for generating reference manuals from the comments in the source code.
  • Graphviz : This can add useful diagrams such as class relationship diagrams to the reference manuals generated by Doxygen.
  • Boost C++ Libraries : Useful C++ library collection.
  • Qt : A framework library including a rich GUI toolkit.
  • OpenSceneGraph : 3D scene graph library based on OpenGL.
  • libjpeg : A library for loading JPEG image files.
  • libpng : A library for loading PNG image files.
  • gettext : Tools and libraries for supporting international messages.

The following libraries are also necessary and you can use ones included in a Choreonoid source archive.

  • Eigen : High performance and high functionality template library for matrix / vector computations.

Note

Currently Choreonoid source archives include Eigen source files which we slightly modified to avoid the compile error caused by the combination with boost::multi_array. If you use the external Eigen, the same modification must be applied to it. The next version of Choreonoid will stop the use of boost::multi_array, and it will be able to be compiled with normal Eigen library.

  • LibYAML : A library to parse YAML texts.

In Ubuntu Linux, you can install all the above tools and libraries by executing a script install-requisities-ubuntu.sh in misc/script of the Choreonoid source tree. After you execute

$ misc/script/install-requisities-ubuntu.sh

the password for sudo is required and please input it. Then all the packages are installed through the package system.

CMake’s build configuration

You have to generate makefiles for compiling Choreonoid by using CMake. When

$ cmake .

is executed in the top directory of the extracted source tree, CMake checks dependency libraries and generates makefiles. Please note that you have to put a period after the cmake command.

Makefiles will be successfully generated by following the above instructions on supported versions of Ubuntu Linux. However CMake may show errors due to problems such as that dependency libraries are not correctly installed in proper directories. In such a case, you should correctly install the libraries, or modify the build settings of CMake. The build settings can be modified through command-line using the cmake command, or you can more easily use “ccmake” command for this purpose:

$ ccmake .

allows you to do configurations in a menu form.

If you want to specify the plugins and samples to compile, please use those commands to do corresponding settings.

Anyway please read the manuals of CMake to know more details.

Note

“GRobot Plugin”, which is used in the startup guide of this site, is not built by default. Please build Choreonoid with “BUILD_GROBOT_PLUGIN” enabled to test the startup guide.

Building Choreonoid

After makefiles are successfully generated by CMake, you can build Choreonoid with make command. In the top source directory (~/src/choreonoid), please type

$ make

If your PC has a multi-core CPU, you can use “-j” option to enable parallel building to reduce the compile time. For example,

$ make -j4

invokes up to four building processes at the same time. Usually specifying the number which adds one or two to the number of logical cores would work well to achieve the parallel building using the maximum CPU performance.

Note that makefiles generated by CMake usually do not show the details of build commands but simply show the build progress status. This is fine for checking the build progress, but you may sometimes want to know the details of command-line parameters given to the build commands such as GCC. You can check the details by specifying the VERBOSE variable like

$ make VERBOSE=1

This makes the make command show actual commands and their parameters.

When building Choreonoid succeeds, executable file choreonoid is generated in the “bin” directory. Choreonoid can be invoked by typing

$ bin/choreonoid

In this way, the executable file generated in the build directory can be directly executed in Linux and it would be convenient for the development. On the other hand, executing

$ make install

installs Choreonoid files into the specified install directory. The default install directory is set to “/usr/local” (in this case you should “sudo make install”), and this can be modified by setting CMAKE_INSTALL_PREFIX of CMake settings.

Treatment of the Balancer Plugin

Choreonoid has a function to automatically adjust the dynamic body balance of biped robots so that the robots can stably perform created motions without falling down. This function is provided by “Balancer Plugin”. Note that the source of this plugin is currently not open and we release only the binary files build for some platforms with the source archive.

For Ubuntu Linux, the pre-compiled binary which works on 32-bit x86 architecture of the supported versions is provided by the source archive. To use the binary of the Balancer plugin, please copy “libCnoidBalancerPlugin.so” in “proprietary/BalancerPlugin” into the plugin directory of Choreonoid. The plugin directory is “lib/choreonoid-x.x” in the build directory or the installed directory.

Please also note that the license of the Balancer plugin is not the same as that (LGPL) of the Choreonoid main program. The use condition is written in “proprietary/BalancerPlugin/LICENSE”. Please ask AIST if you want to use the plugin with another license.