Scheme: qué es, configuración y ejecución en Xcode

¿Qué es un Scheme en Xcode?

Scheme en Xcode es un archivo XML (con extensión .xcscheme) que describe una secuencia de acciones y sus parámetros para compilar y analizar una aplicación. Cada Scheme está vinculado a uno o varios targets y define con qué configuración (Debug, Release, AdHoc) ejecutar cada acción. Scheme es el equivalente del Build Variant en Android, pero con una estructura más flexible: un mismo esquema puede contener diferentes targets para diferentes acciones.

Xcode crea automáticamente un esquema para cada target la primera vez que se abre el proyecto. El nombre del esquema por defecto coincide con el nombre del target. Si el proyecto tiene un target de pruebas, Xcode lo añade automáticamente a la acción Test del esquema del target principal. Para proyectos con varios targets (aplicación principal + watchOS + extensión), Xcode crea un esquema separado para cada uno, pero también se puede crear un único esquema que compile todos los targets a la vez.

Los esquemas se almacenan en el directorio xcshareddata/xcschemes/ (para shared) o xcuserdata/<user>/xcschemes/ (para private). Los esquemas shared llegan a Git y los usa todo el equipo. Los esquemas private se guardan localmente y no se sincronizan. El archivo .xcscheme tiene formato XML con el elemento raíz <Scheme>. En su interior hay bloques para cada acción: BuildAction, TestAction, LaunchAction, ProfileAction, AnalyzeAction, ArchiveAction.

Estructura del archivo .xcscheme

.xcscheme es un archivo XML que se puede editar manualmente o a través de Xcode. Los elementos principales: <BuildAction> (lista de targets a compilar), <TestAction> (enlaces a los targets de prueba), <LaunchAction> (configuración de ejecución), <ProfileAction>, <AnalyzeAction>, <ArchiveAction>. Cada bloque contiene el atributo buildConfiguration, que determina qué configuración (Debug/Release) usar para esa acción.

Acciones del Scheme: Build, Run, Test, Profile, Analyze, Archive

Scheme consta de seis acciones, cada una de las cuales se puede configurar de forma independiente. La acción Build determina qué targets se compilan y en qué orden. La acción Run determina cómo se inicia la aplicación: con qué argumentos, variables de entorno y configuración. La acción Test determina qué pruebas se ejecutan y qué opciones de cobertura de código están activadas. La acción Profile inicia con las herramientas Instruments para el perfilado. La acción Analyze realiza el análisis estático del código con Clang Static Analyzer. La acción Archive compila para publicar en App Store o distribución AdHoc.

Para cada acción se puede definir una build configuration independiente. Normalmente se usa Debug para Run y Test, y Release para Archive. La build configuration define un conjunto de flags del compilador, optimizaciones e información de depuración. Xcode proporciona dos configuraciones estándar: Debug (sin optimizaciones, con símbolos de depuración) y Release (con optimizaciones, sin información de depuración). El desarrollador puede añadir configuraciones personalizadas mediante project.xcconfig.

La acción Archive es especialmente importante: crea un .xcarchive que luego se exporta a un .ipa para App Store o AdHoc. La acción Archive usa la configuración Release por defecto, pero se puede cambiar a AdHoc o Distribution. En la acción Archive también está disponible el flag revealArchiveInOrganizer: cuando el archivado termina, Xcode abre el Organizer para seguir trabajando con el archivo.

<!-- Ejemplo de .xcscheme para aplicación iOS -->
<Scheme
  LastUpgradeVersion = "1500"
  version = "1.7">

  <BuildAction
    parallelizeBuildables = "YES"
    buildImplicitDependencies = "YES">
    <BuildActionEntries>
      <BuildActionEntry
        buildForTesting = "YES"
        buildForRunning = "YES"
        buildForProfiling = "YES"
        buildForArchiving = "YES"
        buildForAnalyzing = "YES">
        <BuildableReference
          BuildableIdentifier = "primary"
          BlueprintIdentifier = "ABCD1234"
          BuildableName = "MyApp.app"
          BlueprintName = "MyApp"
          ReferencedContainer = "container:MyApp.xcodeproj">
        </BuildableReference>
      </BuildActionEntry>
    </BuildActionEntries>
  </BuildAction>

  <LaunchAction
    buildConfiguration = "Debug"
    selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
    enableAddressSanitizer = "YES">
  </LaunchAction>
