Compilar para un sistema operativo o una arquitectura distinta a la que estás usando actualmente es una de las capacidades más potentes del compilador de Go. A diferencia de C o C++, donde necesitas instalar un “cross-compiler” específico para cada combinación de destino (un proceso tedioso y propenso a errores), en Go esto es una operación nativa mediante el uso de las variables de entorno GOOS (sistema operativo de destino) y GOARCH (arquitectura del procesador de destino).
Esto es posible porque el diseño del compilador de Go es altamente modular: la mayor parte de la biblioteca estándar está escrita en Go puro, y el compilador simplemente selecciona los archivos de implementación de bajo nivel (ensamblador y runtime) que corresponden a la combinación de GOOS y GOARCH que hayas definido. Por ejemplo, puedes estar en una MacBook con procesador Apple Silicon (darwin/arm64) y generar un binario para un servidor Linux Intel (linux/amd64) con un solo comando.
Debes recurrir a esta técnica siempre que tu flujo de trabajo de desarrollo difiera de tu entorno de producción. Es el estándar para generar binarios de contenedores (Linux) desde macOS, crear ejecutables para Windows desde Linux, o compilar para arquitecturas ARM (como Raspberry Pi o instancias Graviton en AWS) desde tu workstation.
Sin embargo, esta “magia” tiene un límite crítico: cgo. Si tu código o alguna de tus dependencias utiliza cgo para llamar a bibliotecas de C, el compilador necesitará un toolchain de C para el sistema de destino. Si intentas compilar para Linux desde macOS con cgo habilitado, la compilación fallará porque el compilador de C de tu máquina no sabe cómo generar código para Linux.
Para consultar todas las combinaciones de sistemas y arquitecturas soportadas por tu versión de Go, puedes ejecutar go tool dist list.
package main
import (
"fmt"
"runtime"
)
func main() {
// Los valores de runtime.GOOS y runtime.GOARCH no se detectan
// en el momento de la ejecución basándose en la máquina actual,
// sino que se "inyectan" en el binario durante la fase de compilación
// según las variables de entorno GOOS y GOARCH.
targetOS := runtime.GOOS
targetArch := runtime.GOARCH
fmt.Printf("--- Información de ejecución ---\n")
fmt.Printf("Sistema Operativo: %s\n", targetOS)
fmt.Printf("Arquitectura: %s\n", targetArch)
fmt.Printf("-------------------------------\n")
// Esta función simula una verificación de entorno de despliegue.
verificarEntorno(targetOS, targetArch)
}
func verificarEntorno(os, arch string) {
// Es una buena práctica incluir lógica de validación si tu binario
// tiene dependencias específicas de una plataforma.
switch os {
case "linux":
if arch == "amd64" {
fmt.Println("🚀 Target: Linux/amd64 (Standard Cloud/Docker)")
} else if arch == "arm64" {
fmt.Println("🚀 Target: Linux/arm64 (ARM64/Graviton)")
} else {
fmt.Printf("⚠️ Target: Linux/%s (Arquitectura poco común)\n", arch)
}
case "darwin":
fmt.Printf("🍎 Target: macOS/%s\n", arch)
case "windows":
fmt.Printf("🪟 Target: Windows/%s\n", arch)
default:
fmt.Printf("❓ Target desconocido: %s/%s\n", os, arch)
}
}
Desglose del funcionamiento
Cuando ejecutas el programa anterior, los valores de runtime.GOOS y runtime.GOARCH dependen estrictamente de cómo hayas invocado al comando go build.
Si en tu terminal ejecutas GOOS=linux GOARCH=amd64 go build -o mi-app-linux, el compilador de Go ignorará tu sistema operativo actual (por ejemplo, macOS) y escribirá en el binario la constante interna para linux y amd64. Por eso, la función verificarEntorno puede determinar con exactitud en qué plataforma se está ejecutando el código, permitiéndote validar si el binario es compatible con el entorno de destino (por ejemplo, un contenedor Docker).
Si necesitas garantizar que el binario sea totalmente estático y no dependa de ninguna biblioteca de C del sistema (lo cual es ideal para imágenes de Docker scratch o entornos mínimos), debes ser explícito con la variable CGO_ENABLED=0. Esto desactiva completamente cgo, forzando a Go a usar sus propias implementaciones puras en Go para paquetes como net o os/user, lo cual asegura que la compilación cruzada sea fluida y sin errores de linker.
El error frecuente
El problema más común ocurre cuando intentas compilar para otro sistema operativo pero tu código depende de una librería de C (como una librería de drivers de base de datos o procesamiento de imágenes).
Si tienes un archivo con import "C" y ejecutas:
GOOS=linux GOARCH=amd64 go build main.go
El compilador fallará con un error indicando que no puede encontrar los headers de C para el target de Linux, o bien, si tienes un compilador de C instalado, podría terminar creando un binario que funciona en tu máquina (porque usó el linker local) pero que falla en Linux debido a la incompatibilidad de la versión de libc.
Para solucionar esto de forma segura en procesos de CI/CD, la regla de oro es: si no necesitas cgo, usa siempre CGO_ENABLED=0. Si necesitas cgo, deberás configurar un cross-compiler de C específico para el target y definir la variable CC para que apunte a él, lo cual complica significativamente el pipeline de construcción.
N° 182