Notes for Mac Users

The following notes were compiled for macOS Catalina 10.15.7

Installing the prerequisite software

Commentary that deviates for building and running on macOS Big Sur (macOS 11), including on M1 machines, is provided in italics.

You will need several pieces of software that don't come preinstalled on a Mac. A very popular method for installing the software you need is through Homebrew. To install Homebrew run the following in the terminal:

On Apple Silicon machines (M1 chip), until Homebrew is available for native Apple Silicon you can run it in x86 emulator mode aka Rosetta 2. Set Terminal to Rosetta emulation like so:

close all open Terminal windows
quit Terminal in the Dock
from Finder, open Applications, then open Utilities within Applications
right-click on Terminal and pick Get Info
on the Terminal Info sheet, find the Open using Rosetta checkbox below the Copyright notice
check the Open using Rosetta checkbox
close the Terminal Info sheet
launch Terminal - now it is running in x86 emulation mode and you can run the usual Homebrew.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

Doing this will also download and install the Xcode command line tools. (This can take some time to complete.) Once Homebrew has been installed use it as follows to install the necessary software.

brew install git make cdrtools openjdk gnu-sed wget cmake maven

To make that software available, your PATH needs to be amended in your bashrc / zshrc file:

Big Sur uses zsh by default, so at the end of the next command, substitute .zshrc for .bashrc

echo PATH="/usr/local/opt/openjdk/bin:/usr/local/opt/make/libexec/gnubin:/usr/local/opt/gnu-sed/libexec/gnubin:$PATH" >> .bashrc

Update your environment with:

On Big Sur, type source .zshrc instead of source .bashrc

source .bashrc

To test that the above was done correctly, run:

which sed git make mkisofs java wget cmake mvn

and you should get back:

/usr/local/opt/gnu-sed/libexec/gnubin/sed
/usr/local/bin/git
/usr/local/opt/make/libexec/gnubin/make
/usr/local/bin/mkisofs
/usr/local/opt/openjdk/bin/java
/usr/local/bin/wget
/usr/local/bin/cmake
/usr/local/bin/mvn

Downloading the VASSAL source code

The source code is available on GitHub.

Commentary in italics is for deviations when building on macOS Big Sur (macOS 11), including M1 machines.

git clone https://github.com/vassalengine/vassal

Now that we have the source code we need to run the configuration script to properly configure your build environment.

cd vassal
./bootstrap.sh

Now you need to make some modifications to the default Makefile, that is written for a Linux environment. Grab the patch with:

wget https://raw.githubusercontent.com/tinjaw/mac-vassal/main/macos.patch

Then apply the patch with:

As of build 3.5.0 6f89f3be0, and possibly earlier, the macos.patch has no effect and as we see later it is no longer needed. That is, git apply macos.patch comes back with an error from Makefile.

git apply macos.patch

Now build.

The Makefile was updated for macOS 11. On Big Sur, you can type make release-macos instead of make-release macosx

make release-macosx

If the VASSAL.app that comes out of make does not actually launch on Big Sur, it may be due to linking failing because of no Java runtime engine. If that is the case, try the following. If that is not the case, then there is a way to launch VASSAL from the Terminal window, as explained further down.

On M1 machines at this time (December 8, 2020), the Java runtime engine (JRE) does not land in /Library/Java/JavaVirtualMachines/, despite notices to the contrary. You should manually install a JRE to get VASSAL.app to finish linking during the make process. Here is one example of doing so:

visit adoptopenjdk.net in Safari browser
select OpenJDK 15 (Latest) in the Choose a Version column
select macOS in the Operating System drop-down
select x64 in the Architecture drop-down
click on JRE - 43 MB .pkg - the package should download
click on the package in the Dock, and follow the install instructions
Quit Terminal, start a new Terminal, and try the make release-macos command again
in the Terminal, review the app resources like so:

ls "$(find . -name VASSAL.app)"/Contents/Resources

If you see Java, VASSAL.icns, and doc in the response, that's great! If you don't see those, the linker is still not linking, so you could try the Launch VASSAL from the Terminal procedure, below
in the Terminal, determine if the JRE is in the app like so:

ls "$(find . -name VASSAL.app)"/Contents/MacOS

if you see VASSAL.sh and jre in the response, that's great! If you don't see those, the linker is still not linking, so you could try the Launch VASSAL from the Terminal procedure, below
copy the VASSAL app to your Applications so you can start it from Launchpad, like so:

cp -R "$(find . -name VASSAL.app)" /Applications/

Now you should be able to launch VASSAL from Launchpad, in the Dock

Launch VASSAL from the Terminal

In case you cannot get VASSAL.app to launch, here is a short way to create a launch file that will start VASSAL from the Terminal. After you're done using VASSAL, the Terminal window will linger. You can just close it with the red X button in the top left corner of the window.

Use your favorite code editor to paste the following statements into a shell file in the directory immediately above the directory where you cloned VASSAL to. The statements assume that the directory you cloned VASSAL to is called vassal.

cd vassal exec dist/jdks/mac_x64/Contents/Home/bin/java -classpath release-prepare/target/lib/Vengine.jar -Dapple.awt.graphcis.UseQuartz=false -Xdock:name=VASSAL -Xdock:icon=dist/macos/VASSAL.icns VASSAL.launch.ModuleManager

After you save the file, you need to make it executable, like this:

chmod +x launch.sh

Now you can start VASSAL from this location next time you are in the Terminal window, like so:

./launch.sh