Building from the source code for Windows

Preparation

To build and install Choreonoid from the source code, you have to prepare tools and libraries required for it in advance.

First of all, please install the above tools and libraries. The above versions just show the versions which can successfully build Choreonoid at December 16th, 2011. Older versions may build Choreonoid, or later versions may fail to build. In general, library versions which have the same second (minor) version number can be used in a similar way.

The followings are brief descriptions about installing each tool or library:

  • Visual C++

You can use the commercial editions, or you can also use the Express Edition , which can be freely downloaded.

Note

Currently the debug version compile on Visual C+ 2010 cannot execute correctly. This is due to the compatibility problem between the boost.multi_array library and Visual C++ 2010. We stopped to use boost.multi_array to avoid this problem and that version will be released as the next version. Currently please use Visual C++ 2008 if you need to debug Choreonoid.

  • CMake
You can download the installer for Windows at the Download page of CMake .
  • Boost
Building Choreonoid requires not only headers but also some libraries which must be compiled. Those libraries include system、filesystem、program_options、regex、signals、thread、iostreams, etc. You can easily install the compiled binaries by using the installer for Windows distributed at the download page of BoostPro . In this case, corresponding Visual C++ version should be checked in the install dialog and “Multithread DLL” should be checked as a form of libraries. If you want to build the debug version, please check “Multithread debug DLL”, too. For the selection of libraries to install, it’s easy to just check all the libraries.
  • Qt
You can download the installer for Windows from the download page of Qt . There are several kinds of packages. If you cannot decide which package to use, please use “Qt libraries” for Visual C++ 2008 or Visual C++ 2010.
  • OpenSceneGraph

It is easy to download the corresponding binary package from AlphaPixel’s binary download page of OpenSeneGraph . Each version has three separated archives, and it may be better to download all archives and integrate the all extracted files into the same directory. This can be done by copying each extracted directory to the same place on explorer and answer “Yes” to the question “Integrate folder?”. The 7z archive files can be extracted by using 7-Zip .

Attention

OpenSceneGraph allows Choreonoid to load well-used 3D model format files to show some models and to save the 3D rendering image as an image file. For those functions, if you want to use non-ASCII characters in a file path, you must build OpenSceneGraph with the build option “OSG_USE_UTF8_FILENAMES” enabled. Please note that the binary packages distributed in the above AlphaPixel’s site do not seem to be compiled with that option.

Next, please download the source archive of Choreonoid from ../download and extract it. Note that a path which include non-ASCII characters may cause an error.

In the following description, we assume that the source code is extracted into C:¥src¥choreonoid.

That’s all of the preparation.

Executing CMake

Please invoke CMake(cmake-gui) from the start menu, and the following dialog is shown.

install/images/cmake0.png

In this dialog, please input the top directory of the Choreonoid source code （ C:¥src¥choreonoid ）into the right side of where is the source code, and input the directory to build Choreonoid into the right side of where is build the binaries. Both input areas are indicated by the red rectangle labeled (1) in the above figure. The directory to build Choreonoid may be the same as the source code directory, but it can be different directory to distinguish them. In this example, we make the “build” directory under the top directory of the source code, and specify this directory （ C:¥src¥choreonoid¥build ）as the build directory.

After inputting the directories, please click [Configure], which is indicated by the red rectangle (2) in the above figure. Then the following dialog to specify the compiler is open. Please choose either Visual Studio 9 2008 or Visual Studio 10 2010 according to which you use, and click [Finish].

install/images/cmake1.png

Then the configuration of CMake is processed and it shows the following error dialog. This is because the install directory of OopenSceneGraph cannot be found. To solve this, click [OK] first.

install/images/cmake2.png

Then input the directory where you installed OpenSceneGraph (you extracted the archives) into the input box to the right of OSG_DIR . After finishing the setting of OSG_DIR , click [Configure] again.

install/images/cmake3.png

Note

Similar errors may be reported for other libraries when they are not detected, depending on CMake versions, library versions, or install places. In such a case, please manually specify the installed directory like the case of OpenSceneGraph. Note that basically CMake cannot automatically detect Boost libraries whose version is later than the last latest one when CMake or Choreonoid you are using was released. In order to automatically detect such versions, you should add the version number you want to detect to the “Boost_ADDITIONAL_VERSIONS” variable in the top CMakeLists.txt.

Then configure is processed and it stops at a state like the following figure. This is not an error, and here you can specify plugins to install. In our tutorial, we use the robot G-ROBOTS GR-001, so please check BUILD_GROBOT_PLUGIN if you want to do the tutorial. After all the plugins to install are specified, click [Configure].

install/images/cmake4.png

Configure is processed again, and it is completed when the message “Configuring done” is displayed in the bottom message output area.

install/images/cmake5.png

Note

Following the above operations makes CMAKE_INSTALL_PREFIX be configured to the default value C:¥Program Files¥Choreonoid. Windows7 does not allow non-administrative users to access the directory under C:¥Program Files and it may make your install fail. If you don’t have or want to use administrative privilege, you should set another directory such as C:¥User¥ to CMAKE_INSTALL_PREFIX.

By default what are copied into the install directory are only libraries and commands compiled from the Choreonoid source, and external libraries such as Boost and OpenSceneGraph are not copied. If you want to install all the files which are necessary to execute Choreonoid, please check INSTALL_DEPENDENCIES to install them. Otherwise PATH must include the directories containing those libraries.

Finally, please click [Generate] to generate a solution file set (with project files) of Visual Studio.

install/images/cmake8.png

The generation of the solution file set is completed with the message “Generating done”. Please check whether the solution file (Choreonoid.sln) of Visual Studio is generated in the directory to build Choreonoid.

Loading the solution file on Visual Studio 2008

After the solution file is successfully generated, please double-click solution file Choreonoid.sln on Explorer. This will invoke Visual Studio with loading the solution file. If Visual Studio is not invoked, it may be due to the installation problem of it and try to reinstall it or confirm the file extension relationships. Or please try to invoke Visual Studio first and load the solution file manually from the menu of Visual Studio.

Compiling Choreonoid

After the solution is successfully loaded, the window will be like the following figure. Here please change the build version setting shown by the red rectangle from Debug to Release in order to build the release version.

install/images/VS2008-1.png

Now let’s try to build Choreonoid. In the “Build” menu of the main menu, there is a menu item “Build Solution”, and please activate this menu item to start building. Then building Choreonoid is processed. When “0 Errors” is shown in the bottom message window, the compile is finished.

install/images/VS2008-2.png

Installing Choreonoid

After the compile is finished, let’s install Choreonoid. Install can be processed with the project named “INSTALL”, which is listed as one of the projects in the solution. Please right-click the “INSTALL” project and invoke the “Build” item, which is in the top of this menu. Then the installation is processed, and target files are installed into the directory specified to CMAKE_INSTALL_PREFIX in the CMake configuration. If INSTALL_DEPENDENCIES of the CMake configuration is checked, the binary files of external libraries are also copied.

install/images/VS2008-3.png

That’s all of building and installing Choreonoid.

By double-clicking “choreonoid.exe” in the “bin” sub directory of the installed directory, Choreonoid is invoked.

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 Windows, the attached binary works with the Choreonoid main binaries built as 32-bit binary with Visual C++ 2010. Please copy “CnoidBalancerPlugin.dll” in the “proprietary/BalancerPlugin” directory of the source archive into “lib/choreonoid-x.x/” of the binary installed directory. (x.x means the version number.)

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.