</Scheme>

Creación y configuración del Scheme

Sanitizadores de diagnóstico

La creación de un nuevo esquema se realiza a través del menú de Xcode: Product → Scheme → New Scheme o con el botón "+" en el panel Scheme (junto al botón Run). Al crearlo se selecciona el target para el que se crea el esquema. Xcode copia automáticamente la configuración de un esquema existente si este se selecciona como "duplicate". Los nuevos esquemas se guardan como private por defecto; para compartirlos con el equipo hay que activar Shared en Manage Schemes.

La ventana Edit Scheme (Product → Scheme → Edit Scheme) contiene seis pestañas según el número de acciones. En cada pestaña se puede cambiar la build configuration, los argumentos de ejecución, las variables de entorno y los flags de diagnóstico. En la pestaña Run están las opciones: executable (qué binario ejecutar), wait for executable to be launched (para depurar procesos iniciados), debugger (LLDB o None), launch arguments, environment variables y opciones ampliadas (Address Sanitizer, Thread Sanitizer, Main Thread Checker, Memory Management).

Para el diagnóstico, Address Sanitizer (ASan) detecta accesos fuera de límites, use-after-free y otros errores de memoria en código C/C++/ObjC. Thread Sanitizer (TSan) detecta condiciones de carrera (data races) en código multihilo. Undefined Behavior Sanitizer (UBSan) detecta comportamiento indefinido, como el desbordamiento de un int con signo. Estas opciones están disponibles en Edit Scheme → Run → Diagnostics y solo funcionan en compilaciones Debug. Activar todos los sanitizadores puede ralentizar el inicio 2-3 veces, por lo que se recomienda activarlos de forma selectiva.

Clonación del esquema para distintos entornos

Una práctica habitual es crear esquemas separados para cada entorno: Dev, Staging, Production. Cada esquema usa la misma Build Configuration (Debug para Dev, Release para Production), pero argumentos de ejecución diferentes: -FIRAnalyticsDebugEnabled, -com.apple.CoreData.SQLDebug 1 para Dev y su ausencia para Production. Los argumentos de ejecución se pasan a UserDefaults (ProcessInfo.processInfo.arguments) y están disponibles para lectura al iniciar la aplicación. Esto permite cambiar la URL del servidor, el nivel de registro y las funciones sin modificar el código.

Esquemas Shared y Private: gestión mediante Git

Los esquemas shared se almacenan en <project>.xcworkspace/xcshareddata/xcschemes/ o <project>.xcodeproj/xcshareddata/xcschemes/ y llegan al repositorio de Git. Todos los desarrolladores del equipo ven estos esquemas en Xcode. Los esquemas shared son la única forma de distribuir esquemas dentro del equipo. Si un desarrollador creó un esquema importante (por ejemplo, "Staging Archive") pero no lo marcó como Shared, el resto del equipo no lo verá, lo que genera confusión: cada uno creará su propio esquema con sus propias opciones.

Los esquemas private se almacenan en xcuserdata/<user>/xcschemes/ y no llegan a Git. Son útiles para configuraciones personales: por ejemplo, un esquema con todos los sanitizadores activados para un desarrollador concreto. Los esquemas private no deben contener ajustes críticos de los que dependa la compilación del proyecto: si el desarrollador abandona el proyecto, sus esquemas private desaparecerán. Recomendación: todos los esquemas que se usen en CI/CD y que usen al menos dos desarrolladores deben ser Shared.

La gestión de esquemas se realiza mediante Manage Schemes (Product → Scheme → Manage Schemes). La ventana muestra todos los esquemas del proyecto, su estado (Shared/Private) y botones +/− para añadir/eliminar. La casilla Shared cambia la visibilidad del esquema para el equipo. En caso de conflicto de Git (cambios en .xcscheme por dos desarrolladores), hay que resolver la fusión con cuidado: los archivos XML pueden contener identificadores de target diferentes. Se recomienda añadir .xcscheme a los archivos bloqueados durante el merge (git lfs o .gitattributes).

Argumentos de ejecución y variables de entorno

