ArtiSynth Installation Guide for Windows

14 Additional Information

14.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 command window such as CMD.

14.1.1 Windows 10

  1. 1.

    Open the Start search, enter “env”, and choose “Edit the system environment variables”.

  2. 2.

    Click on Environment Variables.

  3. 3.

    Under User variables (the top window), click on Path and click Edit. If Path does not exist, click New.

  4. 4.

    In the Edit environment variable dialog, click New and enter the full path name for each directory you wish to add.

  5. 5.

    Close each dialog by clicking OK.

14.1.2 Windows 8 and earlier

  1. 1.

    Right-click My Computer, and then click Properties.

  2. 2.

    Click the Advanced tab.

  3. 3.

    Click Environment variables.

  4. 4.

    In the top User variables window, click on Path and then Edit. If Path does not exist, click New.

  5. 5.

    In the edit window, add the full path name for each new directory, separated by semi-colons ‘;’.

  6. 6.

    Close each dialog by clicking OK.

For example, if ArtiSynth is installed at C:\artisynth\artisynth_core and the desired JDK is at C:\Program Files\Java\jdk1.8.0_281, then we can add the bin directories for both by setting the User path to

  C:\artisynth\artisynth_core\bin;C:\Program Files\Java\jdk1.8.0_281\bin

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

14.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 folder.

CLASSPATH

A list of folders and/or JAR files, separated by semi-colons ‘;’, which Java uses to locate its class files.

Path

A list of folders, separated by semi-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.

14.2.1 Setting environment variables

On Windows, a user can view, set, or change environment variables via the following steps:

Windows 10:

  1. 1.

    Open the Start search, enter “env”, and choose “Edit the system environment variables”.

  2. 2.

    Click on Environment Variables.

  3. 3.

    Choose one of the following options:

    • Click New to add a new variable name and value.

    • Click an existing variable, and then Edit to change its name or value.

    • Click an existing variable, and then Delete to remove it.

  4. 4.

    Close each dialog by clicking OK.

Windows 8 and earlier:

  1. 1.

    Right-click My Computer, and then click Properties.

  2. 2.

    Click the Advanced tab.

  3. 3.

    Click Environment variables.

  4. 4.

    Choose one of the following options:

    • Click New to add a new variable name and value.

    • Click an existing variable, and then Edit to change its name or value.

    • Click an existing variable, and then Delete to remove it.

  5. 5.

    Close each dialog by clicking OK.

Variable settings can reference other environment variables by surrounding them with percent signs, as in %VAR_NAME%. For example, suppose you already have an environment variable HOME that gives the location of your home folder, and your ArtiSynth distribution is located in packages\artisynth_core relative to your home folder. Then the environment variable ARTISYNTH_HOME can be specified as

  %HOME%\packages\artisynth_core

14.2.2 Typical environment settings

Typical settings for the environment variables described above might look like this:

ARTISYNTH_HOME c:\users\joe\artisynth_core
CLASSPATH %ARTISYNTH_HOME%\classes;%ARTISYNTH_HOME%\lib\*
PATH %ARTISYNTH_HOME%\bin;%PATH%

14.2.3 GitBash environment settings

When using GitBash (Section 6.2), it is possible to set environment variables in a .bashrc file located in the user’s home folder. The file entries corresponding to the settings of Section 14.2.2 would look like this:

# set ARTISYNTH_HOME to the appropriate location ...
export ARTISYNTH_HOME=C:/users/joe/artisynth_core
# Windows file notation is needed for CLASSPATH:
AH="C:\users\joe\/artisynth_core"
export CLASSPATH="$AH\classes;$AH\lib\*"
export PATH=$ARTISYNTH_HOME/bin:$PATH

Note that the CLASSPATH environment variable must be set using a Windows format, with backslash (’\’) to separate files and semicolon (’;’) to separate path entries. This requirement is imposed by the Java compiler.

14.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-folders (Windows64 for 64-bit Windows 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.

14.4 The EXTCLASSPATH File

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 folder 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 semi-colons ‘;’.

The syntax rules for EXTCLASSPATH are:

  1. 1.

    Entries on the same line should be separated semi-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:

C:\research\artisynth_models\classes
C:\research\models\special.jar
$HOME\projects\crazy\classes

14.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 folder 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 folder specified by <dir>, or in artisynth_core if <dir> is omitted. The repository itself will be located in a sub-folder 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 folder 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 folders, 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