ArtiSynth Installation Guide for Windows

12 Updating ArtiSynth

One reason to install ArtiSynth from GitHub is to be able to update the codebase to incorporate new features and bug fixes. When a significant update occurs, a posting is made to the ArtiSynth update log, currently located at www.artisynth.org/doc/html/updates/updates.html. Users may also be notified via the artisynth-updates email list.

Eclipse users may update simply by selecting the artisynth_core in the Package Explorer and then right clicking and choosing Team > Pull.

If Git for Windows is installed (Section 6.2), then updating may be done using GitBash:

 $ cd <ARTISYNTH_HOME>
 $ git pull

After pulling from the command line, ArtiSynth should be recompiled, using either make or compile.

Other Git-based projects, such as artisynth_models, may be updated similarly.

12.1 Library updates

An update may also change the libraries that ArtiSynth needs, as listed in the file <ARTISYNTH_HOME>\lib\LIBRARIES. Such changes are normally handled automatically:

  • •

    In Eclipse, any new or changed libraries are downloaded the next time the project is built, as during installation (Section 6.1).

  • •

    When compiling with make, any new or changed libraries are downloaded before compilation begins.

  • •

    When ArtiSynth starts up, it checks that all the required libraries are present and downloads any that are missing.

In each case, older versions of the libraries, and libraries that are no longer needed, are removed from <ARTISYNTH_HOME>\lib.

Libraries can also be updated explicitly using the command updateArtisynthLibs located in <ARTISYNTH_HOME>\bin, which can be run from a terminal window:

 > cd <ARTISYNTH_HOME>
 > bin\updateArtisynthLibs

or, from within Eclipse, by selecting Run > External Tools > UpdateArtisynthLibs from the main menu. Selecting “Update libraries” from the ArtiSynth File menu, or running ArtiSynth with the -updateLibs option, will also check that the installed libraries match the latest versions on the ArtiSynth server.

12.2 Refused pulls

If you have modified files in artisynth_core (or another ArtiSynth-supported project such as artisynth_models) which are also changed by the update, Git will refuse the pull, and list the files concerned.

Figure 4: Eclipse Pull Problem box, with the details exposed after clicking the Details button.

If the pull was attempted using Team > Pull in Eclipse, then a Pull Problem box will appear (Figure 4). Clicking Details will provide further information, with the conflicting files listed after the words “Checkout conflict with files”.

If the pull was attempted on the command line, then the pull will fail with a message similar to

 error: Your local changes to the following files would be overwritten by merge:
         .classpath
         .project
         ArtiSynth.launch
 Please commit your changes or stash them before you merge.

Nothing is lost when this happens: your files and the codebase remain as they were. However, in order to proceed with the pull, you need to either discard the conflicting files, or attempt to merge them.

12.2.1 Discarding the conflicting files

If you do not need your changes to the listed files, the simplest remedy is to discard them and then pull again. This is especially recommended when the conflicting files are Eclipse project files, such as .project, .classpath, ArtiSynth.launch, or files under .settings. Ideally these files are not modified by the user at all (see the side block below), but if they are, it is usually easiest to remove them and re-apply your changes after the pull.

Two ways to easily discard the files are:

  • •

    In a file browser or from a CMD or GitBash window, simply delete the given files, and then pull again; the pull will restore the files in their updated form. (You can also rename the files if you want to later try to merge back your local changes.)

    Important: if you pull again in Eclipse, avoid refreshing the project before doing Team > Pull, as this might cause certain project files (like .classpath) to be rebuilt.

  • •

    From a CMD or GitBash window, run

     > git checkout -- <file1> <file2> ...
 > git pull

    where <file1> <file2> ... are the path names of the conflicting files.

ArtiSynth.launch is modified locally when a user edits the ArtiSynth launch configuration to set environment variables or ArtiSynth/JVM arguments (Sections 13.4.1 and 13.5), or to add external projects (Section 13.7), without first making a local copy of it (Section 13.3). A local launch configuration copy will avoid conflicts.
.classpath may get modified if the user adds extra .jar files or external projects to the project build path. There is normally no need to do this: projects such as artisynth_core and artisynth_models are configured with the resources required to build them, and any new classes requiring additional resources should be placed in a separate project.
.project should not normally be modified, but might be to provide interoperability with other IDEs such as VS Code.
Files in .settings/ are modified when a user changes the project properties, such as via Project > Properties.

12.2.2 Merge the conflicting files

If you want to try to keep your changes, two ways to do this are:

  • •

    Use a stash/pull/pop sequence. From a CMD or GitBash window, run

     > git stash
 > git pull
 > git stash pop

    If your changes conflict with those of the update, git stash pop will report a conflict, which must then be resolved by editing the files concerned. Conflict resolution at the command line level is outside the scope of this document, but documentation is available online.

  • •

    Within Eclipse, you can commit your changes (using the Git Staging view or Team > Commit), and then choose Team > Pull. Any conflicts can then be resolved using Team > Merge Tool, as described in the section “Resolving a merge conflict” of the EGit User Guide. Note that your local branch will then contain your own commit, so that subsequent pulls will also produce merges.