GAMS Installation

Amit edited this page Sep 9, 2018 · 96 revisions

Introduction

We do not currently have an automated build system for GAMS packaging, but we do try to make the build process as seamless and easy as possible. The current method for installing GAMS on your system is via build systems. To find out about the installation process for your operating system and build system, please see the sections below.


Table of Contents


Linux

To build for Linux, simply download the latest base_build.sh script for Linux builds. One way to do this is with the following:

sudo apt-get update
sudo apt-get install git-core
export GAMS_ROOT=$HOME/gams
export CORES=4
git clone -b master --single-branch --depth 1 https://github.com/jredmondson/gams $GAMS_ROOT

After you've downloaded GAMS via the above, you have a lot of choices. You can run any of the following scripts at any time. If you have already built GAMS once, calling these again will upgrade from repository to latest version. Note that when upgrading, you can choose which upgrades you want to do. For instance, if you want to only upgrade GAMS, you can call base_build.sh with no options. However, tests will be required to build GAMS and MADARA tests.

Build C++ with Tests

$GAMS_ROOT/scripts/linux/base_build.sh prereqs madara gams vrep tests

Build C++ with Tests and Java support

$GAMS_ROOT/scripts/linux/base_build.sh prereqs madara gams vrep tests java

Build C++ with Tests and Android support

$GAMS_ROOT/scripts/linux/base_build.sh prereqs madara gams vrep tests android

Build C++ with ROS support

$GAMS_ROOT/scripts/linux/base_build.sh prereqs madara gams ros

General Linux Build Notes

By default, the base_build.sh script will download GAMS, MADARA, and VREP to the directory you are calling base_build.sh from. If you want it to rebuild pre-existing installations, then you need to set GAMS_ROOT, MADARA_ROOT, and VREP_ROOT to other locations on your harddrive. Don't forget to include the prereqs option on first installation or usage of new features to install feature prerequisites with apt-get install.

To update an existing installation, you can call the above scripts again with the arguments detailing what you would like to update (e.g. madara for updating MADARA), and the script will only update what you ask it to update.

For instance, if you just want to update GAMS and rebuild it with ROS support, simply do the following:

$GAMS_ROOT/scripts/linux/base_build.sh gams ros

This will not attempt to install prereqs or any of the other software (such as ACE or MADARA), but will do a git pull inside of the $GAMS_ROOT directory and then remake GAMS with ROS support.

Help is built-in. To print options, pass in an argument that doesn't exist--such as "help"

$GAMS_ROOT/scripts/linux/base_build.sh help

Notes on ROS Support

If you are intending to build GAMS to work with or along side a ROS based system, please be aware that GAMS is at the moment targeted to support ROS Kame Kinetic. It may work with other versions but support and development is targeted towards ROS Kinetic platforms. The above base_build.sh script handles all dependencies that GAMS requires for ROS if this is the case. Because of such ROS versioning, it is recommended that you stick to Ubuntu 16.04, not 18.


Mac OS X

These instructions have been tested with Mac OS X Yosemite, but should work for versions since Mac OS X Lion.

Several environment variables need to be set. $HOME is the users home directory. The $PROJECT_HOME environment variable is optional and will be used throughout these instructions as the common download directory for each of the repositories. $MADARA_ROOT and $GAMS_ROOT are the repositories. $CORES is optional and used to parallelize the build jobs. $LD_LIBRARY_PATH must include $ACE_ROOT/lib, $MADARA_ROOT/lib, and $GAMS_ROOT/lib. Editing $PATH allows running the compiled binaries without specifying the full path to the binary. Run these commands to add these line to your .bashrc file and have the environment variables set every time you login.

echo "export PROJECT_HOME=\$HOME/projects" >> ~/.profile
echo "export MADARA_ROOT=\$PROJECT_HOME/madara" >> ~/.profile
echo "export GAMS_ROOT=\$PROJECT_HOME/gams" >> ~/.profile
echo "export LD_LIBRARY_PATH=\$LD_LIBRARY_PATH:\$ACE_ROOT/lib:\$MADARA_ROOT/lib:\$GAMS_ROOT/lib" >> ~/.profile
echo "export PATH=\$ACE_ROOT/bin:\$MADARA_ROOT/bin:\$GAMS_ROOT/bin:\$PATH" >> ~/.profile
echo "export CORES=4" >> ~/.profile

Download the PRO EDU version of V-REP from Coppelia Robotics. VREP_ROOT is required for compiling VREP simulation support. Adjust the path for your own VREP. Run the following command to add this line to your .profile file and have the change applied.

echo "export VREP_ROOT=\$HOME/V-REP_PRO_EDU_V3_2_1_Mac" >> ~/.profile

The Oracle JDK or OpenJDK is required, preferably 1.8. Follow the instructions from Oracle to install Java.

JAVA_HOME must be set to JDK install directory. Java and Android builds require JAVA_HOME, update for your setup. Add this to your .profile file with the following command.

echo "export JAVA_HOME=`/usr/libexec/java_home`" >> ~/.profile

