.xcconfig — その概要、構文、Xcodeでの変数

.xcconfigとは？

.xcconfig（Xcode設定ファイル）は、PARAMETER_NAME = value形式でBuild Settingsを含むプレーンテキストファイルです。.xcconfigファイルは、Xcodeのビルド設定を集中管理するために使用されます。Build Settings UIでの手動フィールド編集を置き換えます。各.xcconfigは、Build Configuration（Debug、Release）またはプロジェクト全体にリンクされ、SWIFT_VERSION、IPHONEOS_DEPLOYMENT_TARGET、PRODUCT_BUNDLE_IDENTIFIER、CODE_SIGN_STYLE、PROVISIONING_PROFILE_SPECIFIERなどの任意のbuild settingを上書きできます。

.xcconfigが登場する前は、ビルド設定はproject.pbxprojというバイナリ/plistファイルにのみ保存されており、diffでの読み取りが難しく、コメントを付けることが不可能でした。.xcconfigはこの問題を解決しました。開発者はパラメータにコメントを付け、意味ごとにグループ化し、異なる環境用にバージョン管理可能なファイルを作成し、ファイル間でパラメータを継承できます。これにより、.xcconfigはiOSプロジェクトにおける設定管理の事実上の標準となりました。

.xcconfigファイルはプロジェクト内、通常はConfigurations/またはBuildConfig/フォルダに配置されます。各ファイルは、Debug.xcconfig、Release.xcconfig、Staging.xcconfigという1つのBuild Configurationに対応します。さらに、共通のShared.xcconfigファイルが作成され、#includeを介してすべての設定に含まれます。これにより、共通パラメータを一度定義し、設定ファイルで特定のパラメータを上書きできます。

UI Build Settingsに対する利点

Diffの可読性：.xcconfigの変更は、Git diffで通常の行として表示されます。project.pbxprojとは異なり、フィールドの順序を変更すると、1つのパラメータ編集で50行の変更がdiffに表示されます。コメント：.xcconfigでは、各パラメータが必要な理由を説明できます。継承：共通設定を持つベース設定を作成し、DebugとReleaseに必要なパラメータのみを上書きできます。

.xcconfigの構文と構造

変数と置換

.xcconfigの構文は可能な限りシンプルです。各行はパラメータで、名前と値が等号で区切られています。=の周囲のスペースは無視されます。値には、$(VARIABLE_NAME)または${VARIABLE_NAME}形式の変数を含めることができます。コメントは//または#で始まり、行末まで有効です。行はバックスラッシュ\を使用して次の行に継続できます。空行は無視されます。

.xcconfigの変数は他の変数を参照でき、複合値を作成できます。例：PRODUCT_NAME = MyApp、PRODUCT_BUNDLE_IDENTIFIER = com.example.$(PRODUCT_NAME)。Xcodeはビルド時に値を評価し、変数の実際の値を置換します。AGPは、ビルド環境によって設定されるシステム変数（ARCHS、SDK_NAME、CONFIGURATION、PLATFORM_NAME）もサポートしています。

条件付き設定には、角括弧内のプラットフォームディレクティブが使用されます：PARAMETER[sdk=iphoneos*] = value。たとえば、SUPPORTED_PLATFORMS[sdk=iphoneos*] = iphoneosは、iOSビルドに対してのみパラメータを設定します。ワイルドカードがサポートされています：*（任意の文字）、?（1文字）。条件付きディレクティブにより、複数のプラットフォームに対して1つの.xcconfigを持ち、1つのファイルでiOSとmacOSに異なる値を設定できます。

// Shared.xcconfig — プロジェクトの共通設定
SWIFT_VERSION = 5.0
IPHONEOS_DEPLOYMENT_TARGET = 16.0
SDKROOT = iphoneos
TARGETED_DEVICE_FAMILY = 1,2

// バンドル識別子 — プレフィックスと名前から構成
BUNDLE_ID_PREFIX = com.example
PRODUCT_NAME = MyApp
PRODUCT_BUNDLE_IDENTIFIER = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME)

// macOSの条件付き設定
SUPPORTED_PLATFORMS[sdk=macosx*] = macosx
PRODUCT_BUNDLE_IDENTIFIER[sdk=macosx*] = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME).mac

// バージョン管理
MARKETING_VERSION = 2.4.1
CURRENT_PROJECT_VERSION = 37

