Universal Binaries for macOS

Starting in September 2021, the build scripts and binary distributions of macOS-specific packages (VAppearances, Java Native Rendering, and VAqua) create and use universal binaries. Universal binaries are native libraries that contain compiled code for both Intel and Apple Silicon (x86_64 and arm64) architectures. This change does not affect application code that uses these packages, but it does change how the packages are built and may change how applications that use the packages are built (if the goal is to build a universal application).

If you are using a release of any of the above packages that predates 2024, there are additional installation steps that must be considered. These steps are described below. If you are using releases dated 2024 or later, the steps described below can be ignored.

Releases of the above packages prior to 2024 use an Apple-created framework called JavaNativeFoundation. This framework is available on macOS, but it contains code only for the Intel (x64_64) architecture. To use these releases on Apple Silicon, the packages must be linked with an unbundled open source version of JavaNativeFoundation. To accomodate this change, the binary distributions of the above packages use a relative path to access the JavaNativeFoundation framework. Using a relative path means that an application that uses these packages must specify a path to locate the framework, if required.

For a bundled macOS application, the path can be specified as an environment variable in the application Info.plist.

For example:

  <key>LSEnvironment</key>
  <dict>
    <key>DYLD_FRAMEWORK_PATH</key>
    <string>../Frameworks:/System/Library/Frameworks:/System/Library/Frameworks/JavaVM.framework/Frameworks</string>
  </dict>

This particular specification looks first in the Frameworks directory of the application before looking for a system framework (the third path is needed on older macOS releases). It means that the unbundled JavaNativeFoundation framework will be found if has been bundled with the application in the Contents/Frameworks directory.

Bundling the JavaNativeFoundation framework is not required, but linking to the framework at runtime is necessary (for releases prior to 2024) to run the native code in the libraries.

The unbundled JavaNativeFoundation framework may be available here.

Additional information on relative paths can be found by searching for rpath macos.