6 Installing from GitHub

If you are planning to use the Eclipse IDE (Section 13), you can install from GitHub directly into Eclipse. Directions on installing Eclipse and configuring it for ArtiSynth development are given in Section 13.1. Once Eclipse is installed, ArtiSynth can be installed as follows:

1. 1.

   From the main menu, select “File > Import ...”. This will cause an Import dialog to appear, as shown below. Open “Git > Projects from Git”, and then click Next.

   
2. 2.

   In the next dialog, choose Clone URI, and click Next.

3. 3.

   A Source Git Repository dialog will appear, as shown below. In the URI field at the top, enter
   https://github.com/artisynth/artisynth_core.git
   This will automatically fill the Host and Repository path fields. Click Next.

   
4. 4.

   A Branch Selection dialog will appear; uncheck svn, so that only master is selected. Click Next.

5. 5.

   A Local Destination dialog will appear as shown below, indicating the directory into which ArtiSynth will be placed locally. Use the default location, or edit it to the desired location. This will be your ArtiSynth home directory, and will be referred to later in this document as <ARTISYNTH_HOME>. Click Next.

   
6. 6.

   ArtiSynth will now be downloaded; this may take a few minutes, depending on your network connection speed. Another dialog will appear, asking you to select to project import wizard. Leave the default (“Import existing Eclipse projects”) selected, and click Next.

7. 7.

   An Import Projects dialog will appear, confirming that you want to import artisynth_core. Leave everything as is, and click Finish.

artisynth_core has now been imported into Eclipse as a project. However, we are not quite done. Eclipse will try to compile artisynth_core, but will fail because some Java and native libraries are missing. (These libraries are not included in the GitHub repository because they are quite large.) The compile failure will be indicated by a red exclamation mark to the left of the artisynth_core project entry in the Package Explorer:

The Java and native libraries must be downloaded separately, outside of Eclipse. Open a terminal window, change directories to <ARTISYNTH_HOME>, and run the command bin/updateArtisynthLibs:

 > cd /path/to/ARTISYNTH_HOME
 > bin/updateArtisynthLibs

The process may take a few minutes, depending on network speed.

When the libraries are loaded, return to Eclipse, click on the artisynth_core project to select it, then “refresh”, either by right clicking and selecting Refresh, or by hitting the F5 key. Eclipse should now find the libraries and compile ArtiSynth; a green progress bar will appear at the lower right while compilation is in progress.

Regardless of the JDK version, ArtiSynth is compiled to be compliant with Java 8, to ensure compatibility with MATLAB. The Eclipse settings supplied in artisynth_core/.settings will ensure Java 8 compliance.

After compilation is complete, ArtiSynth can be run by simply choosing Run > Run from the main menu. This works by invoking a predefined launch configuration named ArtiSynth. In some cases, one may wish to adjust this launch configuration to set environment variables, command line arguments, or Java JVM arguments that affect how ArtiSynth behaves. Instructions for doing so are contained in Sections 13.3 and 13.4.

It is also possible to run ArtiSynth from a terminal window, as described in Section 5.1. Detail on how to load and run demo models are given in Section 7.

If your Linux distribution has Git installed, then you can install ArtiSynth from a terminal window using the following commands:

The first line simply sets the current directory to the one under which you wish to install ArtiSynth, as indicated by /path/to/install. The git clone command then downloads ArtiSynth and extracts it to a folder named artisynth_core, so that the ArtiSynth installation directory (or <ARTISYNTH_HOME>) is /path/to/install/artisynth_core. The updateArtisynthLibs command fetches additional libraries that are not included in the GitHub repository for space reasons.

ArtiSynth can then be compiled using the command

within the artisynth_core directory.

The make command and the associated Makefile automatically determine the Java classpath needed to compile ArtiSynth. However, if you have explicitly set the CLASSPATH environment variable, then that will be used to define the classpath instead, in which case it must contain the classes folder (located under the artisynth_core directory), as well as the .jar files in the lib directory. See Sections 10.1.2 and 14.2.

As an alternative to make, one can also compile ArtiSynth using the compile command:

compile is an ArtiSynth command line utility that compiles all .java files located under the current directory.

Regardless of the JDK version, ArtiSynth is compiled to be compliant with Java 8, to ensure compatibility with MATLAB. The make or compile commands described above are configured to ensure Java 8 compliance.

Once compiled, ArtiSynth can be run from the command line as described in Section 5.1.

Details on how to load and run demo models are given in Section 7.

Note that once you have installed ArtiSynth, you still have the option to later import it into an IDE such as Eclipse. For Eclipse specifically, this is done by importing it as an external project, as described in Section 13.2.