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. If multiple branches are available, make sure that only master is selected. Click Next.

5. 5.

   A Local Destination dialog will appear as shown below, indicating the folder into which ArtiSynth will be placed locally. Use the default location, or edit it to the desired location. This will be your ArtiSynth home folder, 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 a 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, and Eclipse will begin to build it, first by automatically downloading the Java and native libraries that ArtiSynth needs. (These are not included in the GitHub repository because they are quite large.) The download can be on the order of 200 Mbytes, and so may take up to several minutes, depending on network speed. Its progress is shown in Eclipse’s Console view, at the bottom of the Eclipse window:

On some versions of Eclipse, the console view may need to be opened explicitly, by selecting Window > Show View > Console from the main menu.

When the download is complete, the console will display the message LIBRARIES UPDATED SUCCESSFULLY:

Eclipse will then compile ArtiSynth, with the progress bar at the lower right showing compilation progress.

If some libraries could not be downloaded (e.g., because of a network problem), the console will say so, and the artisynth_core project will be marked with errors. After checking your network connection, you can retry the download by selecting Run > External Tools > UpdateArtisynthLibs from the main menu, or Project > Clean....

ArtiSynth is currently compiled to be compliant with Java 8, regardless of the Java version. The Eclipse settings supplied in artisynth_core\.settings ensure this. This will be raised to Java 21 in the near future.

After compilation is complete, ArtiSynth can be run by selecting artisynth_core in the Package Explorer and choosing Run > Run from the main menu:

Alternatively, you can click the small arrow beside the green Run button in the Eclipse toolbar and choose ArtiSynth. Either way works by invoking a predefined launch configuration named ArtiSynth. In some cases, one may wish to adjust the 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.4 and 13.5.

It is also possible to run ArtiSynth from either a file browser or a terminal window, as described in Sections 5.1 and 5.2, respectively. Details on how to load and run demo models are given in Section 7.

Git for Windows is an application that provides the user with a terminal window interface that can be used for entering Git commands. Users can choose between GitBash, which provides a Unix-like bash shell, or GitCMD, which provides a Windows CMD shell. GitBash has several advantages, such as allowing users to easily set environment variables in a .bashrc file (Section 14.2.3), and supplying a number of Unix-like commands that can be convenient for tasks other than those involving Git.

At the time of this writing, Git for Windows can be installed from git-scm.com/download/win.

Once installed, ArtiSynth can then be installed and compiled by opening a GitBash window and entering the following commands (where the ‘$’ character indicates the GitBash prompt and should not be entered):

The first line simply sets the current folder to the one under which you wish to install ArtiSynth, as indicated by /path/to/install. (Note that GitBash follows the Unix convention of using forward slash (’/’) instead of backslash (’\’) to separate files.) 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, and the bin/compile command on the last line is an ArtiSynth-supplied utility that compiles all .java files located under the current folder. The updateArtisynthLibs and compile commands use the java and javac commands of your JDK, which must be visible from the command window (Section 4.1).

If you have GNU make installed on your system, then you can use that instead of the compile command, replacing

with

make also downloads any missing libraries automatically, so when using it, the updateArtisynthLibs step can be omitted.

ArtiSynth is currently compiled to be compliant with Java 8, regardless of the JDK version. The make and compile commands described above ensure this. This will be raised to Java 21 in the near future.

The make and compile commands automatically determine the Java classpath needed to compile ArtiSynth, consisting of the classes folder plus the .jar files listed in lib\LIBRARIES. If you have set the CLASSPATH environment variable, its entries are appended to this, except for any that refer to the lib folder. See Sections 10.1.2 and 14.2.

Once built, ArtiSynth can then be run (from within artisynth_core) using the command

For convenience, if you place <ARTISYNTH_HOME>\bin in your Path environment variable (Section 14.1), then ArtiSynth can be run independently of the current directory using the simple command

 % artisynth

ArtiSynth can also be installed and compiled using GitCMD, with an analogous command sequence:

The only real difference is using backslash (’\’) instead of forward slash (’/’) as a file separator.

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.