Mac Compilation Guide

Additional considerations when compiling Friday Night Funkin’ for macOS

When compiling Friday Night Funkin’ for macOS, there are several extra considerations for creating production-ready builds.

Before following this guide, make sure you’ve completed the basic compilation setup.

Mac-Specific Considerations

When creating a wider release for macOS, the Funkin’ Crew handles several additional steps:

• Creating Universal Binaries (ARM64 + x86_64)
• Code-signing the application
• Notarizing with Apple

Creating a Universal Binary

A Universal Binary allows your game to run natively on both Intel (x86_64) and Apple Silicon (ARM64) Macs.

Using the Build Script

The easiest way to create a Universal Binary is to use the included build script:

./art/macos-universal.sh

This script automatically:

1. Compiles a release build for ARM64
2. Compiles a release build for x86_64
3. Combines both into a Universal Binary

Manual Universal Binary Creation

If you want to understand the process or customize it, here’s what the script does:

1. Build for ARM64

   Compile the game for Apple Silicon:

   lime build mac -release -arm64
   
2. Build for x86_64

   Compile the game for Intel Macs:

   lime build mac -release -64
   
3. Combine the binaries

   Use the lipo command to merge both architectures:

   lipo -create \
     export/release/mac/bin/Funkin-arm64 \
     export/release/mac/bin/Funkin-x86_64 \
     -output export/release/mac/bin/Funkin
   
4. Verify the Universal Binary

   Check that both architectures are present:

   lipo -info export/release/mac/bin/Funkin
   

   Expected output:

   Architectures in the fat file: Funkin are: x86_64 arm64
   

Code Signing

Code signing requires an Apple Developer account ($99/year).

To distribute your Mac build outside the Mac App Store, you need to sign it with your Apple Developer certificate:

codesign --force --deep --sign "Developer ID Application: Your Name (TEAM_ID)" \
  export/release/mac/bin/Funkin.app

Verify Code Signing

Check that your app is properly signed:

codesign --verify --verbose export/release/mac/bin/Funkin.app

Notarization

Notarization is Apple’s process of scanning your app for malicious software. Users will see warnings if your app isn’t notarized.

1. Create an app-specific password

   Generate an app-specific password in your Apple ID account.

2. Create a ZIP of your app

   ditto -c -k --keepParent export/release/mac/bin/Funkin.app Funkin.zip
   
3. Submit for notarization

   xcrun notarytool submit Funkin.zip \
     --apple-id "[e-mail]" \
     --team-id "TEAM_ID" \
     --password "app-specific-password" \
     --wait
   
4. Staple the notarization ticket

   Once notarization succeeds, attach the ticket to your app:

   xcrun stapler staple export/release/mac/bin/Funkin.app
   

Build Script Reference

The art/macos-universal.sh script contains the complete build process used by the Funkin’ Crew. You can examine it to understand the full production build pipeline:

# View the build script
cat art/macos-universal.sh

Platform Setup

For initial Mac platform setup, refer to Lime’s official documentation:

Lime macOS Setup

Official guide for setting up Lime on macOS

Common Mac Build Issues

Architecture Mismatch Errors

If you see errors about architecture mismatches, ensure you’re building with the correct architecture flag:

• Apple Silicon: Use -arm64 or -DHXCPP_ARM64
• Intel: Use -64 or -DHXCPP_M64

Xcode Command Line Tools Missing

Install Xcode Command Line Tools:

xcode-select --install

Code Signing Issues

Verify your certificates are installed:

security find-identity -v -p codesigning

You should see your “Developer ID Application” certificate listed.

Next Steps

General Compilation

Return to the main compilation guide

Troubleshooting

Fix common compilation issues

Contributing

Learn how to contribute code

Style Guide

Follow code conventions