The Definitive Guide to Building and Deploying Avalonia Applications for macOS

As an Avalonia developer, you've harnessed the power of cross-platform development to create stunning, efficient applications. However, when it comes to deploying your creation on macOS, you're faced with a unique set of challenges and requirements. This comprehensive guide will walk you through the intricate process of building, packaging, signing, and notarizing your Avalonia application for macOS. We'll delve deep into the technical aspects, ensuring you not only understand how to perform each step but also why each step is necessary.

Understanding the macOS Ecosystem and Architecture

Before we dive into the build process, it's crucial to understand the current state of the macOS ecosystem and its architectural landscape.

The Apple Silicon Transition

In 2020, Apple announced a significant shift in its hardware strategy: transitioning Macs from Intel processors to their own Apple Silicon chips. This move marked a change from the x86-64 (x64) architecture to ARM-based designs, specifically the arm64 architecture.

Key points about this transition:

• Intel Macs use the Complex Instruction Set Computing (CISC) architecture.
• Apple Silicon Macs use the Reduced Instruction Set Computing (RISC) architecture.
• Apple Silicon offers better performance per watt, integrated GPU and Neural Engine, and a unified memory architecture.
• The transition created a split Mac ecosystem with both Intel and Apple Silicon Macs in active use.

Implications for Avalonia Developers

This architectural diversity presents both challenges and opportunities:

• Dual Compilation Requirement: Your application needs to run natively on both x64 and arm64 architectures.

• Performance Considerations: Native arm64 code can run significantly faster on Apple Silicon Macs.

• Binary Size and Distribution: Compiling for both architectures increases your total binary size.

• Dependency Management: All native libraries and dependencies must support both architectures.

Understanding these implications is crucial as we move forward in the build and deployment process.

Preparing Your Avalonia Project for macOS Deployment

Before we start building, we need to optimize our project settings for deployment.

Configuring the Project File

Add the following to your .csproj file:

<PropertyGroup>
  <PublishSingleFile>true</PublishSingleFile>
  <SelfContained>true</SelfContained>
  <PublishTrimmed>true</PublishTrimmed>
  <PublishReadyToRun>true</PublishReadyToRun>
</PropertyGroup>

Let's break down these settings:

• PublishSingleFile: Combines your application and its dependencies into a single executable file. This simplifies distribution but can impact startup time for larger applications.
• SelfContained: Includes the .NET runtime with your application. This increases the application size but ensures compatibility and eliminates runtime dependencies.
• PublishTrimmed: Removes unused code from your application and its dependencies. While this can significantly reduce size, it may inadvertently remove dynamically invoked code. Extensive testing is crucial when using this option.
• PublishReadyToRun: Pre-compiles your application's assemblies to native code at build time. This increases the application size but can significantly reduce startup times, especially beneficial for larger applications.

Building for Multiple Architectures

Now that our project is configured, let's dive into the build process for both x64 and arm64 architectures.

Building for x64 (Intel)

To build for x64 architecture, use the following command:

dotnet publish -r osx-x64 -c Release

This command targets the x64 runtime identifier (RID) and creates a release build optimized for Intel Macs.

Building for arm64 (Apple Silicon)

For arm64 architecture, use:

dotnet publish -r osx-arm64 -c Release

This command creates a build specifically for Apple Silicon Macs.

Creating a Universal Binary

While you can distribute separate builds for each architecture, creating a universal binary simplifies distribution and improves user experience.

Understanding Universal Binaries

A universal binary is a single executable file that contains code for multiple architectures. On macOS, this allows one application to run natively on both Intel and Apple Silicon Macs.

Using LIPO to Create Universal Binaries

The lipo tool, part of Apple's development toolkit, is used to create and manipulate universal binaries. Here's a script to automate the process:

#!/bin/bash

PROJECT_NAME="$1"
OUTPUT_DIR="./bin/Release/net8.0"
FINAL_OUTPUT_DIR="./bin/Release/Universal"

