Escribir código portable: costuras, no condicionales dispersos

Hay dos maneras de escribir código que funcione en varias plataformas y solo una sobrevive al segundo año. La primera consiste en escribir el programa para el sistema que se tiene delante y luego ir salpicando condicionales de compilación allí donde algo falla; produce resultados rápidos, se degrada de forma silenciosa y acaba en archivos donde cada función tiene tres versiones que nadie ha vuelto a leer. La segunda consiste en decidir de antemano dónde está la frontera entre lo que es del dominio y lo que es del sistema, poner ahí una costura explícita y no permitir que lo específico la cruce hacia dentro. La diferencia entre ambas no es de estilo ni de gusto: es que en la primera el compilador solo revisa la rama que está compilando, y todo lo demás se pudre sin que nadie se entere.

La jerarquía de las directivas

Swift ofrece varias condiciones de compilación y no son intercambiables: cada una responde a una pregunta distinta y elegir la equivocada es el origen de la mayoría del código condicional que envejece mal.

#if os pregunta por la identidad del sistema. Es la más usada y la peor, porque toda condición escrita así hay que revisarla cada vez que aparece un objetivo nuevo; una comprobación de Linux escrita hace tres años simplemente no contempla Android, FreeBSD ni el entorno de WebAssembly.

#if canImport pregunta por la capacidad, y es la que conviene por defecto. Dice lo que de verdad importa —si el módulo del que dependo existe aquí— y sigue siendo cierta cuando ese módulo llega a una plataforma nueva sin que nadie toque el código.

#if arch pregunta por la arquitectura, y sirve para lo aritmético: tamaño de puntero, alineación, orden de bytes. #if compiler y #if swift preguntan por la versión del compilador y del lenguaje, y son las únicas adecuadas para dar soporte a varias versiones del toolchain a la vez.

#if canImport(Darwin)
import Darwin
#elseif canImport(Glibc)
import Glibc
#elseif canImport(Musl)
import Musl
#elseif canImport(WinSDK)
import WinSDK
#endif

Ese bloque es el idioma canónico para llegar a la biblioteca del sistema, y muestra la propiedad que buscamos: no menciona ninguna plataforma por su nombre, y sin embargo cubre todas las que existen hoy y algunas de las que existirán.

Costuras, no condicionales dispersos

El patrón que resuelve el problema es viejo y se llama de muchas formas —puertos y adaptadores, inversión de dependencias, costura— pero en Swift toma una forma muy concreta. En el núcleo portable declaras qué necesitas del mundo, sin decir cómo se consigue; cada plataforma aporta un tipo que lo cumple, en su propio archivo; y el ensamblado ocurre una sola vez, en el punto donde se construye la aplicación.

// Nucleo portable: ni una sola directiva, ni un solo import del sistema.
public protocol AlmacenDeSecretos: Sendable {
    func guardar(_ dato: Data, para clave: String) throws
    func leer(_ clave: String) throws -> Data?
}

public struct Sesion: Sendable {
    let almacen: any AlmacenDeSecretos      // la plataforma entra por aqui y solo por aqui
}

// AlmacenDarwin.swift  — un unico #if, en el nivel superior del archivo
#if canImport(Security)
import Security

public struct AlmacenLlavero: AlmacenDeSecretos { /* ... */ }
#endif

Las reglas que hacen que esto funcione son cuatro y ninguna es opcional. La directiva vive en el nivel superior del archivo, nunca dentro del cuerpo de una función, porque un condicional incrustado en una función obliga a leer tres variantes a la vez para entender una. Todas las ramas exponen exactamente la misma firma, porque en cuanto una plataforma tiene un parámetro de más el resto del programa deja de ser portable sin avisar. El número de archivos con directivas se mantiene contable con los dedos y se sabe cuáles son. Y no se anidan: si necesitas una condición dentro de otra, lo que hace falta es otro archivo.

flowchart TB
A[Nucleo de dominio sin directivas] --> B[Protocolos que declaran lo que hace falta]
B --> C[Adaptador Darwin]
B --> D[Adaptador Linux]
B --> E[Adaptador Windows]
B --> F[Adaptador WebAssembly]
C --> G[Ensamblado unico en el arranque]
D --> G
E --> G
F --> G
H[Bateria de pruebas de contrato] --> C
H --> D
H --> E
H --> F
style A fill:#a6e3a1,color:#11111b
style G fill:#89b4fa,color:#11111b
style H fill:#f9e2af,color:#11111b

El manifiesto hace la mitad del trabajo

Buena parte de lo que la gente resuelve con directivas se expresa mejor en el manifiesto del paquete, que puede condicionar dependencias, ajustes del compilador y enlazado por plataforma. La ventaja es que el criterio queda en un solo sitio, declarado, y no repartido por los archivos.

.target(
    name: "Nucleo",
    dependencies: [
        .product(name: "Crypto", package: "swift-crypto",
                 condition: .when(platforms: [.linux, .windows, .wasi])),
    ],
    swiftSettings: [
        .define("SIN_HILOS", .when(platforms: [.wasi])),
        .enableUpcomingFeature("StrictConcurrency"),
    ]
)

Conviene además desmontar un malentendido persistente: el campo platforms de la cabecera del manifiesto no declara en qué sistemas funciona el paquete. Solo fija versiones mínimas de los sistemas de Apple. Un paquete que no mencione Linux puede funcionar allí perfectamente, y uno que declare toda la familia de Apple puede no compilar. La declaración de soporte real no existe como metadato: se demuestra construyendo.

Probar en todas o no saber nada

Una arquitectura portable sin integración continua multiplataforma es una hipótesis, y las hipótesis en software se pudren rápido. La matriz mínima útil tiene tres ejecutores y un trabajo adicional.

# macos-latest    -> swift test
# ubuntu-latest   -> swift test  y  swift build --swift-sdk x86_64-swift-linux-musl
# windows-latest  -> swift test
# trabajo aparte  -> swift build --swift-sdk wasm32-unknown-wasi
swift test --enable-code-coverage -Xswiftc -warnings-as-errors

Sobre esa base hay tres refinamientos que multiplican el valor. El primero es la batería de contrato: un conjunto de pruebas escrito una sola vez contra el protocolo y ejecutado contra cada adaptador, de modo que la paridad de comportamiento se verifica en lugar de suponerse. El segundo es la prueba diferencial: alimentar la misma entrada en todas las plataformas y comparar las salidas serializadas, que es lo único que detecta las divergencias de formateo, de región y de orden. El tercero es construir también en modo de publicación, porque las optimizaciones cambian el comportamiento de las comprobaciones de desbordamiento y de las aserciones, y hay fallos que solo aparecen ahí.

Una advertencia final sobre una confusión frecuente: @available y #if os no son alternativas. El primero es una comprobación de versión del sistema en tiempo de ejecución y solo tiene sentido en las plataformas de Apple; el segundo es una decisión de compilación. Usar el primero esperando que excluya código en Linux no funciona, porque allí no hay ninguna versión que comprobar.