ArtiSynth Installation Guide for MacOS

13 Additional Information

13.1 Adding Directories to the System Path

The system “Path” is a list of directories which the system searches in order to find executables. Adding a directory to the path allows executables contained in that directory to be called directly from a terminal window.

Since MacOS is a Unix-based system, directories can be added to the path by appending them to the PATH environment variable, which is a list of directories separated by colons ‘:’. The most direct way to do this is to redefine PATH inside one of the initialization files for whichever command line shell you are using.

Assume that your home folder is <HOMEDIR>. Then for the bash shell, one can edit <HOMEDIR>/.bashrc and insert a line of the form

   export PATH=<DIR>:$PATH

while for the csh or tcsh shells, one can edit <HOMEDIR>/.cshrc and insert a line of the form

   setenv PATH <DIR>":"$PATH

On Mac OS X 10.8 and greater, directories can also be added to the path by adding a text file containing the directories to /etc/paths.d. In particular, we can create a file called ArtiSynth in /etc/paths.d that contains the full path names of the desired directories.

  1. 1.

    Open a terminal window

  2. 2.

    Use sudo to create /etc/paths.d/ArtiSynth with a plain text editor. For example:

      sudo nano /etc/paths.d/ArtiSynth
    
  3. 3.

    Add the full path name of each desired directory, one per line, and save the file.

  4. 4.

    To test the revised PATH, open a new terminal window and enter the command: echo $PATH.

Most most command windows and applications need to be restarted in order to get them to notice changes to PATH.

13.2 Environment variables

This is a glossary of all the environment variables that are associated with building or running ArtiSynth. Often, the system can detect and set appropriate values for these automatically. In other cases, as noted in the above documentation, it may be necessary or desirable for the user to set them explicitly.

ARTISYNTH_HOME

The path name of the ArtiSynth installation directory.

CLASSPATH

A list of directories and/or JAR files, separated by colons ‘:’, which Java uses to locate its class files.

PATH

A list of directories, separated by colons ‘:’, which the operating system uses to locate executable programs and applications. Placing <ARTISYNTH_HOME>/bin in PATH (as described in Section 13.1) will allow you to run artisynth and related commands directly from a command window.

OMP_NUM_THREADS

Specifies the maximum number of processor cores that are available for multicore execution. Setting this variable to the maximum number of cores on your machine can significantly increase performance.

Note that settings for most of the above can be derived from the value of ARTISYNTH_HOME.

13.2.1 Example environment set up for bash

If you are using bash as your shell, then the environment can be configured by placing a block of commands similar to the following in one of your bash initialization files (typically ~/.bashrc), located in your home directory:

# set ARTISYNTH_HOME to the appropriate location ...
export ARTISYNTH_HOME=$HOME/artisynth_core
export CLASSPATH="$ARTISYNTH_HOME/classes:$ARTISYNTH_HOME/lib/*"
export PATH="$ARTISYNTH_HOME/bin:$PATH"
# Set to the number of cores on your machine:
export OMP_NUM_THREADS=4

Be sure to set ARTISYNTH_HOME to the proper location of your ArtiSynth installation directory.

These environment variables will be passed on to any program which you run from the shell (such as artisynth or eclipse). However, they will not be passed on to programs (such as eclipse) which you launch from the dock.

Alternatively, you can source the script setup.bash, located in the installation directory:

 > source setup.bash

This will determine the system type automatically and set the environment variables accordingly, with ARTISYNTH_HOME set to the current directory from which the script is called (however, it won’t set OMP_NUM_THREADS).

13.2.2 Example environment setup for csh or tcsh

If you are using csh or tcsh as your shell, then the environment can be configured by placing a block of commands similar to the following in your .cshrc file, located in your home directory:

# set ARTISYNTH_HOME to the appropriate location ...
setenv ARTISYNTH_HOME $HOME/artisynth_core
setenv CLASSPATH "$ARTISYNTH_HOME/classes:$ARTISYNTH_HOME/lib/*:$CLASSPATH"
setenv PATH $ARTISYNTH_HOME/bin":"$PATH
# Set to the number of cores on your machine:
setenv OMP_NUM_THREADS 4

These environment variables will be passed on to any program which you run from the shell (such as artisynth or eclipse). However, they will not be passed on to programs (such as eclipse) which you launch from the dock.

Alternatively, you can source the script setup.csh, located in the installation directory:

 > source setup.csh

