troubleshooting

Troubleshooting

This section provides solutions to common problems you might encounter while using the Darwin Build Environment.

(This section would be populated with common issues and their solutions. Below are some examples based on the provided text. You should add more specific troubleshooting steps as they become known.)

1. Linker Errors: duplicate symbol _main or ld: entry point (_main) undefined

• Cause: This often occurs if you have toggled the "Remote Debug Console" feature (either via the REMOTELOG_IP variable in make.cmd or the checkbox in the Unity builder) without performing a full rebuild of your project. The feature injects or removes code related to the main function.

• Solution:

  • Perform a clean build of your project.

  • Many builders have a "Rebuild all files (once)" checkbox or a "Clean" option. Use this to ensure all source files are recompiled.

2. Code Signing Failures

• Cause:

  • Product not activated: Full code signing requires product activation.

  • Incorrect or expired certificate/private key/provisioning profile selected in Keychain Tool.

  • Passphrase for the private key is incorrect.

  • Provisioning profile does not match the App ID (Bundle Identifier) of your application.

  • Provisioning profile does not include the UDID of the test device (for Development/Ad Hoc).

  • Entitlements in your app not matching those in the provisioning profile.

• Solution:

  • Ensure the product is activated (see Section 2).

  • Open the Keychain Tool:

    • Verify the correct certificate, private key, and provisioning profile are selected.

    • Ensure the lock icon is green, indicating a match.

    • Re-enter the private key passphrase carefully.

  • In the Apple Developer Portal:

    • Check if your certificate or provisioning profile has expired.

    • Ensure your App ID (Bundle ID) in make.cmd or Unity settings exactly matches the App ID in the provisioning profile.

    • For Development/Ad Hoc builds, confirm your device's UDID is registered and included in the provisioning profile.

    • If using entitlements, make sure they are enabled for your App ID and the provisioning profile has been regenerated.

  • Re-download and re-import profiles from the Apple Developer Portal if unsure.

3. App Installs but Crashes Immediately on Launch (Non-Jailbroken Device)

• Cause: Often related to code signing or entitlement issues.

  • The provisioning profile might be invalid for the device or build type.

  • Entitlements issues: The app might be trying to use a service for which it doesn't have permission according to its embedded provisioning profile.

  • Incorrect architecture built for the device.

• Solution:

  • Double-check all code signing settings (see point 2).

  • Use the Remote Debug Console to capture system logs. These logs often provide specific reasons for launch failures (e.g., "missing entitlement," "signature validation error").

  • Ensure your make.cmd is configured to build for the correct architecture of your target device.

4. SDK Migration Issues

• Cause:

  • USB key not FAT-formatted.

  • Xcode not installed or not found correctly on the macOS side.

  • Insufficient space on the USB key or target drive.

• Solution:

  • Ensure your USB key is formatted as FAT32.

  • Verify Xcode is installed in /Applications on the Mac. If using an older Mac, try the workaround mentioned in Section 1.2.

  • Ensure sufficient free space.

  • Re-run the migration assistant steps carefully.

5. Build Fails with #include or #import Errors for SDK Libraries

• Cause: The compiler cannot find the header files for an SDK library you're trying to use (e.g., libxml2).

• Solution:

  • As described in Section 6.1, you need to add the path to the library's header files to your compiler flags using -I.

  • Example in make.cmd:

    set DBE_CPPFLAGS=-W -Wall -O2 -I"/usr/include/libxml2"

    (Adjust the path according to the SDK structure if needed).

6. Unity Project Build Issues

• Cause:

  • Incorrect Xcode project path selected in the "Project Builder for Unity".

  • Signing identity not set up or incorrect.

  • Bundle Identifier in Unity doesn't match the provisioning profile.

• Solution:

  • Ensure you're pointing the builder to the root of the Xcode project folder that Unity generated.

  • Verify your signing identity in the Keychain Tool and ensure it's correctly reflected in the Project Builder for Unity.

  • Align the Bundle Identifier in Unity > File > Build Settings > Player Settings with your App ID and provisioning profile.