Build and install from source code (Windows version)¶
目次
Preparation¶
To build Choreonoid from source code and install, you will need to prepare in advance the libraries and tools required for the build.
Required tools
Visual C++ 2015, 2017, or 2019
CMake (3.12.0)
First of all, install the above tools and libraries. The numerical values in parentheses for each library indicate the version which we have tested and confirmed to be working as of July 2018. Apart from the libraries where a minimum version is specified, older versions may or may not work. But on the other hand, building from source may fail even when using newer versions. (It is difficult to specify a version that is working correctly, so please forgive this vague description.) Generally, if the first two digits of the version number are the same, you should be able to use it in the same way.
Additional information about installing each tool and library is provided below. Installation should be done under an account with administrator privileges. Also, if the user account control is displayed as in the screenshot below, click on Yes to proceed.
Visual C++¶
Install Visual C++. It is recommended to user the latest version of Visual C++. The free version of Visual C++ can be used to build Choreonoid.
CMake¶
This is a tool for specifying the build process. The build process for Choreonoid is described using the format of this tool, and it can be used to generate Visual Studio project files on Windows.
You can download the Windows installer “Windows win64-x64 Installer” from the CMake download page. We are currently testing operation with version 3.12.0.
Click cmake-3.12.0-win64-x64.msi to download, and run this file to install. Follow the displayed instructions.
When you see the screen as in the screenshot above, select Add CMake to the system PATH for all users.
Other settings can be left at their defaults.
Boost¶
This is a useful collection of C++ libraries. You can download it from the Boost Downloads page.
f you download the source code, you will need to compile it. There is already an installer that is easier to use, as it contains prebuilt binaries compiled for Windows. Click Windows Binaries on the screen and it will take you to the download page.
boost_1_67_0-msvc-14.0-64.exe (for VC2015) or
boost_1_67_0-msvc-14.1-64.exe (for VC2017).
Download either
Run the file to begin the installation process. By default, the installation location is the “C:\local\boost_1_67_0” folder. If you don’t change this, CMake will automatically detect Boost in a later step. If you do change it, remember that you will need to specify the folder manually.
Qt¶
Qt is a comprehensive framework library that includes a GUI, and Choreonoid also uses it as the basis for its GUI.
You can get the Qt installer from the Qt download page . On that page, you can select the Commercial version or the Open Source version, as shown in the screenshot below. The Open Source version is fine, so select that.
When you go to the next page, it will auto-detect your OS and display the appropriate installer.
Check that “Recommended download: Qt Online Installer for Windows” is displayed and click the Download button. When you launch the downloaded file, you will be asked to login. It is okay to click the Skip button and skip ahead.
By default, the installation location is the “C:\Qt” folder. If you don’t change this, CMake will automatically detect Qt. If you do change it, remember that you will need to specify the folder manually.
During the process, on the Select Components screen as shown below, select the library to install.
Select the latest version 5.11.1 of MSVC2015 64bit or MSVC2017 64bit. Then, follow the instructions of the installer.
Eigen¶
It is a library used to calculate matrices, vectors, etc. It can be downloaded from the official Eigen page .
The latest version 3.3.5 Zip file can be downloaded by clicking on Zip. This library is made up of a header file only and doesn’t need to be compiled, so it is okay to just extract the downloaded file to a suitable location. However, in Eigen, the archive file name and extracted folder name consist of characters that do not give the version number, which can be confusing if left as it is. Refer to the example shown below for how to change folder names during installation.
Download the Zip file of the version you are going to use from the Eigen page. For version 3.3.5, the file will be named “eigen-eigen-b3f3d4950030.zip”. As you can see, the file name doesn’t specify that the version number is 3.3.5. Also, the word “eigen” is included twice for some reason.
Extract the Zip file using Explorer or a similar tool. By default, the extracted folder will be named “eigen-eigen-b3f3d4950030”, and Eigen itself will be inside.
eigen-eigen-b3f3d4950030benchblascmake…
Change the folder name to include the version number and move it to a suitable location. Boost will be under C:\local, so it is a good idea to also save Eigen here. The final Eigen installation will be as shown below. If it is installed in this location, CMake will automatically detect Eigen. If you install it somewhere else, remember that you will need to specify the folder manually.
localboost_1_60_0…eigen-3.3.4benchblascmake…
Getting the source code¶
Official release version¶
The source code of the official release version of Choreonoid can be downloaded from the Downloads page. Download the corresponding version of the “source package” from this page. The files are Zip archives, so extract them into a suitable directory using Explorer or a similar tool.
When you extract it, it generates a directory named something like choreonoid-1.6.0. The complete source code is stored in this directory, which from now on is referred to in this manual as the “source directory”.
Development version¶
You can also use the Choreonoid development version if you wish. It is managed as a Git repository, and it is published at the following github address.
There are two ways to get the source code from here.
Install Git
Get the Zip file
Installing Git¶
Git tools are required in order to use the repository. There are several tools that have been released free of charge, but here we will explain how to use the Git tools in Visual Studio and how to install a tool used at the command prompt. Of course, you can use other tools that you’re already familiar with.
Use Visual Studio¶
Launch Visual Studio, select Team Explorer from the View menu and it will be displayed.
Click the icon circled in red in the screenshot.
Under Local Git Repositories, click Clone.
Enter the URL of the Choreonoid repository in the upper field outlined in red, enter the directory where you want to keep the source code in the lower field, and click the Clone button.
The source code will be cloned.
Once cloned, select choreonoid as shown below, right-click and select Open from the dropdown menu.
When the screen changes as shown below, select Sync. Then, when you click Pull, the latest source code will be updated.
Use Git for Windows¶
Next, we will explain about the tool used at the command prompt.
Download the file from Git for Windows and run. Follow the instructions of the installer. It’s fine to keep the default setting, but if the screen below appears, select “Use Git from the Windows Command Prompt”, which will add wrappers to your PATH.
When the installation is complete, launch the Command Prompt, go to the directory which contains the Choreonoid source you want to save, and execute the following command.:
git clone https://github.com/choreonoid/choreonoid.git
This will create a “choreonoid” directory containing the repository. You can then use the following command:
git pull
in this directory and update to the latest version of the source code.
The above will allow you to get the source code, but for detailed usage of Git you should refer to the Git manual or explanatory articles.
Getting it as a Zip file¶
Open the Choreonoid repository using a web browser, click on the green Clone or download button outlined by the red rectangle, and it will be displayed as follows.
Click the blue Download ZIP circled in red to download the latest content in Zip format. Extract the downloaded file in the directory where you keep the source code.
While this method is simple, after the second time the git pull command can only get updated files, and using this method means downloading all the files every time.
Configure build settings with CMake¶
First, launch CMake (cmake-gui) from the Start menu. Then, the dialog box shown below will be displayed.
Next, enter the Choreonoid source directory in the input field to the right of Where is the source code: indicated by the No.1 red frame in the screenshot above. Click Browse Source… and a dialog box will open, from which you can select the directory. Next, enter the directory where you want to build Choreonoid in the input field to the right of Where to build the binaries:. The directory for the build can be the same one used for the source code, but this may create a confusing structure. So, create a sub-directory called “build” below the source directory and enter the name of that sub-directory. Once you’ve entered the above, click Configure indicated by the No.2 red frame.
If the directory for the build has not been created in advance, a dialog box will now be displayed asking if you want to create one.
Next, a dialog box will be displayed as shown below. Select the compiler from the dropdown menu outlined in red.
Select “Visual Studio 14 2015 Win64” or “Visual Studio 15 2017 Win64” and click the Finish button.
This will then run CMake’s configuration process and the compiler, libraries, etc. will be detected.
Note
At this time, you may see a message saying, “The C compiler identification is unknown” or, “The CXX compiler identification is unknown”. This indicates that the Visual C++ compiler has not been detected correctly. The cause is unclear, but this problem has occurred in one of our developer environments. In this case, it is not possible to continue processing correctly from this point.
Regarding this issue, we tested running CMake with administrator privileges, which correctly detected the compiler and made it possible to proceed past this issue. To do this, right-click on the CMake icon and select “Launch as Administrator” in the menu that appears. If you encounter this problem, we recommend trying this workaround.
Note
If the program called pkg-config.exe is installed in the Windows environment, you may encounter an error during this operation. If that happens, you should uninstall pkg-config.exe.
When installing the libraries, if you selected the default directory, it will automatically detect the libraries and a message will be displayed with Configuring done on the last line as shown below.
(If you install in another directory, an error message will probably be displayed. The settings for that situation are explained later.)
Next, set the installation location. Scroll through the field shown in the center as in the screenshot below until the item CMAKE_INSTALL_PREFIX is displayed.
By default, it is set to “c:\Program Files\Choreonoid”. In Windows, only administrators have access to paths below “c:\Program Files”, so this may cause the installation to fail. You can run the installer with administrative privileges, but it is probably easier to simply install in a different directory. You can set this with CMAKE_INSTALL_PREFIX, specifying a directory structure such as “c:\choreonoid\program”, for example.
When the settings are complete, click the Configure button and confirm that a message ending with Configuring done is again displayed.
Next, click the Generate button in order to create a Visual Studio project file. If the Generate button is not clickable, click Configure again.
Once the solution file is created, you will see the message Generating done displayed in the output pane.
Next, we will explain the steps to take if an error message is displayed or you want to change other settings. If you have not seen any errors up to this point, you can read this after you have proceeded to Launching Visual Studio and importing solutions .
If libraries cannot be detected automatically, an error dialog like the one shown will be displayed.
Click OK to close the dialog box. Scroll down in the window where the message in the section below is displayed and find where the error is displayed. Ignore the warnings. An error displayed lower down is sometimes due to an error above, so start searching from the top.
In the screenshot below, an error appears saying that Eigen libraries could not be found.
Look up EIGEN_DIR from the previous settings and enter the Eigen installation directory.
Click the Configure button and confirm that the error has disappeared.
In the screenshot below, an error appears saying that Boost libraries could not be found.
BOOST_ROOT is not in the above settings. In this case, click the Add Entry button. A dialog box will appear, so enter the details as shown below.
In the Value field, specify the directory where the Boost libraries are installed. Click OK to close the dialog box, and confirm that BOOST_ROOT has been added as shown below.
Click the Configure button.。
If errors pertaining to QT5 appear, enter the directory in which the Qt5CoreConfig.cmake file is kept (it should be the path to the Qt installation location, followed by, /5.5/msvc2015_64/lib/cmake/Qt5Core) in the Qt5Core_DIR field. You may also see errors pertaining to other QT5 libraries, so enter details in the same way as above. You are free to ignore these warnings.
After that, it is possible to set various other options related to the build as required. For example, some Choreonoid functions are off by default, but you can turn these on as required by toggling the options that begin with BUILD_.
Repeat the same settings as above until the installation locations of all the necessary libraries are specified and there are no errors.
When all the required settings are complete, click Generate.
Note
Regarding other libraries, depending on the version of CMake you are using and the versions of installed libraries and their locations, detection may fail and produce similar errors. Errors may also appear for some of the optional features described below. The order in which errors appear may also vary depending on the installation. If this occurs, find the error locations and manually enter the installation location in the same way as described above.
Note
The details of the settings are saved as a file called CMakeCache.txt in the location specified by Where to build the binaries. If you want to redo the settings from scratch, delete this file. It can also be deleted using File - Delete Cache from the CMake menu.
Launching Visual Studio and importing solutions¶
Next, you can build Choreonoid.
The previous operations should have resulted in the Visual Studio solution file Choreonoid.sln being created in the location specified by Where to build the binaries in CMake. Double click this file.
Visual Studio will be launched and the solution file should be opened.
If Visual Studio fails to launch, there may have been an issue with the installation process, so reinstall it and attempt to repair the file association. Alternatively, you can try launching Visual Studio and opening the solution file from the menu.
Since the build operation is the same in Visual Studio 2015 and 2017, the following description does not specify which version. Therefore, there may be differences in the screen design, etc.
Compiling¶
Once a solution is read in, you will see the screen below. Change the section outlined in red to Release and confirm that x64-bit is displayed. If you change it to Debug, you will be able to create a debuggable binary. However, the debugging binary will be considerably slower than the Release version you compiled, so you should use the compiled Release binary unless you need to debug.
Next, you will build Choreonoid. Click Build in the menu and the dropdown menu seen below will appear. Click Build Solution as outlined in red. Choreonoid will now begin building. When you see the message “0 Failed” in the message window at the bottom, the compilation is complete.
Installation¶
Once the Choreonoid build is complete, you will finish by installing it. Install is selected, as shown below, from the Solution Explorer seen on the upper left. Right-click on the INSTALL project and a menu will appear. The top option of this menu is Build (see the area outlined in red shown below). Select this. If the process goes smoothly, the Choreonoid binary will be copied to the directory you specified with CMAKE_INSTALL_PREFIX when using CMake. If you checked the box next to INSTALL_DEPENDENCIES when creating the solution file with CMake, the library dependencies will also be copied.
This completes the installation of Choreonoid.
Double-clicking on choreonoid.exe in the bin directory of your installation location will launch Choreonoid.
Building optional features¶
In addition to setting Choreonoid to the default state following the steps above, there are several modules, plugins, and samples that can be used. These can be enabled with CMake and built into the software. In this section, we describe building several of these optional features. A summary of other features can be found in Optional Features.
We will briefly explain the installation method of the library used by each plugin, but there may be major changes due to a library version upgrade, for example. There may also have been updates to the developer’s website or changes to link destinations. If that is the case, you should be able to find up-to-date information by searching online using keywords such as the library name, “install”, etc.
Note
After configuring optional features in CMake, click the Configure and Generate buttons to update the solution file. Compiling and installing in Visual Studio using this file will create an optional plugin. Be sure to compile and install after changing options in CMake.
Assimp plugin¶
This plugin is for using Open Asset Import Library (Assimp), a library for reading 3D model data in various formats, in Choreonoid. In order to use this plugin, you need to build the Assimp library from source and install.
Open the page for assimp on github in your browser.
Click Branch:master as indicated by red circle No.1, then Tags as indicated by red circle No.2, and select the version. The current version tested as working is 4.1.0. In the screenshot, version 4.1.0 is selected.
Confirm that the display has changed to Tag: v4.1.0, click Clone or download, and click Download ZIP to download the source file in Zip format.
Extract the Zip file.
You can use CMake, in the same way as explained in the Choreonoid build, to create a Visual Studio project file. You don’t need to change the CMake option settings.
The installation destination of CMAKE_INSTALL_PREFIX is set to c:\Program Files\Assimp, but if you set it to be under c:\local, it will be detected automatically. So, if possible, specify it as c:\local\Assimp.
Compile and install in Visual Studio in the same way as Choreonoid.
Once you have installed Assimp, re-launch CMake and specify the source and build directory of Choreonoid.
The previous setting details are saved, so this time you only need to do the Assimp settings. (If you don’t have saved settings, such as when you specify a new build directory, click Configure without doing the following operation.)
As shown, the value for ASSIMP_DIR is displayed as ASSIMP_DIR - NOTFOUND.
There is an item below that called ENABLE_ASSIMP, so select this and click the Remove Entry button to delete this item. Then click Configure, which should automatically detect Assimp.
If the automatic detection fails, set ENABLE_ASSIMP to ON and enter the value for ASSIMP_DIR manually. At this point, you need to specify the directory that contains Assimp’s CMake file, not the top directory of the Assimp installation. It should be at (installation location)\Assimp\lib\cmake\assimp-4.1.
Next, you will build Choreonoid.
Media plugin¶
This plugin allows you to play back media files. Set BUILD_MEDIA_PLUGIN to ON in CMake.
Some file formats, such as MPEG-4 media files, may not play back by default. You can enable playback by installing the corresponding codec pack for that file format. You can search online to easily find these codec packs for free. Because these codecs can affect the functionality of other video software, we do not make specific recommendations. You should use codecs that match your system.
ODE plugin¶
The Open Dynamics Engine (ODE) is an open-source dynamics computation library; it is used in Choreonoid as a plugin to compute its simulations.
In order to build this plugin and use it, you must first install the ODE library. Prebuilt binaries of this library are not available, so you must build it from source. Access the Open Dynamics Engine site to download the file and extract it. We have tested versions up to 0.12 as working. (There are reports of 0.13 not working with Choreonoid.)
Click Get the source code here.
Go to ODE - 0.12 and click ode-0.12.tar.gz to download the file.
It is in the tar.gz file format, so you will need extraction software for Windows. If you don’t have it installed, you can install free software such as Lhaplus. )
Extract the Zip file and perform the build.
Use the command “premake” to build ODE. Launch the command prompt and go to the directory called “build” under the expanded directory. Then, run
premake4.exe --with-libccd --platform=x64 vs2008
. When you do so, it will create a directory called vs2008, which contains the file ode.sln. (Since ode 0.12 supports only up to vs2008, it creates a solution file for 2008. ) When you launch VS2015 (or VS2017) and open this file, a dialog box will open to convert the solution. Click the OK button to run it.
Several warnings will be displayed, but you can ignore these.
Using the converted solutions file, you will now perform a build. Select ReleaseDoubleDLL and x64 for the solution structure and confirm. If successful, a file named ode_double.* will be created in lib/ReleaseDoubleDLL.
Next, in the CMake build settings for Choreonoid, set BUILD_ODE_PLUGIN to ON and specify the ODE lib root directory for ODE_DIR.
Python plugin¶
This plugin is used to import and execute Python scripts and to use the features of the Python console used in Choreonoid.
In order to build this plugin and use it, you must first install Python. We have tested versions 2.7.15 and 3.6.3 as working.
When you use Python 3, go to the Python 3 download page on the Python website. Download and run Windows x86-64 executable installer.
If you don’t have Python 2.7 installed, check the box for Add Python 3.7 to PATH. If you do have Python 2.7 installed, don’t check this box. Click Install Now to install.
Next, you will install Numpy.
Numpy is installed for the Python that is used in Choreonoid. If only one of either Python 2 or Python 3 is installed, it will be in your PATH, so launch the command prompt and execute the following command.
python -m pip install numpy
If both are installed, your PATH will go through Python 2. In order to install to Python 3, execute a command specifying the directory where Python 3 is installed. Launch the command prompt and install with this command:
C:Users(username)AppDataLocalProgramsPythonPython37python -m pip install numpy
. C:Users… is the default installation destination, so change this as required.
When the installation is complete, open CMake for Choreonoid again and set the following settings to ON: ENABLE_PYTHON, BUILD_PYTHON_PLUGIN, and BUILD_PYTHON_SIM_SCRIPT_PLUGIN.
Note
If your PATH does not include Python 3, you need to pass PATH when launching Choreonoid.
set PATH=(installation destination of Python 3);%PATH%
choreonoid
It is easy to prepare and execute a batch file written as shown above.
Uninstalling plugins¶
Plugins installed by enabling the BUILD_XXX_PLUGIN option will not be deleted even if you turn the option off later. If you add a plugin and want to later delete it due to unstable performance or other issues, you must delete the file manually. Plugins are installed to (Choreonoid installation destination)/lib/choreonoid-1.7 in the format of Cnoid***Plugin.dll.