# Function to build for a specific architecture
build_for_arch() {
    local arch=$1
    echo "Building for $arch..."
    dotnet publish -r osx-$arch -c Release
}

# Build for both architectures
build_for_arch "x64"
build_for_arch "arm64"

# Create the final output directory
mkdir -p "$FINAL_OUTPUT_DIR"

# Create universal binary
echo "Creating universal binary..."
lipo -create \
    "$OUTPUT_DIR/osx-x64/publish/$PROJECT_NAME" \
    "$OUTPUT_DIR/osx-arm64/publish/$PROJECT_NAME" \
    -output "$FINAL_OUTPUT_DIR/$PROJECT_NAME"

echo "Universal binary created successfully"

This script builds your project for both architectures and then uses lipo to combine them into a universal binary.

Handling Dependencies

When creating a universal binary, you must ensure all dependencies are also universal or have versions for both architectures. Some Avalonia-specific libraries (like libAvaloniaNative.dylib) may already be universal binaries.

Packaging Your Application

Once you have your universal binary, the next step is to package it into a .app bundle, the standard format for macOS applications.

.app Bundle Structure

A typical .app bundle has the following structure:

MyApp.app/
  Contents/
    Info.plist
    MacOS/
      MyApp (executable)
    Resources/
      Assets.car
      MyApp.icns

Creating the .app Bundle

1. Create the directory structure:

mkdir -p MyApp.app/Contents/MacOS MyApp.app/Contents/Resources

2. Move your universal binary into the MacOS directory:

mv ./bin/Release/Universal/MyApp MyApp.app/Contents/MacOS/

3. Create an Info.plist file in the Contents directory. This file describes your application to macOS. Here's a basic template:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleName</key>
    <string>MyApp</string>
    <key>CFBundleIdentifier</key>
    <string>com.mycompany.myapp</string>
    <key>CFBundleVersion</key>
    <string>1.0</string>
    <key>CFBundlePackageType</key>
    <string>APPL</string>
    <key>CFBundleSignature</key>
    <string>????</string>
    <key>CFBundleExecutable</key>
    <string>MyApp</string>
    <key>CFBundleIconFile</key>
    <string>MyApp.icns</string>
</dict>
</plist>

4. Add your application icon (in .icns format) to the Resources directory.

Code Signing

Code signing is a crucial security feature in macOS that verifies the integrity and origin of your application.

Obtaining a Developer ID Certificate

To distribute your application outside the Mac App Store, you need a Developer ID Certificate from Apple. Obtain this through your Apple Developer account.

Signing the Application

Use the codesign tool to sign your application:

codesign --force --options runtime --sign "Developer ID Application: Your Name (XXXXXXXXXX)" MyApp.app

This command signs your entire .app bundle, including all contained resources and binaries.

Verifying the Signature

After signing, verify the signature:

codesign --verify --deep --strict MyApp.app

Notarization

Notarization is Apple's process of verifying that your application is free from known malware and hasn't been tampered with.

Preparing for Notarization

• Create an app-specific password for your Apple ID.
• Archive your .app bundle:

ditto -c -k --keepParent MyApp.app MyApp.zip

Submitting for Notarization

Use the notarytool command to submit your app for notarization:

xcrun notarytool submit MyApp.zip --wait --keychain-profile "AC_PASSWORD"

This command submits your app and waits for the notarization result.

Stapling the Notarization Ticket

Once notarized, staple the notarization ticket to your app:

xcrun stapler staple MyApp.app

This allows your app to be validated offline.

Conclusion

Building and deploying an Avalonia application for macOS involves multiple complex steps, each crucial for ensuring your application's compatibility, security, and performance across the diverse Mac ecosystem. By understanding the architectural landscape, optimizing your build process, creating universal binaries, properly packaging your application, and completing the necessary security procedures, you're setting your Avalonia application up for success on macOS.

Remember, this process requires attention to detail and thorough testing at each stage. As the macOS ecosystem continues to evolve, staying informed about the latest requirements and best practices will be key to maintaining a successful Avalonia application on this platform.