Installing ArtiSynth from GitHub into Eclipse (MacOS)

This document describes how to install ArtiSynth directly from GitHub and import it into the Eclipse IDE (Integrated Development Environment), within a MacOS environment. While for demonstration purposes it is faster to install ArtiSynth using a precompiled release, installing from GitHub provides access to the most recent updates, and the Eclipse IDE is a convenient platform for developing and modifying the Java code used to create ArtiSynth models.

There are two parts to the installation process:

1. 1.

   Installing Eclipse

2. 2.

   Installing ArtiSynth from GitHub

Eclipse comes with its own version of Java, which is sufficient for compiling and running ArtiSynth within Eclipse, so you do not need to install Java separately. A separate Java development kit (JDK) is needed only in special cases, as described in Section 2.1.

This document is intentionally brief and describes only installation from Git into an Eclipse IDE. More complete instructions, including how to create and add models, integrate external models, and update ArtiSynth, are given in the general Installation Guide. Instructions for visualizing, navigating, editing and simulating models are given in the ArtiSynth User Interface Guide. Instructions on how to build a model using Java are given in the ArtiSynth Modeling Guide.

ArtiSynth runs on Macs based on either Apple silicon (the Apple M chips) or Intel processors. We recommend a minimum of 16 Gbytes of memory, and more is better if you are doing finite element work with larger numbers of elements.

Eclipse is an integrated development environment (IDE) that is commonly used for writing and maintaining Java programs. While other IDEs exist for Java, such as IntelliJ and VS Code, Eclipse is currently the most commonly used amongst ArtiSynth users. It should be noted, however, that an IDE is not required for Java programming; simpler programs, in particular, can often be created by editing the .java source files using a text editor and then compiling them with command line tools, including GNU make, if that is available, or the compile utility supplied by ArtiSynth.

Eclipse is released quarterly, with versions named by year and month (e.g., 2026-09). Any recent version should work; the instructions below use 2026-09 as an example.

Eclipse can be downloaded from www.eclipse.org/downloads/packages. From this page, choose “Eclipse IDE for Java Developers”, macOS AArch64 if your Mac uses Apple silicon, or macOS x86_64 if it uses an Intel processor. (To check, choose About This Mac from the Apple menu: the Chip entry will say “Apple M...” for Apple silicon.) This will download a file named

  eclipse-java-2026-09-R-macosx-cocoa-aarch64.dmg

or

  eclipse-java-2026-09-R-macosx-cocoa-x86_64.dmg

Open this file, and drag the Eclipse application into the Applications folder as indicated. Then open Eclipse from Applications. The following dialog will appear, asking you to select a workspace directory:

This is where Eclipse settings and project information will be stored. Unless you have another Eclipse already installed, the default location should be fine. (Remember also to check the “Use this as the default ...” box so that this query won’t appear every time you open Eclipse.) Next, click Launch. A welcome page will appear; close this. A “donate” panel may also appear; close this too. You should then see an empty Eclipse display, similar to this:

Before closing Eclipse, you may want to pin its icon to your dock to make it easier to restart.

You can now install ArtiSynth from GitHub.

1. 1.

   From the panel at the left of the main Eclipse frame, choose “Import projects...”. 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 directory into which ArtiSynth will be placed locally. Use the default location, or edit it to some other desired location. This will be your ArtiSynth installation directory. 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....

You should now be able to run ArtiSynth. Select the imported artisynth_core project in the Package Explorer panel on the left of the Eclipse window, and choose Run > Run from the main menu:

ArtiSynth will then start up (perhaps slowly the first time). Alternatively, you can click the small arrow beside the green Run button in the Eclipse toolbar, and choose ArtiSynth from the menu that appears.

Within ArtiSynth, you can then load a demonstration model by selecting Models > Demos from the main menu and choosing a demo model:

Once a model is loaded, it will appear in the viewer, and simulation can be controlled using the “play” controls located at the upper right of the application window:

From left to right, these are: step size control, which controls the simulation step size (in seconds); current simulation time (in seconds); and the reset, skip-back, play/pause, single-step and skip-forward buttons. Starting and stopping a simulation is done by clicking play/pause, and resetting it to time 0 is done by clicking reset. The single-step button advances the simulation by one time step.

On some MacOS systems, a problem that may occur when trying to run ArtiSynth models is that MacOS complains about using a nonvalidated external library. If it does, it may take the form of a console error that looks like this:

 ...
 /Users/roger/git/artisynth_core/lib/MacOSArm64/libMumpsJNI.5.9.1.dylib
 not valid for use in process using Library Validation: library load disallowed
 by system policy
 ...

and/or a popup notice like this:

The problem here is that one or more of the native libraries are not “known” to Apple and are therefore not trusted. Clicking the "?" on the popup will open a window containing more information about what to do.
The short version is to immediately open System Settings > Privacy & Security after the error occurs. Near the bottom, under Security, you should see a notification about the blocked library with a button to the right labeled Open Anyway. Clicking that button will grant the library a security exception. You will then need to exit and restart ArtiSynth.

A model can also be loaded by specifying either its defining class or a .art file containing its textual representation. For details, see the section “Loading, Simulating and Saving Models” in the ArtiSynth User Interface Guide. The model menu can also be customized, as described in “Customizing the Model Menu”. The interface guide also contains information on using the ArtiSynth GUI for model visualization, navigation, editing, and simulation control. Instructions on how to build a model using Java are given in the ArtiSynth Modeling Guide.

The image below shows ArtiSynth with the Spring Net demo loaded:

To update ArtiSynth to the latest version on GitHub, right-click on artisynth_core in the Package Explorer and choose Team > Pull. If the update requires new or different libraries, they are downloaded automatically the next time Eclipse builds the project, as during installation, and libraries that are no longer needed are removed.

The pull may be refused if it would overwrite files that you have modified locally, such as ArtiSynth.launch or .classpath. Eclipse will then report an error, and clicking Details in the error dialog lists the files concerned. Information on resolving this is given in the Section “Refused pulls” in the general Installation Guide.

As described in Section 2.1, you need a separate JDK only to compile or run ArtiSynth from a terminal window, or to use a specific version of Java (such as Java 21 for use with MATLAB). Any JDK of version 21 or later will work. Free builds of the JDK are available from several sources; we suggest Eclipse Temurin, available from

adoptium.net/temurin/releases.

JDKs are also available from Oracle at www.oracle.com/java/technologies/downloads but may be subject to certain licensing restrictions.

Select your operating system and architecture, the package type JDK, and the desired version (21, or later). For MacOS, choose the architecture aarch64 if your Mac uses Apple silicon, or x64 if it uses an Intel processor. The easiest option is then the .pkg installer.

The home directory for a JDK install is usually something like

  /Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home

for Temurin and

  /Library/Java/JavaVirtualMachines/jdk-21.jdk/Contents/Home

for Oracle.

Previous versions of these instructions asked that an Intel-based (x64) JDK be installed on Macs with Apple silicon, so that ArtiSynth would run under Rosetta. This is no longer necessary, as ArtiSynth now runs natively on Apple silicon.