Log out and log back in or run source ~/.profile to have all environment variable changes applied.

The ACE, MADARA, and GAMS code bases must be acquired. Each of the repositories are in either Subversion or Git. Subversion and Git are part of the XCode command line tools package and can be downloaded through XCode or through Terminal:

xcode-select --install

Download the repositories:

svn checkout svn://svn.dre.vanderbilt.edu/DOC/Middleware/sets-anon/ACE $PROJECT_HOME/ace
git clone git://git.code.sf.net/p/madara/code $PROJECT_HOME/madara
git clone https://github.com/jredmondson/gams $PROJECT_HOME/gams

After following these instructions, the following values should be in your .profile file, an example is shown below:

############### ENVIRONMENT VARIABLES. FEEL FREE TO COPY THIS TO YOUR .BASHRC FILE ########################
# We are installing ACE, MADARA, and GAMS to your $HOME directory in a subdir called projects
# Feel free to change PROJECTS_ROOT to point wherever you want these installed
export HOME=/Users/aldukeman   # update this with your actual HOME directory
export PROJECTS_ROOT=$HOME/projects
export ACE_ROOT=$PROJECTS_ROOT/ace/ACE_wrappers
export MADARA_ROOT=$PROJECTS_ROOT/madara
export GAMS_ROOT=$PROJECTS_ROOT/gams

# JAVA_HOME will change depending on your system, make sure to set the correct value.
# If you used the copy and paste instructions above, the Oracle VM and JDK should be installed to the following
export JAVA_HOME=`/usr/libexec/java_home`

export LD_LIBRARY_PATH=$ACE_ROOT/lib:$MADARA_ROOT/lib:$GAMS_ROOT/lib:$LD_LIBRARY_PATH
export PATH=$ACE_ROOT/bin:$MADARA_ROOT/bin:$GAMS_ROOT/bin:$PATH
################ END ENVIRONMENT VARIABLES. Log out and back in for this to take effect
################################################################################################

The build scripts are located in $GAMS_ROOT/scripts/mac. Each of the files build_*.sh files calls base_build.sh with the arguments expected. build_c++.sh builds the C++ version of GAMS with V-REP support. build_java.sh builds the Java and C++ version of the GAMS. The C++ version is required due to extensive use of JNI in the Java JAR. build_android.sh builds the Java and C++ version of GAMS using a cross-compiler. Each of the build_*.sh scripts can take arguments to add to the ones required for C++ or Java. One of the arguments can be the version of Mac to compile for ("lion", "mountainlion", "mavericks", or "yosemite"). If the version is missing, then the script attempts to auto-detect it. The other arguments are identical to the ones available in base_build.sh and are explained in the next paragraph.

base_build.sh can be called directly to compile GAMS. The available options are <mac_version>, tests, vrep, java, and android. The tests option compiles the test executables. The vrep option adds support for VREP. The java option additionally compiles the JAR for using GAMS in Java. The android option uses a cross-compiler to compile GAMS for Android. <mac_version> is the version of Mac to compile for which to compile GAMS ("lion", "mountainlion", "mavericks", or "yosemite"). If it is not included, then the script attempts to auto-detect it. These scripts have only been tested with OS X Yosemite, but should work for versions as old as OS X Lion.


Windows

To install on Windows, you should understand that the old build instructions at Sourceforge are slightly wrong. We are moving away from ACE (from the CORBA/ACE+TAO world) and are instead using STL and Boost where possible for threading, OS functionality, etc. The new requirements for installing base MADARA on Windows are the following:


