Guía completa para compilar lua-zlib en Windows para OpenResty

Al utilizar OpenResty en entornos Windows, a menudo surge la necesidad de la extensión lua-zlib. Dado que los distribuidores suelen proporcionar únicamente el código fuente, la compilación manual se vuelve un paso esencial. Este artículo lo guiará desde cero, completando todo el proceso que va desde la configuración del entorno Lua hasta la compilación de la DLL.

Requisitos del Entorno

• Sistema Operativo: Windows 10/11 x64
• OpenResty: v1.25.3.1 (con entorno compatible Lua 5.1)
• Compilador: Visual Studio 2022 (con componentes de desarrrollo de escritorio C++)
• Gestor de Paquetes: vcpkg (para obtener la dependencia zlib)
• Herramientas Auxiliares: Dependencies (para diagnosticar problemas de dependencias DLL)

Verfiicación del Entorno

1. Confirmar el Entorno de Compilación de VS

¡No abra directamente el cmd o PowerShell del sistema! Busque e ingrese desde el menú Inicio:

Correcto: Símbolo del sistema para herramientas nativas x64 para VS 2022

Incorrecto: Símbolo del sistema para herramientas nativas x86… o el símbolo del sistema común

Consejo: En la línea de comandos, ingrese cl. Si la primera línea de salida termina con for x64, el entorno es correcto.

2. Confirmar la Plataforma Objetivo de vcpkg

Al instalar zlib, asegúrese de que el sufijo coincida exactamente:

64 bits: vcpkg install zlib:x64-windows

32 bits: vcpkg install zlib:x86-windows

Preparación de las Bibliotecas Dependientes

1. Instalar zlib con vcpkg

Necesitamos los archivos de encabezado y biblioteca de zlib. Se recomienda vcpkg por su simplicidad y estandarización.

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat

# Instalar versión de 64 bits (debe coincidir con la arquitectura de OpenResty)
.\vcpkg install zlib:x64-windows

Punto de Verificación: Confirme que los siguientes archivos se han generado:

• C:\vcpkg\installed\x64-windows\bin\zlib1.dll (dependencia en tiempo de ejecución)
• C:\vcpkg\installed\x64-windows\include\zlib.h (archivo de encabezado de compilación)
• C:\vcpkg\installed\x64-windows\lib\zlib.lib (biblioteca de enlace)

2. Obtener el Entorno de Desarrollo Lua 5.1

Dado que lua-zlib necesita enlazar con símbolos Lua, tiene dos opciones:

Opción A: Generar .lib desde lua51.dll de OpenResty (Recomendado)

Esto garantizará que la extensión compilada sea 100% compatible con el entorno de ejecución de OpenResty.

1. Abra Símbolo del sistema para herramientas nativas x64 para VS 2022.
2. Navegue al directorio raíz de OpenResty (donde se encuentra lua51.dll):

cd D:\servidor\openresty-1.25.3.1

:: Extraer automáticamente las funciones exportadas y crear archivo .def
echo LIBRARY lua51 > lua51.def
echo EXPORTS >> lua51.def
for /f "skip=19 tokens=4" %i in ('dumpbin /exports lua51.dll') do echo %i >> lua51.def

:: Generar biblioteca exportada
lib /def:lua51.def /out:lua51.lib /machine:x64

Opción B: Compilar el Código Fuente Lua 5.1 Independientemente

Si necesita un entorno Lua independiente para pruebas, puede crear build.bat en lua-5.1.5/src:

Descargar código fuente 5.1 desde https://www.lua.org/versions.html

@echo off
cl /nologo /O2 /W3 /c /D_CRT_SECURE_NO_DEPRECATE /DLUA_BUILD_AS_DLL l*.c
del lua.obj luac.obj
link /nologo /dll /out:lua51.dll *.obj
lib /nologo /out:lua51.lib *.obj
echo ¡Compilación Exitosa!

Compilación de lua-zlib.dll

Este es el paso central. Debemos enlazar el código fuente de lua-zlib con los archivos zlib y lua51 preparados anteriormente.

1. Clonar el Código Fuente

git clone https://github.com/brimworks/lua-zlib.git
cd lua-zlib

2. Crear el Script de Compilación build_zlib.bat

Cree este script en el directorio del código fuente, modificando las rutas según su ubicación real:

@echo off
set OR_PATH=D:\servidor\openresty-1.25.3.1-nuevo
set LUA_INC=D:\servidor\openresty-1.25.3.1-nuevo\include\luajit-2.1
set ZLIB_INC=C:\vcpkg\installed\x64-windows\include
set ZLIB_LIB=C:\vcpkg\installed\x64-windows\lib

:: 1. Fase de compilación (forzar compilación como código C)
cl /nologo /O2 /W3 /c /TC /D_CRT_SECURE_NO_DEPRECATE ^
   /I"%LUA_INC%" /I"%ZLIB_INC%" lua_zlib.c

:: 2. Fase de enlace (especificar explícitamente nombres de funciones exportadas)
:: Notar el parámetro /EXPORT:luaopen_zlib agregado
link /nologo /dll /out:zlib.dll lua_zlib.obj ^
   /EXPORT:luaopen_zlib ^
   "%OR_PATH%\lua51.lib" "%ZLIB_LIB%\zlib.lib"

echo ¡Terminado!

3. Ejecutar la Compilación

En el Símbolo del sistema para herramientas nativas x64, ejecute:

.\build_zlib.bat

Verificación e Implementación

1. Verificar Funciones Exportadas

Ejecute dumpbin /exports zlib.dll y confirme que la lista de salida contiene:

1 0 00001330 luaopen_zlib

2. Análisis de Dependencias (Importante)

Use la herramienta Dependencies para abrir el zlib.dll generado. Observará que depende de dos archivos clave:

• lua51.dll (ya incluido en OpenResty)
• zlib1.dll (proporcionado por vcpkg)

¡Debe copiar C:\vcpkg\installed\x64-windows\bin\zlib1.dll al directorio raíz de OpenResty (o al directorio donde se encuentra nginx.exe), de lo contrario recibirá el error "El módulo especificado no se encontró"! O bien, agregue C:\vcpkg\installed\x64-windows\bin a la variable de entorno PATH.

3. Prueba

En OpenResty, realice la prueba:

local zlib = require "zlib"
print(zlib.version())

Guía de Prevención de Problemas

1. Coincidencia de Arquitectura: Todo el sistema (OpenResty, zlib, compilador Lua, entorno de línea de comandos VS) debe ser x64.
2. Dependencias DLL: Aunque se genera zlib.dll (lua-zlib), en tiempo de ejecución aún necesita zlib1.dll (el generado por vcpkg). Es necesario colocar zlib1.dll en la ruta PATH de OpenResty o junto a nginx.exe.

Consideraciones Finales

Al compilar extensiones Lua en Windows, los puntos clave son la coincidencia de arquitectura (x64), la coincidencia de la biblioteca en tiempo de ejecución (/MD) y el manejo manual de símbolos exportados (/EXPORT). Si encuentra errores al cargar el módulo, verifique que zlib1.dll esté en las rutas de búsqueda del sistema.