14 Additional Information

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 (or create the file if it does not already exist) 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 MacOS 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.

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 14.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. If not set, the system uses the maximum number of cores available. Users can also set this number from within ArtiSynth by setting the configuration property numSolverThreads, either for the current session by choosing “Settings > Interaction ...” from the main menu, or for all sessions by choosing “Settings > Preferences ... > Interaction”.

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

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 12). 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.

The EXTCLASSPATH file is stored in the user configuration folder (Section 9) and contains the entries for the external class path (Section 10.2.2). It is usually edited within ArtiSynth by selecting “External classpath ...” from the Settings menu but can also be edited directly. Each file entry describes a class directory or JAR file needed to run models external to the core ArtiSynth package. Entries are usually placed 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

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