Windows Prerequisites

  • Install Perl (ActiveState)
  • Install Git (TortoiseGit), which requires Git for Windows. It is highly recommended that when prompted to install command line tools, do so. The Windows Builds instructions below expect you to have command line git available. If you don't, download the MADARA repo as you would do normally with how you are comfortable on Windows.
  • Download Boost (Boost)
  • Install Oracle JDK (if you want Java) (preferably 1.8)
  • Install Visual Studio (recommend 2017 but 2015 also works)
  • Install Copellia Robotics VREP (if you want its simulation environment) (http://www.coppeliarobotics.com/downloads.html)

Windows Build

:: Open up the Visual Studio Command Line for building. For VS 2017, it can be invoked with the following:
"C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\Common7\Tools\VsDevCmd.bat"

:: Build the system module for Boost. The following will build debug and release versions of 32 bit and 64 bit Boost
cd %BOOST_ROOT%
.\bootstrap.bat
.\b2 --with-system

:: set environment variables for BOOST locally but these should really be set in your computer's user or system
:: environment variables
set BOOST_ROOT=c:\code\boost\boost_1_67_0
set BOOST_STATIC_LIB_PREFIX=lib
set PROJECTS_ROOT=C:\code
set MADARA_ROOT=%PROJECTS_ROOT%\madara
set GAMS_ROOT=%PROJECTS_ROOT%\gams
set MPC_ROOT=%PROJECTS_ROOT%\MPC
set EIGEN_ROOT=%PROJECTS_ROOT%\eigen
set PATH=%PATH%:%BOOST_ROOT%/stage/lib:%MADARA_ROOT%/lib:%GAMS_ROOT%/lib

:: if building for VS 2015, also set the following:
set BOOST_TOOLSET=vc140

:: Download MPC (the build system we're currently using for MADARA)
git clone https://github.com/DOCGroup/MPC.git %MPC_ROOT%
git clone https://github.com/eigenteam/eigen-git-mirror.git %EIGEN_ROOT%

:: Do a git clone of MADARA into a directory you want MADARA installed into
git clone -b master https://github.com/jredmondson/madara %MADARA_ROOT%
git clone -b master https://github.com/jredmondson/gams %GAMS_ROOT%

:: Generate MADARA build files with whatever features you want for the toolset you want to build with
:: toolset recommendations: vs2017 or vc14 (VS 2015)
:: See the default features file at %MADARA_ROOT%\default.features for all supported features
cd %MADARA_ROOT%
%MPC_ROOT%\mwc.pl -type vs2017 -features tests=1 MADARA.mwc
MADARA.sln

:: The above should open MADARA.sln. It is recommended that you build the main MADARA project in Debug and Release
:: and that you build all tests for Release. All projects should likely be 64 bit on the target. Building for 32 bit
:: will require setting %BOOST_ARCH% to x32 on the command line BEFORE you call mwc.pl above. Also, definitely
:: enable Multi-processor Compilation. This will use all of your processor cores to compile.

:: Generate GAMS build files with whatever features you want for the toolset you want to build with
:: toolset recommendations: vs2017 or vc14 (VS 2015)
:: See the default features file at %GAMS_ROOT%\default.features for all supported features
cd %GAMS_ROOT%
%MPC_ROOT%\mwc.pl -type vs2017 -features tests=1,vrep=0 gams.mwc
gams.sln

:: The above should open gams.sln. It is recommended that you build the main MADARA project in Debug and Release
:: and that you build all tests for Release. All projects should likely be 64 bit on the target. Building for 32 bit
:: will require setting %BOOST_ARCH% to x32 on the command line BEFORE you call mwc.pl above. Also, definitely
:: enable Multi-processor Compilation. This will use all of your processor cores to compile.

Set Environment Variables

You're going to want to set a few environment variables in order to refer to MADARA and GAMS in your installation. Most of them are required for your installation and programs to function correctly.

On Windows, to change environment variables, you need to do the following. First, click your Start Menu, right click on "Computer", and then right click "Properties". This is shown in the image below.

Click Properties from your Computer

Click the "Environment Variables" button, and then set your environment variables in the User section. You can set them in the System section if you want other users to be able to develop GAMS applications. Here are the variables you need to setup.

  • MADARA_ROOT needs to be set to the directory MADARA is downloaded to (e.g., %PROJECTS_DIR%\madara)
  • GAMS_ROOT needs to be set to the directory GAMS is downloaded to (e.g., %PROJECTS_DIR%\gams)
  • PATH will need to have %ACE_ROOT%\lib;%ACE_ROOT%\bin;%MADARA_ROOT%\lib;%GAMS_ROOT%\lib added to it either in User or System
  • VREP_ROOT needs to be set to the directory where you can see the vrep executable

And this is what the resulting Environment Variables dialog might look like:

Example Environment Variables setup

IMPORTANT: the MADARA_ROOT and GAMS_ROOT should point to locations that have "lib" directories inside of them. If you do not see a "lib" directory inside of %MADARA_ROOT% or %GAMS_ROOT%, adjust your environment variables to the locations that do have that directory inside of them.

Do remember that if you are including VREP support, then VREP_ROOT will also need to be set appropriately.

Android Build

Currently Android build is supported only on Linux. So the instructions for building android version of GAMS & MADARA are similar to that of building them on Linux.

Prerequisites:

  • Linux & corresponding dependencies for GAMS & MADARA as mentioned above.
  • Android NDK [r16b at the time of writing this wiki instruction]. In case NDK is already available set NDK_ROOT to avoid downloading it automatically.
  • Boost for Android [1.65.1 at the time of writing this wiki instruction]. In case Boost for Android libraries are already available, set BOOST_ANDROID_ROOT environment variable to point it to the root directory. If you want to build Boost-for-Android manually, check out the repo here

To cross-compile GAMS & MADARA for android:

$GAMS_ROOT/scripts/linux/base_build.sh prereqs gams madara android

If prereqs option is used with base_build the corresponding NDK and Boost for Android libraries are downloaded and installed automatically in the $INSTALL_DIR directory.

By default the build cross-compiles GAMS & MADARA libraries for armeabi-v7a architecture. In case different architecture is required, export ANDROID_ARCH environment variable. The ANDROID_ARCH variable can be either of armeabi-v7a, arm64, x86 or x86_64

Android Tests

Using android-tests option with base_build will generate and run an Android app on a real android device or an emulator. Connect the device via USB or start an emulator before executing this command. The command will execute instrumentation tests on device/emulator, show the results on command line and remove the instrumentation apps from device/emulator after tests are executed. This command expects adb is pre-installed in the system.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.