Importar C: cuando una cabecera se vuelve un módulo

La interoperabilidad con C no es una biblioteca ni un puente en tiempo de ejecución: es una parte del compilador. Swift incorpora Clang entero, y cuando escribes import CJson lo que ocurre es que Clang analiza las cabeceras de esa librería, construye su árbol de declaraciones y un componente llamado importador traduce cada declaración a una declaración Swift equivalente, en memoria, sin generar una sola línea de código intermedio. No hay envoltorio, no hay marshalling, no hay coste en ejecución: una función C importada se llama con exactamente la misma instrucción de máquina que emitiría un compilador de C. Lo que sí hay es una traducción de reglas, y esas reglas —qué tipo Swift corresponde a cada tipo C, qué se vuelve opcional, qué se vuelve tupla, qué desaparece— son el objeto de esta lección.

El importador de Clang

El importador no ve archivos, ve módulos. Un módulo Clang es un conjunto de cabeceras declarado en un archivo module.modulemap, y esa unidad es lo que Swift sabe importar. Cuando una librería no trae mapa de módulo —el caso habitual en C clásico— eres tú quien debe escribirlo. Dentro de un proyecto de Xcode con Objective-C el papel lo cumple el bridging header, que veremos en la tercera lección; en SwiftPM el mecanismo canónico es el mapa.

La traducción es puramente sintáctica y sucede una vez por compilación. Toma esta cabecera:

// incluye/geo.h
typedef struct { double x, y; } Punto;
typedef struct Region Region;              // tipo opaco: definicion oculta

Region *region_crear(const char *nombre);
void    region_liberar(Region *r);
double  region_area(const Region *r, const Punto *vertices, size_t n);

El importador produce, sin que nadie escriba nada, una API Swift razonable: Punto se convierte en un struct Swift con inicializador por miembros y con inicializador de ceros, Region en un OpaquePointer porque su definición no es visible, y las tres funciones en funciones libres de nivel de módulo. La conversión conserva los nombres tal cual: C no tiene espacios de nombres, así que el módulo importado es un saco plano de símbolos.

El mapa de correspondencias

La tabla siguiente cubre casi todo lo que encontrarás. La columna de la derecha es lo que verás en la ayuda rápida de Xcode al inspeccionar el símbolo importado.

Dos entradas merecen comentario. La primera son los opcionales: todo puntero llega opcional porque en C cualquier puntero puede ser nulo y el importador no tiene forma de saberlo. Las macros de anotación de nulabilidad, _Nonnull y _Nullable, existen justamente para corregirlo; una cabecera bien anotada produce una API Swift mucho más limpia, y por eso conviene envolver las declaraciones entre NS_ASSUME_NONNULL_BEGIN y su cierre cuando la librería es tuya.

La segunda son los arrays de tamaño fijo, que se convierten en tuplas. Un campo declarado como sesenta y cuatro caracteres llega a Swift como una tupla de sesenta y cuatro elementos, imposible de indexar con un entero. La salida idiomática es tomar el puntero al campo y reinterpretarlo:

var cfg = Config()                       // inicializador de ceros sintetizado
let nombre = withUnsafeBytes(of: &cfg.nombre) { crudo in
    String(cString: crudo.bindMemory(to: CChar.self).baseAddress!)
}

Las enumeraciones tienen dos destinos según cómo se declaren. Una enumeración marcada con NS_ENUM o con __attribute__((enum_extensibility(closed))) llega como un enum Swift auténtico, con exhaustividad en el switch. Una enumeración C corriente llega como un struct que conforma a RawRepresentable con constantes estáticas, porque el importador no puede prometer que el conjunto de casos esté cerrado: en C nada impide almacenar un valor fuera de rango en una variable del tipo enumerado, y construir un enum Swift sobre esa premisa sería un comportamiento indefinido esperando su turno.

Memoria prestada

El punto donde más gente tropieza no es el mapeo de tipos, sino la vida de los punteros. Swift ofrece conversiones implícitas muy cómodas al llamar a una función importada: un Array se pasa donde se espera un puntero a su elemento, un String se pasa donde se espera un puntero a CChar, y una variable pasada con & se convierte en puntero a sí misma. La comodidad esconde una regla dura: esos punteros solo son válidos durante la llamada.

let puntos = [Punto(x: 0, y: 0), Punto(x: 1, y: 0), Punto(x: 0, y: 1)]
let area = region_area(r, puntos, puntos.count)   // valido: dura la llamada

let colgante = puntos.withUnsafeBufferPointer { $0.baseAddress }
// colgante ya no apunta a nada garantizado: el prestamo termino

La segunda línea compila sin una queja y es memoria corrompida en potencia. La razón es que Swift no promete dónde vive el almacenamiento de un array ni durante cuánto tiempo; solo promete que, mientras dura la llamada donde se hizo la conversión, hay un buffer contiguo y estable en esa dirección. Si la librería en C guarda el puntero para usarlo más tarde, la conversión implícita es la herramienta equivocada y necesitas memoria que tú controles con UnsafeMutablePointer.allocate y su deallocate correspondiente.

Declarar una librería del sistema

Para consumir una librería instalada en el sistema desde SwiftPM necesitas dos piezas. La primera es el mapa de módulo, que le dice a Clang qué cabecera constituye el módulo y con qué librería enlazar:

module CZstd [system] {
    header "shim.h"
    link "zstd"
    export *
}

El atributo [system] es más importante de lo que parece: silencia los avisos de esas cabeceras, que de otro modo inundarían tu compilación con advertencias de código que no controlas. La cabecera shim.h suele ser un archivo de una línea que incluye la cabecera real; ese rodeo permite fijar la ruta sin depender de dónde la haya instalado cada máquina. La segunda pieza es el objetivo en el manifiesto:

.systemLibrary(
    name: "CZstd",
    path: "Fuentes/CZstd",
    pkgConfig: "libzstd",
    providers: [.brew(["zstd"]), .apt(["libzstd-dev"])]
)

El campo pkgConfig es el que hace el trabajo real: SwiftPM consulta pkg-config para obtener las rutas de inclusión y las banderas de enlace de la máquina donde se compila. Los providers no instalan nada, solo mejoran el mensaje de error cuando la librería falta.

flowchart TB
H[Cabeceras en C] --> MM[module.modulemap]
MM --> CL[Clang construye el modulo]
CL --> IMP[Importador de Swift]
IMP --> API[Declaraciones Swift en memoria]
API --> SC[Tu codigo llama sin envoltorio]
SC --> OBJ[Mismo codigo maquina que en C]
style MM fill:#f9e2af,color:#11111b
style IMP fill:#cba6f7,color:#11111b
style OBJ fill:#a6e3a1,color:#11111b