HAPI Installation

From H3D.org

Jump to: navigation, search

Contents

Requirements

Installation on Windows

Installation

To install HAPI on Windows follow these steps.

  1. Register at http://www.h3d.org and download the Windows installation file. (Currently you need to use the installation file for H3D to install HAPI, if H3DAPI is not desired then just do deselect it before installing.)
  2. Install HAPI using that file.
  3. Run examples through start menu.

Building from source

To build HAPI on Windows follow these steps.

  1. Obtain the source code. Preferrably by installing HAPI as in the step above. If the development source is desired follow the instructions in the Source Repositories section.
  2. Install version 2.6.0 or later of CMake. Go to the cmake homepage to download and install that program.
  3. Start CMake GUI. Put the search path to CMakeLists.txt in the first text box in this GUI. On a standard installation the search path is C:\H3D\HAPI\build. Put the search path to where the generate projects will be build in the second text box, for example C:\H3D\HAPI\build\vc10. Press the Configure button and choose the compiler for which CMake will generate build files. Then wait while CMake tries to detect what libraries are installed on your system. It might be so that the Configure button will have to be pressed again after the first configure run. If everything went fine then the "OK" button should light up and when it is pressed the project files will be generated.

    Alternatively the CMake command line could be used to generate the project files. In that case navigate (in the command line) to the HAPI\build folder and on a standard installation of CMake 2.6 write:
    C:\Program Files\CMake 2.6\bin\cmake.exe
    The project files will then be generated in HAPI\build folder.
  4. Open the projects and start building. When generating for Microsoft Visual Studio the project file to open is the solution file generated.
  5. When the HAPI ( and H3DUtil) library(ies) finished building build the INSTALL project once. This will copy needed files to a location in which other CMakeLists.txt distributed with HAPI can find them.
  6. To generate examples use the CMAKE GUI again and enable HAPI_EXAMPLE_PROJECTS before configuring again. Then open solution and build as before.

Installation on GNU/Linux

Using debian package

It is quite easy to use debian packages to install HAPI and obtain its source code. These steps are tested for Ubuntu 12.04 and 12.10. We assume it will work on other systems as well.

  1. Open /etc/apt/sources.list as sudo. Use for example the terminal command
    sudo gedit /ets/apt/sources.list
  2. At the end of that file add the following
    deb ftp://www.h3dapi.org/pub/releases/linux/debian/ distro sensegraphics
    Where "distro" is your linux distribution. For Ubuntu 12.04 this is "precise" and for Ubuntu 12.10 this is "quantal".
  3. If you would like to make it easy to download source the also add
    deb-src ftp://www.h3dapi.org/pub/releases/linux/debian/ distro sensegraphics
  4. Save file and exit.
  5. In terminal write
    sudo apt-get update
    followed by
    sudo apt-get install libhapi
  6. Select Yes for all questions about "not known debian package".


Sadly we can not distribute HAPI with prebuilt OpenHaptics support for linux. Therefore it might be useful to get source of HAPI. Then do the following.

  1. In terminal cd to a directory in which you want to download the source.
  2. Write
    apt-get source libhapi libh3dutil
  3. After download is finished you will have tar.gz files in your directory which contains all the source code for h3d. Note that if you only want extra OpenHaptics support it should be enough to only custom build hapi and h3dapi. The rest can be installed using debian.

Installation from Source