This will determine the system type automatically and set the environment variables accordingly, with ARTISYNTH_HOME set to the current directory from which the script is called (however, it won’t set OMP_NUM_THREADS).

13.3 ArtiSynth Libraries

ArtiSynth uses a set of libraries located under <ARTISYNTH_HOME>/lib. These include a number of JAR files, plus native libraries located in architecture-specific sub-directories (MacOS64 for MacOS systems).

As described in Section 6, these libraries need to be downloaded automatically if the system is obtained from the GitHub repository. The required libraries are listed in the file <ARTISYNTH_HOME>/lib/LIBRARIES. This file is checked into the repository, so that the system can always determine what libraries are needed for a particular checkout version.

Occasionally the libraries are changed or upgraded (Section 11). If you run ArtiSynth with the -updateLibs command line option, the program will ensure that not only are all the required libraries present, but that they also match the latest versions on the ArtiSynth server.

13.4 The EXTCLASSPATH File

In order to run an external model in ArtiSynth, all class directories and JAR files associated with those external models must be made visible to ArtiSynth. One way to do this is to list these as entries in a text file named EXTCLASSPATH, located in <ARTISYNTH_HOME>.

Using a plain text editor (such as vim, gedit, or emacs), open EXTCLASSPATH (or create it if it does not already exist) and add the required class directories and JAR files. Usually these are added one per line, but multiple entries can be made on the same line if separated by colons ‘:’.

The syntax rules for EXTCLASSPATH are:

  1. 1.

    Entries on the same line should be separated colons ‘:’.

  2. 2.

    The ‘#’ character comments out all remaining characters to the end of line.

  3. 3.

    The ‘$’ character can be used to expand environment variables.

  4. 4.

    Any spaces present will be included in the entry name.

An example EXTCLASSPATH might look like this:

/research/artisynth_models/classes
/research/models/special.jar
$HOME/projects/crazy/classes

13.5 Quick Git Summary

Git is a distributed source control management (SCM) system that is widely used in the software industry. A full discussion of Git is beyond the scope of this document, but a large literature is available online. Generally, when you clone a Git repository, you create a local copy of that repository on your machine, along with a checked out working directory containing the most recent version of the code (which is referred to as the HEAD).

Unlike client/server SCMs, Git is distributed, with users maintaining their own private copies of a repository. This allows a great deal of flexibility in usage, but also adds an extra “layer” to the workflow: when you “checkout” from a repository or “commit” to it, you do so with respect to your own local copy of that repository, not the original (origin) repository from which you performed the original clone. The process of merging in changes from the origin to the local repository is known as “pulling”, while committing changes from the local repository back to the origin is known as “pushing”.

There is also another layer of interaction when you commit changes to the local repository: you first add them to a staging area (also known as the “index”), and then commit them using the commit command.

A very simple workflow for a typical ArtiSynth user is summarized below. The actions are described in command-line form, but the same commands can generally be issued through Eclipse or other interfaces. First, clone the most recent version of the ArtiSynth repository on GitHub:

  git clone https://github.com/artisynth/artisynth_core.git [<dir>]

This will create a local copy of the GitHub repository, along with a checked out “working copy”, in the directory specified by <dir>, or in artisynth_core if <dir> is omitted. The repository itself will be located in a sub-directory called .git.

Other Git repositories can be cloned in a similar manner. If the repository has read access restrictions, then when performing a checkout it may also be necessary to specify a user name for which the repository has granted read access. This is typically done by embedding the user name in the URL, as in (for example):

https://user@host.xz/path/to/repo.git

Later, to fetch the latest updates from the GitHub repository and merge them into your working copy, from within the working copy directory you can do

  git pull

If you make changes to some files in your working copy and wish to commit these to your local repository, you first add (or remove them) from the staging area using commands such as:

  git add <fileName>    # add a new (or modified) file
  git add *             # add all files
  git rm <fileName>     # remove a file

and then commit them to your local repository using

  git commit -m "commit message"

Note that you can also add modified files and commit them using the single command

  git commit -m -a "commit message"

To see the current status of the files in your working copy and the staging area, use the command

  git status

and to see the commit history for particular files or directories, use

  git log [ <filename> ... ]

Finally, to push your changes back to the GitHub repository (assuming you have permission do so), you would do so using the command

  git push origin master

Note that the above commands all have various options not mentioned. There are also numerous topics that haven’t been discussed, including the creation and merging of branches, but there are many useful online resources that describe these in detail. Some current references include

   https://git-scm.com/docs
   http://rogerdudler.github.io/git-guide