Los argumentos en Scheme son cadenas que se pasan a la aplicación al iniciarse (ProcessInfo.processInfo.arguments) y variables de entorno (ProcessInfo.processInfo.environment). Los argumentos se usan para flags: -AppleLanguages (ru), -AppleLocale ru_RU para simular la configuración regional rusa, o -FIRDebugEnabled para activar la depuración de Firebase. Las variables de entorno se usan para configuración: API_BASE_URL=http://localhost:3000, LOG_LEVEL=debug.

Para gestionar funciones (feature flags) en distintos entornos se usa una combinación de Arguments + Build Configuration. En el esquema Dev se define el argumento -FeatureFlagNewOnboarding YES, y en Production — -FeatureFlagNewOnboarding NO (o el argumento no existe). En el código la comprobación es: UserDefaults.standard.bool(forKey: "FeatureFlagNewOnboarding"). Este enfoque permite activar funciones gradualmente en staging sin modificar el código y sin hacer commit de los valores de producción.

Importante: los argumentos y variables de entorno del Scheme sobrescriben los valores de Info.plist. Si en Info.plist está definido API_URL y en el Scheme — API_URL=http://localhost para la acción Run, al ejecutar desde Xcode se usará el valor del Scheme. Al ejecutar en un dispositivo (no desde Xcode) — el valor de Info.plist. Esto es cómodo para el desarrollo local, pero hay que recordar que las variables del Scheme no llegan a la compilación: solo actúan cuando se ejecuta a través de Xcode.

import Foundation

struct AppEnvironment {
    var apiBaseURL: String {
        ProcessInfo.processInfo.environment["API_BASE_URL"]
            ?? Bundle.main.object(forInfoDictionaryKey: "API_BASE_URL") as? String
            ?? "https://api.production.com"
    }

    var isDebugMode: Bool {
        ProcessInfo.processInfo.arguments.contains("-DebugModeEnabled")
    }

    var isNewOnboardingEnabled: Bool {
        UserDefaults.standard.bool(forKey: "FeatureFlagNewOnboarding")
    }
}

// Uso al iniciar
let env = AppEnvironment()
NetworkConfig.shared.configure(baseURL: env.apiBaseURL)

Scheme en CI/CD: automatización con xcodebuild

En CI/CD (GitHub Actions, Jenkins, GitLab CI), Scheme se usa como argumento principal del comando xcodebuild. Ejemplo: xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -configuration Release -sdk iphoneos archive. El flag -scheme indica qué esquema usar. xcodebuild lee toda la configuración del archivo .xcscheme, incluida la build configuration, los targets y el orden de compilación. Esto garantiza que CI/CD compile la aplicación con los mismos parámetros que la IDE local.

Para CI/CD son críticos los esquemas shared. Si el esquema no es Shared, xcodebuild no lo encontrará en el repositorio y la compilación fallará con el error "Scheme not found". Regla: antes de configurar CI/CD, asegúrate de que todos los esquemas utilizados estén marcados como Shared. Segunda regla: en CI/CD no uses el esquema por defecto (Xcode selecciona automáticamente el primer esquema) — pasa siempre el nombre del esquema explícitamente con el flag -scheme.

Para compilar varios esquemas en paralelo (por ejemplo, la aplicación y la extensión de watchOS), se puede ejecutar xcodebuild de forma secuencial o en paralelo. Los sistemas CI modernos permiten paralelizar la compilación de distintos esquemas mediante una matriz: un job compila la aplicación de iOS, el segundo la extensión de watchOS. Esto reduce el tiempo total de compilación de 15 a 8 minutos con dos agentes en paralelo. Al final los artefactos se combinan en un único .xcarchive con xcodebuild -exportArchive.

#!/bin/bash — compilación CI/CD con xcodebuild
# 1. Limpieza y compilación
xcodebuild clean archive \
  -workspace "MyApp.xcworkspace" \
  -scheme "MyApp Production" \
  -configuration Release \
  -sdk iphoneos \
  -archivePath "build/MyApp.xcarchive" \
  CODE_SIGN_STYLE="Manual" \
  PROVISIONING_PROFILE_SPECIFIER="match AppStore"

# 2. Exportación a IPA
xcodebuild -exportArchive \
  -archivePath "build/MyApp.xcarchive" \
  -exportPath "build/ipa" \
  -exportOptionsPlist "ExportOptions.plist"