Scheme: o que é, configuração e execução no Xcode

O que é um Scheme no Xcode?

Scheme no Xcode é um arquivo XML (com extensão .xcscheme) que descreve uma sequência de ações e seus parâmetros para compilar e analisar um aplicativo. Cada Scheme está vinculado a um ou mais targets e define com qual configuração (Debug, Release, AdHoc) executar cada ação. Scheme é o equivalente ao Build Variant no Android, mas com uma estrutura mais flexível: um esquema pode conter targets diferentes para ações diferentes.

O Xcode cria automaticamente um esquema para cada target na primeira vez que o projeto é aberto. O nome do esquema por padrão corresponde ao nome do target. Se o projeto tiver um target de testes, o Xcode o adiciona automaticamente à ação Test do esquema do target principal. Para projetos com vários targets (aplicativo principal + watchOS + extensão), o Xcode cria um esquema separado para cada um, mas também é possível criar um único esquema que compila todos os targets de uma vez.

Os esquemas são armazenados no diretório xcshareddata/xcschemes/ (para shared) ou xcuserdata/<user>/xcschemes/ (para private). Os esquemas shared vão para o Git e são usados por toda a equipe. Os esquemas private são armazenados localmente e não são sincronizados. O arquivo .xcscheme tem formato XML com o elemento raiz <Scheme>. Dentro há blocos para cada ação: BuildAction, TestAction, LaunchAction, ProfileAction, AnalyzeAction, ArchiveAction.

Estrutura do arquivo .xcscheme

.xcscheme é um arquivo XML que pode ser editado manualmente ou pelo Xcode. Os elementos principais: <BuildAction> (lista de targets a compilar), <TestAction> (links para targets de teste), <LaunchAction> (configuração de execução), <ProfileAction>, <AnalyzeAction>, <ArchiveAction>. Cada bloco contém o atributo buildConfiguration, que determina qual configuração (Debug/Release) usar para a ação.

Ações do Scheme: Build, Run, Test, Profile, Analyze, Archive

Scheme consiste em seis ações, cada uma configurável de forma independente. A ação Build determina quais targets são compilados e em qual ordem. A ação Run determina como o aplicativo é executado: com quais argumentos, variáveis de ambiente e qual configuração. A ação Test determina quais testes são executados e quais opções de cobertura de código estão ativadas. A ação Profile executa com as ferramentas Instruments para perfilamento. A ação Analyze realiza análise estática do código com o Clang Static Analyzer. A ação Archive compila para publicação na App Store ou distribuição AdHoc.

Para cada ação é possível definir uma build configuration separada. Normalmente usa-se Debug para Run e Test e Release para Archive. A build configuration define um conjunto de flags do compilador, otimizações e informações de depuração. O Xcode oferece duas configurações padrão: Debug (sem otimizações, com símbolos de depuração) e Release (com otimizações, sem informações de depuração). O desenvolvedor pode adicionar configurações personalizadas via project.xcconfig.

A ação Archive é especialmente importante — ela cria um .xcarchive, que depois é exportado para um .ipa para a App Store ou AdHoc. A ação Archive usa a configuração Release por padrão, mas é possível alternar para AdHoc ou Distribution. Na ação Archive também está disponível o flag revealArchiveInOrganizer — após o arquivamento, o Xcode abre o Organizer para ações adicionais com o arquivo.

<!-- Exemplo de .xcscheme para aplicativo 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>

Criando e configurando um Scheme

Sanitizadores de diagnóstico

A criação de um novo esquema é feita pelo menu do Xcode: Product → Scheme → New Scheme ou pelo botão "+" no painel Scheme (ao lado do botão Run). Na criação, seleciona-se o target para o qual o esquema é criado. O Xcode copia automaticamente as configurações de um esquema existente se ele for selecionado como "duplicate". Novos esquemas são salvos como private por padrão — para publicar para a equipe, é necessário habilitar Shared em Manage Schemes.

A janela Edit Scheme (Product → Scheme → Edit Scheme) contém seis abas conforme o número de ações. Em cada aba é possível alterar a build configuration, os argumentos de execução, as variáveis de ambiente e os flags de diagnóstico. Na aba Run estão as opções: executable (qual binário executar), wait for executable to be launched (para depurar processos executados), debugger (LLDB ou None), launch arguments, environment variables e opções estendidas (Address Sanitizer, Thread Sanitizer, Main Thread Checker, Memory Management).

Para diagnóstico, Address Sanitizer (ASan) detecta acessos fora dos limites, use-after-free e outros erros de memória em código C/C++/ObjC. Thread Sanitizer (TSan) detecta condições de corrida (data races) em código multithread. Undefined Behavior Sanitizer (UBSan) detecta comportamento indefinido, como estouro de int com sinal. Essas opções estão disponíveis em Edit Scheme → Run → Diagnostics e funcionam apenas em compilações Debug. Habilitar todos os sanitizadores pode tornar a execução 2-3 vezes mais lenta, por isso recomenda-se habilitá-los seletivamente.

Clonando o esquema para diferentes ambientes

Uma prática comum é criar esquemas separados para cada ambiente: Dev, Staging, Production. Cada esquema usa a mesma Build Configuration (Debug para Dev, Release para Production), mas argumentos de execução diferentes: -FIRAnalyticsDebugEnabled, -com.apple.CoreData.SQLDebug 1 para Dev e sua ausência para Production. Os argumentos de execução são passados para o UserDefaults (ProcessInfo.processInfo.arguments) e ficam disponíveis para leitura na inicialização do aplicativo. Isso permite alternar a URL do servidor, o nível de log e recursos sem alterar o código.

