ArtiSynth Installation Guide for Linux

6 Installing from GitHub

For most users doing active modeling work, we recommend installing the current ArtiSynth development version from GitHub, which will provide ongoing access to updates and bug fixes. GitHub is a web-based repository service based on the source control management system Git. A very brief summary of Git is given in Section 14.5.

ArtiSynth is available from GitHub at the URL

   https://github.com/artisynth/artisynth_core.git

After installation, users can continually update the ArtiSynth codebase to the latest version using pull operations (Section 12). In some cases, developers we work with closely can also obtain, by mutual arrangement, write access to our GitHub repository, allowing them to also commit changes.

Users who have a GitHub account combined with SSH keys may instead wish to clone using the SSH URL

   git@github.com:artisynth/artisynth_core.git

For users with repository write access, this will allow them to perform subsequent push operations without having to enter a username and password.

6.1 Installation using Eclipse

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.

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.

6.2 Installation using the command line

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

 > cd /path/to/install
 > git clone https://github.com/artisynth/artisynth_core
 > cd artisynth_core
 > bin/updateArtisynthLibs

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

 > make

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:

 > bin/compile

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

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.