#includeによる設定の継承

#includeは、別の.xcconfigファイルの内容を含める.xcconfigプリプロセッサディレクティブです。ディレクティブはネストできます。Shared.xcconfigは“Base.xcconfig”を#includeでき、Debug.xcconfigは“Shared.xcconfig”を#includeできます。継承チェーンにより、各レベルが前のレベルのパラメータを上書きする設定の階層を構築できます。#includeは後書き優先の原則で機能します。同じパラメータがインクルードされたファイルとメインファイルの両方で定義されている場合、メインファイルの値が優先されます。

典型的なiOSプロジェクトの正しい階層：Base.xcconfig（最も一般的なパラメータ）→ Shared.xcconfig（プロジェクト設定）→ Debug.xcconfigまたはRelease.xcconfig。Base.xcconfigは標準（SWIFT_VERSION、DEPLOYMENT_TARGET）を定義し、Shared.xcconfigはプロジェクト固有の設定（PRODUCT_NAME、PREPROCESSOR_DEFINITIONS）を定義し、Debug/Releaseは環境（DEBUG_INFORMATION_FORMAT、OPTIMIZATION_CFLAGS）を定義します。#includeは循環を許可しません。循環依存が検出されると、Xcodeはエラーを出力します。

例：Config/Base.xcconfig → Config/iOS/Shared.xcconfig → Config/iOS/Debug.xcconfig。この構造により、BaseをiOS、macOS、tvOSプロジェクトで再利用し、SharedをiOSのみで再利用できます。注意：#includeは、ルート.xcconfigの場所からのファイル名または相対パスを使用します。絶対パスは推奨されません。他のマシンやCI/CDでビルドが壊れます。

// --- Config/Base.xcconfig ---
SWIFT_VERSION = 5.0
ENABLE_MODULE_VERIFIER = YES
CLANG_ENABLE_MODULES = YES

// --- Config/iOS/Shared.xcconfig ---
#include "../Base.xcconfig"
IPHONEOS_DEPLOYMENT_TARGET = 16.0
PRODUCT_BUNDLE_IDENTIFIER = com.example.myapp

// --- Config/iOS/Debug.xcconfig ---
#include "Shared.xcconfig"
OPTIMIZATION_CFLAGS = -O0
DEBUG_INFORMATION_FORMAT = dwarf
SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG
ENABLE_TESTABILITY = YES

// --- Config/iOS/Release.xcconfig ---
#include "Shared.xcconfig"
OPTIMIZATION_CFLAGS = -Osize
DEBUG_INFORMATION_FORMAT = dwarf-with-dsym
SWIFT_COMPILATION_MODE = wholemodule

Xcodeプロジェクトでの.xcconfigの接続

プロジェクトレベルとターゲットレベルの設定

.xcconfigをプロジェクトに接続するには、Project Info → Configurationsで行います。各Build Configuration（Debug、Release、AdHoc）について、“Based on Configuration File”ドロップダウンから対応する.xcconfigを選択します。設定がファイルにリンクされていない場合、Xcodeはproject.pbxprojの値を使用します。.xcconfigを選択すると、ファイルのすべてのパラメータがその設定に対してアクティブになります。

プロジェクトレベルとターゲットレベルの設定を区別することが重要です。プロジェクトレベルの.xcconfigは、すべてのターゲットのデフォルトパラメータを設定します。ターゲットレベルの.xcconfigは、特定のターゲットに対してそれらを上書きします。パラメータがターゲットレベルの.xcconfigで設定されていない場合、プロジェクトレベルの値が使用されます。そちらでも設定されていない場合は、project.pbxprojの値が使用されます。実用的なルール：共通パラメータ（ビルド、バージョン）はプロジェクトレベルに配置し、ターゲット固有の設定（バンドル識別子、プロビジョニング）はターゲットレベルに配置します。

.xcconfigとUI Build Settingsの間で競合が発生した場合、UIの値が優先されます（.xcconfigを上書きします）。これにより混乱が生じる可能性があります。開発者は、.xcconfigが別の値を指定していることに気づかずに、UIでBuild Settingを変更します。.xcconfigに完全に移行し、UI Build Settingsに触れないことをお勧めします。どのパラメータが適用されているかを確認するには、xcrun xcodebuild -showBuildSettingsを使用します。このコマンドは、すべてのレベルを解決した後のすべてのパラメータの最終値を表示します。