Esquemas Shared e Private: gerenciamento via Git

Esquemas shared são armazenados em <project>.xcworkspace/xcshareddata/xcschemes/ ou <project>.xcodeproj/xcshareddata/xcschemes/ e vão para o repositório Git. Todos os desenvolvedores da equipe veem esses esquemas no Xcode. Esquemas shared são a única forma de distribuir esquemas dentro da equipe. Se um desenvolvedor criou um esquema importante (por exemplo, "Staging Archive") mas não o marcou como Shared, o restante da equipe não o verá, o que gera confusão: cada um criará seu próprio esquema com suas próprias configurações.

Esquemas private são armazenados em xcuserdata/<user>/xcschemes/ e não vão para o Git. São úteis para configurações pessoais: por exemplo, um esquema com todos os sanitizadores habilitados para um desenvolvedor específico. Esquemas private não devem conter configurações críticas das quais a compilação do projeto dependa — se o desenvolvedor sair do projeto, seus esquemas private desaparecerão. Recomenda-se: todos os esquemas usados em CI/CD e por pelo menos dois desenvolvedores devem ser Shared.

O gerenciamento de esquemas é feito via Manage Schemes (Product → Scheme → Manage Schemes). A janela mostra todos os esquemas do projeto, seu status (Shared/Private) e botões +/− para adicionar/remover. A caixa Shared alterna a visibilidade do esquema para a equipe. Em caso de conflito de Git (alterações no .xcscheme por dois desenvolvedores), é preciso resolver o merge com cuidado — arquivos XML podem conter identificadores de target diferentes. Recomenda-se adicionar .xcscheme aos arquivos bloqueados durante o merge (git lfs ou .gitattributes).

Argumentos de execução e variáveis de ambiente

Argumentos no Scheme são strings passadas ao aplicativo na execução (ProcessInfo.processInfo.arguments) e variáveis de ambiente (ProcessInfo.processInfo.environment). Argumentos são usados para flags: -AppleLanguages (ru), -AppleLocale ru_RU para simular o idioma russo, ou -FIRDebugEnabled para habilitar a depuração do Firebase. Variáveis de ambiente são usadas para configuração: API_BASE_URL=http://localhost:3000, LOG_LEVEL=debug.

Para gerenciar recursos (feature flags) em diferentes ambientes, usa-se uma combinação de Arguments + Build Configuration. No esquema Dev define-se o argumento -FeatureFlagNewOnboarding YES, e no Production — -FeatureFlagNewOnboarding NO (ou o argumento está ausente). No código, a verificação é: UserDefaults.standard.bool(forKey: "FeatureFlagNewOnboarding"). Essa abordagem permite habilitar recursos gradualmente no staging sem alterar o código e sem fazer commit dos valores de produção.

Importante: argumentos e variáveis de ambiente do Scheme substituem os valores do Info.plist. Se API_URL estiver definido no Info.plist e no Scheme — API_URL=http://localhost para a ação Run, ao executar pelo Xcode será usado o valor do Scheme. Ao executar em um dispositivo (não pelo Xcode) — o valor do Info.plist. Isso é conveniente para desenvolvimento local, mas é preciso lembrar que variáveis do Scheme não entram na compilação — elas atuam apenas quando executado pelo 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 na inicialização
let env = AppEnvironment()
NetworkConfig.shared.configure(baseURL: env.apiBaseURL)

Scheme em CI/CD: automação via xcodebuild

Em CI/CD (GitHub Actions, Jenkins, GitLab CI), o Scheme é usado como argumento principal do comando xcodebuild. Exemplo: xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -configuration Release -sdk iphoneos archive. O flag -scheme indica qual esquema usar. O xcodebuild lê todas as configurações do arquivo .xcscheme, incluindo build configuration, targets e ordem de compilação. Isso garante que o CI/CD compile o aplicativo com os mesmos parâmetros do IDE local.

Para CI/CD, esquemas shared são críticos. Se o esquema não for Shared, o xcodebuild não o encontrará no repositório e a compilação falhará com o erro "Scheme not found". Regra: antes de configurar o CI/CD, certifique-se de que todos os esquemas usados estão marcados como Shared. Segunda regra: em CI/CD, não use o esquema padrão (o Xcode seleciona automaticamente o primeiro esquema) — sempre passe o nome do esquema explicitamente via flag -scheme.

Para compilar vários esquemas em paralelo (por exemplo, o aplicativo e a extensão watchOS), pode-se executar o xcodebuild sequencialmente ou em paralelo. Sistemas CI modernos permitem paralelizar a compilação de diferentes esquemas via matriz: um job compila o aplicativo iOS, o segundo a extensão watchOS. Isso reduz o tempo total de compilação de 15 para 8 minutos com dois agentes em paralelo. No final, os artefatos são combinados em um único .xcarchive com xcodebuild -exportArchive.

#!/bin/bash — compilação CI/CD com xcodebuild
# 1. Limpeza e compilação
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. Exportação para IPA
xcodebuild -exportArchive \
  -archivePath "build/MyApp.xcarchive" \
  -exportPath "build/ipa" \
  -exportOptionsPlist "ExportOptions.plist"