** Overview ** This repository contains everything that is needed to set up and build the Tensegrity simulators. The 'env' and 'build' directories that are created during setup are considered to be local directories and are ignored in the repository. If you run into problems, you can always delete these and run setup again. To get started, read the below instructions, then run the setup script (setup.sh). It will walk you through the process of getting everything configured and installed. If you already have some things installed in the standard locations, setup will find those so that you don't have to reinstall. However, this functionality may be limited based on your linux distribution, so if you're not using Ubuntu 13.10 or 14.04, be sure to read below and confirm you have the necessary packages in your $PATH. You can run setup as many times as you like without hurting anything. ** Linux / Mac Installation ** ** Prerequisites/Dependencies ** - Some Linux prerequisites, outside of the setup script file. Make sure the following are installed: Ubuntu (you can use sudo apt install): - g++ (the compiler for cmake) - libglib2.0-dev - curl - freeglut3 - freeglut3-dev (glut for bullet graphics) - cmake - build-essential - unzip - python-dev (depending on you linux setup) Fedora/CentOS (you can use sudo dnf install): - gcc-c++ (the compiler for cmake) - glib2-devel and glib2-devel.i686 - curl - freeglut - freeglut-devel - cmake - build-essential - unzip MAC OSX (please read the detailed instructions below for OSX 10.9 at the end of this file) -gcc/g++ 4.5 (via Macports or Homebrew) - Also if available, it's sometimes easier to install cmake (and/or boost) from your distro. On ubuntu, sudo apt-get install cmake. If you do this, the script is designed to detect system-wide cmake installations on both Linux and Mac; however, it only correctly detects boost installations on Mac. - Installing libboost-all-dev under Ubuntu does NOT place these files where our install script can see them. At the moment, it's easier to just have our installer download and compile its own version of libboost-1.53.0-dev, as counterintuitive as that seems. See a known issue below about this compilation under Ubuntu 14.04. ** Known Issue with GCC/G++ 7 and Ubuntu 18.04 / Debian Stretch ** - NTRTsim is broken with the newer versions of GNU's C/C++ compilers. A change occurred somewhere between gcc and g++ 4.8 and version 7 that changed functionality that NTRTsim and/or Bullet 2.82 relied upon. A symptom of this error occurs when trying to build (e.g.) the NeuroEvo classes. No known fix allows NTRTsim to be built with these compilers. However, it is possible to install version 4.8 alongside 7 and switch between them. For Ubuntu, as motivated by http://charette.no-ip.com:81/programming/2011-12-24_GCCv47/, the fix is as follows. Please read that link carefully before attempting the fix, to understand what's happening. sudo apt-get install g++-4.8 sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.8 60 --slave /usr/bin/g++ g++ /usr/bin/g++-4.8 sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-7 40 --slave /usr/bin/g++ g++ /usr/bin/g++-7 sudo upate-alternatives --config gcc ...and select the 4.8 compiler. You can check which is being used by ls -lah /usr/bin/g++* ls -lah /etc/alternatives/g++* If you had previously run setup.sh using the 7 series compilers, you must delete all files in env/ and build/ and re-run setup.sh to recompile all libraries with the 4.8 compilers before running bin/build.sh. ** Running the setup script ** - Ensure that all of the dependencies above are installed before running setup.sh. If you realize after successfully running setup.sh that you were missing a dependency, then install the dependency, nuke your existing NTRT install, and do a fresh build from scratch. There are cases (e.g. freeglut3) where setup can finish even if a dependency is missing, but app builds will continue to fail even after you've installed the missing dependency. See issue 211 for more info (https://github.com/NASA-Tensegrity-Robotics-Toolkit/NTRTsim/issues/211) - If you want to specify setup options, copy the files in conf/default/ to conf/, removing the .default (for example conf/default/bullet.conf.default becomes conf/bullet.conf) and edit as desired. This can save you time if you already have Boost installed. You can also just run setup.sh -- it will create the .conf files for you and allow you to set certain options like the location of your bullet build if you already have one. - Run setup.sh. (sh setup.sh or bash setup.sh) - The setup.sh script may be run multiple times without hurting anything. - To build the the src tree, run bin/build.sh The resulting executables will be located under the 'build' folder. To run an app, go to build/examples/SomeApp and run the executable. (for example: build/examples/3_prism/AppPrismModel) To build a specific app (after making changes to the source, for instance), go to build/dev/myApp and run 'make' - Create a project in your favorite IDE using the equivalent of 'Create a project using existing source' to point your project to the src directory. See below for more instructions. ** Development Environments ** During setup, an 'env' directory will be created. This directory is intended to be local to your system and is ignored in the repository. It contains builds of the software installed by setup as well as symlinks needed by CMakeLists.txt for the build process. After you create a new project using the existing source (the 'src' directory), add the include and library paths that have been created during setup. Note that all relative paths listed below (e.g. env/lib) are relative to this directory. - Add the following to your c++ include paths: env/include/bullet env/include/boost - You'll also want to add the standard include paths if they're not already present, e.g.: /usr/include /usr/local/include /usr/include/c++/4.2.1 (location of cstdlib header on your system) - Add the following to your c++ library paths: env/lib - If you are working on Mac OSX you will need to include the default framework location /Library/Frameworks - Also add the standard library paths (may be slightly different for you): /usr/lib /usr/local/lib ** Build Options ** - After the first install, note the following options are available with build.sh (run build.sh -h for an up to date list) positional arguments: build_path Path to build (relative to src, e.g. 'BasicApp' or 'lib/Example'). Defaults to all if not specified, includes dependancies. optional arguments: -h Show this help message and exit -c Run 'make clean' before make/make install on non-library sources -w Show compiler warnings when building -t Build test/ rather than src/ -r Build test/ rather than src/ *and* run all tests after compilation. -i Build test_integration/ rather than src/ -g Build test_integration/ rather than src/ *and* run all tests after compilation. ** Manual Installation ** - Install cmake (see http://www.cmake.org for details) - Install boost in the standard manner (see http://www.boost.org) - Create an 'env' directory in the same directory as this INSTALL file. mkdir env - Create the necessary subdirectories under env: cd env mkdir bin build downloads include lib cd .. - Create a symlink to cmake under env/bin: cd env/bin ln -s `which cmake` # (or just provide the path, e.g. ln -s /usr/bin/cmake) cd ../.. # back to top level - Download and build Bullet Physics: cd env/downloads curl -k -L -O http://bullet.googlecode.com/files/bullet-2.82-r2704.tgz cd ../build tar xzvf ../downloads/bullet-2.82-r2704.tgz cd bullet-2.82-r2704/ path_to_env=`pwd`/../../../env "$path_to_env/bin/cmake" . -G "Unix Makefiles" \ -DBUILD_SHARED_LIBS=OFF \ -DBUILD_EXTRAS=ON \ -DCMAKE_INSTALL_PREFIX="$path_to_env" \ -DCMAKE_INSTALL_NAME_DIR="$path_to_env" make make install cd .. # back to env/build - Create a 'bullet' symlink to your bullet build under env/build. This will be expected by CMakeLists.txt ln -s bullet-2.82-r2704 bullet cd ../.. # back to top level - Create the necessary symlinks under env/include. The following values reflect global installations of boost and gsl; adjust these values if you installed these packages elsewhere (e.g. using --prefix=/path/to/env). cd env/include ln -s /usr/local/include/boost boost cd ../.. # back to top level You should also have a 'bullet' directory under env/include. If not, make sure to create a symlink that points to the bullet header files. - NOTE: When complete, your 'env' directory must have either directories or symlinks for the following elements: env/ bin/ cmake # (executable) include/ bullet/ # Bullet header files boost/ # Boost header files lib/ # Libraries will be installed here when you build the source. - That should do it. You can now run bin/build.sh to build your code. ** Troubleshooting and Known Issues ** - Our usage of Git does not respect file permissions well enough on occassion. You may have to "chmod ug+x" our setup.sh and bin/build.sh scripts. - If any of the downloads fail, there may be a corrupt file in env/downloads. Be sure to remove it before running setup/setup.sh again. Similarly, there might be a failed install directory under env/build, if a compilation fails. TO-DO: create a "make clean"-like function for setup. - Similarly, this script does not currently check for package integrity before extracting tarballs, and will happily attempt to extract incomplete downloads and then fail. If you get errors, just delete the package's directory under ./env/downloads and ./env/build - Under Ubuntu 14.04, the compile of Boost will exit with errors even though it actually completes successfully. You'll get an exit message like: >> ...failed updating 6 targets... >> ...skipped 18 targets... >> ...updated 11024 targets... >> Install failed >> Boost initialization failed -- exiting now. This is fine. Just run setup.sh again to confirm everything is OK, then move on to running bin/build.sh - If you want to recompile a library, when you try and re-run ./setup.sh, remove not only the downloaded file and extracted files under ./env/build, but also the (failed) compiled files under ./env/include and ./env/lib, for example, a failed compile of Boost requires deleting ./env/include/boost and everthing named "libboost" under ./env/lib - If you get an error when running bin/build.sh about CMake not "including" a GLIB directory, be sure you've installed libglib2.0-dev (Ubuntu 14.04). - A known bug is that some of this code will not compile without the position-independent-code flag, -fPIC, passed in. Though this flag should be enabled by default now, if you do get an error related to -fPIC, just edit the CMakeLists files to include -fPIC. - If you are upgrading from a prior version, be sure to delete your env directory and reinstall it using setup.sh. There have been some changes to the patches, particularly the neuralNetwork code, that are incompatible. ** MAC OSX 10.9 installation problem ** Due to the defaul library being stdlibc++ instead of stdc++, NTRT and also all the dependencies (boost and bullet) has to be compiled using gcc. As a temporary solution, please follow these steps: 1) Install gcc, g++ using macports or homebrew (I used with gcc 4.5.4 through macports). 2) Download the github directory 3) Edit bin/setup/setup_boost.sh and uncomment this line by deleting '#': #sed -i '' 's/^# using gcc ;/using gcc ;/g' tools/build/v2/user-config.jam 4)run setup.sh 5)run bin/build.sh