If you want to build follow these steps.

  1. Install version 2.4.7 or later of CMake. To do this on Ubuntu open a terminal and write:
     sudo apt-get install cmake 
  2. Register at http://www.h3d.org and download the source for HAPI.
  3. HAPI depends on other libraries. If you installed hapi from debian and then want to build it from source you should not need to use apt-get to install any new libraries. The build system used by HAPI will detect which libraries are installed on the system and only enable the features that the system can support. If more features are desired the corresponding library has to be installed. Note that some libraries are required for HAPI to compile. See the list of external libraries.

    If DHD-API is obtained then libusb needs to be installed. PCISCAN_LIBRARY should also be set if the library is not found in default location.

    • If using Ubuntu 7.10 or later, several of these libraries can be obtained by using the apt-get feature. The first two packages installed below are the C++ compilers needed to compile HAPI. In a terminal write:
      sudo apt-get update
      sudo apt-get install gcc g++ libglew-dev libglut libglut3-dev

      Freeglut can be obtained using the following commands:
      wget http://ovh.dl.sourceforge.net/sourceforge/freeglut/freeglut-2.4.0.tar.gz
      tar -xzvf freeglut-2.4.0.tar.gz
      cd freeglut-2.4.0
      sudo ./configure CFLAGS="-fexceptions" CXXFLAGS="-fexceptions"
      sudo make
      sudo make install

      To install libusb required by DHD-api from ForceDimension on Ubuntu do the following:
      sudo apt-get install libusb++-dev

      In version 8.04 of Ubuntu another library might need to be installed:
      sudo apt-get install libxi-dev libxmu-dev
  4. In the terminal change folder to the HAPI/build folder and generate a makefile by writing:
    mkdir linux
    The reason for creating a new directory called 'linux' is to easily remove all the cmake generated files in the future in case this is needed. Now change directory to the new 'linux' directory. Then write:
    cmake ../

    To build HAPI using the makefile write:
    make

    When the make finished all that is left is to install HAPI. This can be done by writing:
    sudo make install

    HAPI libraries are now installed on your system. But there is no application installed that use HAPI libraries. The second last step could be skipped if one want to build and install right away.
  5. There are example applications in this distribution that use HAPI. One of the examples requires WxWidgets, to install WxWidgets on Ubuntu write this in the terminal:
    sudo apt-get install libwxgtk2.8-dev

    To build the examples simply change the folder to HAPI/examples and do the following:
    mkdir linux
    cd linux
    cmake ../
    make

    To test one of the examples change folder to HAPI/examples/SurfaceExample/build and do the following:
    ./SurfaceExample

    Note that a supported haptics device must be connected for this demo to work properly.

Installation on Mac OS

Currently you need to build HAPI on MacOS X yourself. To build HAPI on MacOS X follow these steps.

  1. Install version 2.4.7 or later of CMake.
  2. Install XCode. If gcc is an unrecognized command in the terminal after installing XCode there is a high probability that CMake will not be able to generate build files for gcc and/or XCode. Another version of XCode could be used or fix it in some other way.
  3. Register at http://www.h3d.org and download the source for HAPI.
  4. HAPI depends on other libraries. The build system used by HAPI will detect which libraries are installed on the system and only enable the features that the system can support. If more features are desired the corresponding library has to be installed. Note that some libraries are required for HAPI to compile. See the list of external libraries.
  5. Generate build files for your build system using CMake. Either use the console version as in the installation guide for linux above or use the GUI version in which the first textbox should contain the location of the CMakeLists.txt file. This file is located in HAPI/build. The second box is the location of where the build files will be created. Use for example HAPI/build/OSX. Press configure, choose which system to generate build files for wait and press configure again until the generate button can be used. Press generate and then the build files will be in the choosen folder. If "Unix Makefile" are choosen then proceed from step 3 in the installation guide for linux.
  6. There are example applications in this distribution that use HAPI. To build these use the CMakeLists.txt located in the folder HAPI/examples. Run any of the built examples to test your HAPI build.

Troubleshooting

Upgrading

Source Repositories

Latest development version

Sometimes it is convenient to get the latest source of HAPI that is not yet in an official release. To obtain the source an internet connection and a subversion client is needed. Subversion can be obtained from subversion.tigris.org. The following instructions assume that a subversion client is used. When subversion is installed HAPI source can be checked out from a shell by these commands.

cd mydevdir
svn checkout https://www.h3dapi.org:8090/HAPI/trunk HAPI
svn checkout https://www.h3dapi.org:8090/H3DUtil/trunk/H3DUtil H3DUtil

This will make the directories HAPI and H3DUtil subdirectories to mydevdir.

On Windows it is important to put the directories in this type of hierarchy structure unless it is desired to set most of the paths to libraries by hand when using CMake. It also makes developing smoother if an official HAPI release is installed and the folders created by it are used to check out the source in. The reason for this is to not have to download and install all external libraries needed by HAPI and H3DUtil. For Windows TortoiseSVN could be used as a subversion client to integrate subversion closely to the Explorer interface.

Bug fix repositories

The repository urls listed below contain bug fixes to official releases of HAPI. These differs from the latest development version in the way that no new functionality will be added to the repository. Only fixes to problems discovered in the release will be added.

Release 1.0

https://www.h3dapi.org:8090/HAPI/branches/release1.0.1
https://www.h3dapi.org:8090/H3DUtil/branches/release1.0.1
Personal tools
go to