Adding an ADHoc Build Configuration to a Flutter‑iOS Project

In client development, different environments often require distinct parameters and code paths, such as enabling logs in Debug mode while disabling them in Release. Xcode provides default Debug and Release build configurations, but they may not satisfy all scenarios, for example when an ADHoc configuration is needed to distribute an enterprise‑signed app for testing or UAT.

The article demonstrates how to add an ADHoc configuration to a mixed Flutter‑iOS project so that a single Xcode target can produce both an App Store version and an enterprise version, and how to automate the packaging process.

1. Create a new Build Configuration In Xcode’s project Settings → Configurations, click the “+” button, duplicate the Release configuration, and name the copies ADHoc_Release and ADHoc_Debug . This creates separate build settings for the two new configurations.

2. Modify Build Settings Adjust the following items for each configuration:

Bundle ID – set a different Product Bundle Identifier in the Target’s Build Settings.

App name – change the value of CFBundleDisplayName in Info.plist by creating a user‑defined setting BUNDLE_DISPLAY_NAME and assigning a different name per configuration.

Push SDK initialization – use different appId and appSecret values according to the configuration.

Certificates – select the appropriate signing certificate (enterprise for ADHoc, App Store for Release) in Signing & Capabilities.

3. Add User‑Defined Settings Create a new User‑Defined Setting named BUNDLE_DISPLAY_NAME and give it the desired value for each configuration. Then reference this variable in Info.plist for the bundle display name.

4. Define Macro Flags In the Target’s Build Settings → Apple Clang – Preprocessing, add ADHOC_DEBUG to the ADHoc_Debug configuration and ADHOC_RELEASE to ADHoc_Release. These macros allow conditional compilation of push‑SDK initialization code.

5. Update Code Wrap the push‑SDK initialization logic with #if ADHOC_DEBUG / #elif ADHOC_RELEASE blocks so that the correct credentials are used for each build.

6. Cocoapods Considerations After modifying the build settings, run pod install to generate the adhoc_debug.xcconfig and adhoc_release.xcconfig files that store the new configuration values.

7. Flutter‑Specific Adjustments The Flutter build script xcode_backend.sh reads the FLUTTER_BUILD_MODE macro. By setting this macro to debug , profile , or release in the corresponding Xcode configuration, Flutter automatically selects the matching SDK mode. If the macro is absent, Flutter falls back to the configuration name to decide the build mode.

8. CI Automation In the Avatar CI platform, specify the custom build configuration name in the build type field; the CI system will then package the app using the selected configuration, enabling automated builds for both enterprise and App Store variants.

By leveraging Xcode’s build configurations, developers can manage multiple environments, adjust bundle identifiers, app names, signing certificates, and code paths without maintaining separate Xcode projects, greatly reducing manual effort and the risk of configuration errors.