diy-layout-creator/diylc/diylc-swing/deploy/mac/README.md

# Setting up macOS Build Environment for DIYLC

This document describes how to set up a macOS machine for building and signing DIYLC application bundles.

## Prerequisites

1. **macOS System**
   - macOS 11 (Big Sur) or later
   - Xcode Command Line Tools installed
   ```bash
   xcode-select --install
   ```

2. **Java Development Kit**
   - Install JDK 17 (recommended to use SDKMAN!)
   ```bash
   # Install SDKMAN!
   curl -s "https://get.sdkman.io" | bash
   source "$HOME/.sdkman/bin/sdkman-init.sh"
   
   # Install JDK 17
   sdk install java 17.0.14-tem
   ```

3. **Maven**
   - Install Maven 3.9 or later
   ```bash
   sdk install maven
   ```

## Apple Developer Account Setup

1. **Apple Developer Account**
   - Enroll in the [Apple Developer Program](https://developer.apple.com/programs/)
   - You need a paid membership ($99/year) for distribution signing

2. **Developer Certificate**
   - Open Keychain Access
   - Go to Certificate Assistant → Request a Certificate from a Certificate Authority
   - Fill in your email and name
   - Save to disk
   - Go to [Apple Developer Certificates](https://developer.apple.com/account/resources/certificates/list)
   - Create a new Developer ID Application certificate
   - Download and double-click to install in Keychain

3. **Notarization Setup**
   - Create an app-specific password:
     1. Go to [Apple ID Account](https://appleid.apple.com/)
     2. Security → App-Specific Passwords → Generate Password
     3. Save this password securely

   - Create a keychain profile for notarization:
   ```bash
   xcrun notarytool store-credentials "AC_PASSWORD" \
     --apple-id "your.email@example.com" \
     --team-id "YOUR_TEAM_ID" \
     --password "app-specific-password"
   ```

## Environment Configuration

1. **Set Developer Identity**
   - Find your Developer ID in Keychain Access
   ```bash
   security find-identity -v -p codesigning
   ```
   - Set the environment variable (add to your ~/.zshrc):
   ```bash
   export APPLE_DEVELOPER_IDENTITY="Developer ID Application: Your Name (TEAM_ID)"
   ```

2. **Verify Setup**
   ```bash
   # Verify codesign is available
   codesign --version
   
   # Verify notarytool is available
   xcrun notarytool --version
   
   # Verify your identity is set
   echo $APPLE_DEVELOPER_IDENTITY
   ```

## Building DIYLC

1. **Clone the Repository**
   ```bash
   git clone https://github.com/bancika/diy-layout-creator.git
   cd diy-layout-creator/diylc
   ```

2. **Build for Intel Macs**
   ```bash
   mvn clean package -P mac-x86
   ```

3. **Build for Apple Silicon Macs**
   ```bash
   mvn clean package -P mac-arm
   ```

4. **Build Both Architectures**
   ```bash
   mvn clean package -P mac-x86,mac-arm
   ```

## Output Files

After successful builds, you'll find these files in the `diylc-swing/target` directory:

**Signed and Notarized Builds:**
- `diylc-<version>-mac-intel.zip` - Signed and notarized Intel build
- `diylc-<version>-mac-silicon.zip` - Signed and notarized Apple Silicon (ARM) build

**Unsigned Builds:**
- `diylc-<version>-mac-intel-unsigned.zip` - Unsigned Intel build
- `diylc-<version>-mac-silicon-unsigned.zip` - Unsigned Apple Silicon (ARM) build

The unsigned builds are created before the signing and notarization process and can be useful for testing or in environments where code signing is not required.

## Troubleshooting

1. **Signing Issues**
   - Verify your certificate is valid:
   ```bash
   security find-identity -v -p codesigning
   ```
   - Check certificate expiration in Keychain Access

2. **Notarization Issues**
   - Check notarization status:
   ```bash
   xcrun notarytool log <submission-id> --keychain-profile "AC_PASSWORD"
   ```
   - Verify entitlements are correct in `deploy/mac/entitlements.plist`

3. **Build Issues**
   - Clear Maven cache:
   ```bash
   rm -rf ~/.m2/repository/org/diylc
   ```
   - Verify JDK version:
   ```bash
   java -version
   ```

## Common Issues

1. **"The specified item could not be found in the keychain"**
   - Solution: Verify your Developer ID certificate is in the keychain
   - Check the exact name matches `APPLE_DEVELOPER_IDENTITY`

2. **"No account for team found"**
   - Solution: Verify your Apple Developer membership is active
   - Check team ID in notarytool credentials

3. **"The binary is not signed"**
   - Solution: Check that the signing process isn't being skipped
   - Verify all dependencies are properly signed

## Support

For additional help:
- Check the [Apple Code Signing Documentation](https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution)
- File an issue on the DIYLC GitHub repository
- Contact the development team