例：Dev、Staging、Production環境

3レベルの設定を考えてみましょう：Dev（ローカル開発）、Staging（テストサーバー）、Production（リリース）。各環境に対して個別の.xcconfigが作成され、異なるAPI_URL、ロギング、証明書の値を定義します。Devはlocalhostを使用し、Stagingはstaging.api.example.comを使用し、Productionはapi.example.comを使用します。3つすべてが#includeを介して共通のShared.xcconfigを継承します。

環境間で異なる主要なパラメータはPRODUCT_BUNDLE_IDENTIFIERです。Dev：com.example.myapp.dev、Staging：com.example.myapp.staging、Production：com.example.myapp。異なるバンドルIDにより、3つのバージョンすべてを1つのデバイスに同時にインストールできます。CODE_SIGN_IDENTITY（DevはApple Development、ProductionはApple Distribution）とPROVISIONING_PROFILE_SPECIFIERも異なります。

コードに値を渡すには、INFOPLIST_PREFIX_HEADERまたは-Dプリプロセッサ付きのOTHER_SWIFT_FLAGSを使用します。Swiftにはプリプロセッサがないため、Active Compilation Conditionsが使用されます：SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEV。コード内：#if DEV; #elseif STAGING; #else; #endif。Objective-CにはGCC_PREPROCESSOR_DEFINITIONSが使用されます。これにより、ソースファイルを変更せずに、異なる環境用に異なるコードをコンパイルできます。

// --- Config/Dev.xcconfig ---
#include "Shared.xcconfig"

PRODUCT_BUNDLE_IDENTIFIER = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME).dev
CODE_SIGN_IDENTITY = Apple Development
PROVISIONING_PROFILE_SPECIFIER = Dev Profile

SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG DEV
OTHER_SWIFT_FLAGS = -D DEV

// Info.plistを介したAPI URL — 値が置換される
API_BASE_URL = http://localhost:3000/api

// --- Config/Staging.xcconfig ---
#include "Shared.xcconfig"

PRODUCT_BUNDLE_IDENTIFIER = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME).staging
CODE_SIGN_IDENTITY = Apple Development
PROVISIONING_PROFILE_SPECIFIER = Staging Profile

SWIFT_ACTIVE_COMPILATION_CONDITIONS = STAGING
OTHER_SWIFT_FLAGS = -D STAGING
API_BASE_URL = https://staging.api.example.com/v2

// --- Config/Production.xcconfig ---
#include "Shared.xcconfig"

PRODUCT_BUNDLE_IDENTIFIER = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME)
CODE_SIGN_IDENTITY = Apple Distribution
PROVISIONING_PROFILE_SPECIFIER = AppStore Distribution

SWIFT_ACTIVE_COMPILATION_CONDITIONS = RELEASE
API_BASE_URL = https://api.example.com/v3

.xcconfigとInfo.plist：値の受け渡し

.xcconfigの値は、変数$(PARAMETER_NAME)を介してInfo.plistに渡すことができます。.xcconfigでパラメータが定義されている場合（例：API_BASE_URL）、Info.plistで使用できます：<key>ApiBaseUrl</key><string>$(API_BASE_URL)</string>。ビルド時に、Xcodeは$(API_BASE_URL)を.xcconfigの値に置き換えます。これにより、コードを変更せずにアプリケーションを設定できます。スキームを切り替えるだけです。

Info.plistで使用される.xcconfigパラメータは公開である必要があります。これらはバイナリに含まれ、逆コンパイルされたアプリケーションで表示されます。機密値（トークン、パスワード）には.xcconfigを使用しないでください。サーバー上で実行されるFirebase Remote Configなどのサービスを使用してください。Info.plist用の.xcconfigは、サーバーURL、エンティティ名、トラッカー識別子、feature flagsに適しています。

コード内のInfo.plist値へのアクセス：Objective-C/Swiftの場合、Bundle.main.object(forInfoDictionaryKey: “ApiBaseUrl”)。値が.xcconfigを介して設定されている場合、置き換えられ、Bundle main.infoDictionaryで利用可能になります。この方法は、Info.plistが標準のiOSメカニズムであり、その値がextensions、widgets、Siri Intentsを含むすべてのシステムコンポーネントで利用できるため、BuildConfigField（Androidのように）よりも推奨されます。