Un colega desarrolló una aplicación para macOS utilizando Qt y encontró un problema al intentar descomprimir archivos con una biblioteca externa llamada libquazip.1.dylib. Al ejecutar la aplicación, esta fallaba con el siguiente error en la consola:

dyld: Library not loaded: libquazip.1.dylib
  Referenced from: /Users/USER/Documents/quawindow.app/Contents/MacOS/quawindow
  Reason: image not found

Este mensaje indica que la aplicación intenta cargar libquazip.1.dylib al iniciarse, pero no puede encontrarla. Aunque el entorno de desarrollo no era el habitual (Xcode), se decidió abordar el problema utilizando la experiencia en desarrollo para macOS.

1. Verificación de la configuración del proyecto Qt

Inicialmente, se confirmó que la configuración del proyecto Qt para la carga de bibliotecas dinámicas en macOS, específicamente para libquazip.1.dylib, parecía correcta en cuanto a rutas y opciones de enlace. Tras revisar la documentación y blogs sobre la configuración de bibliotecas dinámicas en Qt, no se encontraron inconsistencias obvias.

Ante la falta de progreso, se adoptó un enfoque de pensamiento inverso:

• La aplicación sí intenta enlazar con libquazip.1.dylib.
• La biblioteca libquazip.1.dylib existe.
• El problema radica en que la aplicación no puede encontrar la biblioteca.

Esto sugiere que la información proporcionada para localizar la biblioteca es incorrecta, o que la vía de búsqueda de la aplicación tiene un error.

2. Uso de otool para inspeccionar enlaces de archivos Mach-O

Se utilizó la herramienta de línea de comandos otool, comúnmente empleada en el desarrollo y análisis de binarios de iOS/macOS, para examinar la información de enlace del ejecutable de la aplicación.

La estructura típica de un paquete de aplicación (.app) en macOS es la siguiente:

YourApp.app
├── Contents
│   ├── MacOS
│   │   └── YourAppExecutable  (El binario ejecutable)
│   ├── Frameworks
│   │   └── YourFramework.framework
│   │       └── ...
│   ├── Resources
│   │   └── ...
│   └── Info.plist
└── ...

Se ejecutó el siguiente comando para listar las bibliotecas dinámicas que el ejecutable principal intenta cargar:

otool -L /Users/hxq/Documents/quawindow.app/Contents/MacOS/quawindow

La salida mostró:

/Users/hxq/Documents/quawindow.app/Contents/MacOS/quawindow:
    libquazip.1.dylib (compatibility version 1.0.0, current version 1.0.0)
    @rpath/QtWidgets.framework/Versions/5/QtWidgets (compatibility version 5.13.0, current version 5.13.0)
    @rpath/QtGui.framework/Versions/5/QtGui (compatibility version 5.13.0, current version 5.13.0)
    @rpath/QtCore.framework/Versions/5/QtCore (compatibility version 5.13.0, current version 5.13.0)
    /System/Library/Frameworks/DiskArbitration.framework/Versions/A/DiskArbitration (compatibility version 1.0.0, current version 1.0.0)
    /System/Library/Frameworks/IOKit.framework/Versions/A/IOKit (compatibility version 1.0.0, current version 275.0.0)
    /System/Library/Frameworks/OpenGL.framework/Versions/A/OpenGL (compatibility version 1.0.0, current version 1.0.0)
    /System/Library/Frameworks/AGL.framework/Versions/A/AGL (compatibility version 1.0.0, current version 1.0.0)
    /usr/lib/libc++.1.dylib (compatibility version 1.0.0, current version 400.9.4)
    /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1252.250.1)

Se observó que, mientras otras bibliotecas como las de Qt (QtWidgets, QtGui, QtCore) o las del sistema (IOKit, libc++) tienen rutas explícitas o convenciones de búsqueda definidas (@rpath), libquazip.1.dylib solo aparece con su nombre, sin una indicación clara de dónde encontrarla. Este es el punto clave del problema.

Para solucionarlo, se utilizó install_name_tool para modificar la referencia de la biblioteca en el ejecutable prnicipal, apuntándola a una ruta específica donde se encontraba la biblioteca:

install_name_tool -change libquazip.1.dylib /Users/hxq/Documents/libquazip.1.0.0.dylib /Users/hxq/Documents/quawindow.app/Contents/MacOS/quawindow

Tras ejecutar otool -L nuevamente, la salida confirmó el cambio:

/Users/hxq/Documents/quawindow.app/Contents/MacOS/quawindow:
    /Users/hxq/Documents/libquazip.1.0.0.dylib (compatibility version 1.0.0, current version 1.0.0)
    ... (resto de las bibliotecas)

Al probar la aplicación de nuevo, esta se ejecutó sin errores. El problema se originaba en la forma en que se especificaba la ruta de carga de la biblioteca dinámica.

3. Profundizando en las Bibliotecas Dinámicas (dylib)

Las bibliotecas dinámicas (dylib) en macOS son código que no se incluye directamente en el binario ejecutable, sino que se carga en tiempo de ejecución cuando las funciones que contienen son necesarias. El proceso de carga y enlace es gestionado por dyld (dynamic linker).

Un atributo crucial de una dylib es su install name. Este no es solo un nombre, sino que debe ser una ruta que indica dónde se puede encontrar la biblioteca. Las aplicaciones o bibliotecas que dependen de ella utilizan esta información para localizarla.

Se puede verificar el install name de una biblioteca con otool -D:

otool -D /Users/hxq/Documents/libquazip.1.0.0.dylib
/Users/hxq/Documents/libquazip.1.0.0.dylib:
libquazip.1.dylib

En este caso, el install name de libquazip.1.0.0.dylib era simplemente libquazip.1.dylib. Según las convenciones de macOS, debería haber sido una ruta (absoluta o relativa).

4. Mecanismos de Carga de Bibliotecas Dinámicas en macOS

Existen principalmente dos formas en que las aplicaciones dependen de bibliotecas dinámicas:

1. Ubicación en directorios del sistema: Bibliotecas de uso general, como las del sistema operativo (ej. /System/Library/Frameworks/IOKit.framework/..., /usr/lib/libc++.1.dylib). El install name en este caso es una ruta absoluta fija.
2. Inclusión dentro del paquete de la aplicación: Para evitar dependencias externas y facilitar la distribución, las bibliotecas pueden ser empaquetadas dentro del propio archivo .app.

Cuando una biblioteca dinámica se incrusta dentro de una aplicación, se utilizan variables especiales en su install name para definir rutas relativas:

• @executable_path: Se refiere al directorio donde se encuentra el binario ejecutable principal de la aplicación. Si libquazip.1.dylib estuviera en YourApp.app/Contents/Frameworks/, su install name podría ser @executable_path/../Frameworks/libquazip.1.dylib.
• @loader_path: Es similar a @executable_path, pero se refiere al directorio del *binario que está siendo cargado actualmente*. Es más flexible, especialmente cuando hay dependencias entre bibliotecas o extensiones (como .appex). En una aplicación simple, su comportamiento es similar a @executable_path. Su utilidad se ve en escenarios más complejos, como dependencias entre un App Extension y la aplicación principle.
• @rpath: Permite definir rutas de búsqueda adicionales para el cargador dinámico (dyld). Cuando un ejecutable tiene @rpath en el install name de una dependencia, dyld buscará la biblioteca en las rutas especificadas en el Runpath Search Paths del propio ejecutable que la referencia. Esto da más flexibilidad al desarrollador de la aplicación principal para controlar dónde se buscan las dependencias.

5. Resolución del Error dyld: Library not loaded

Entendiendo los puntos anteriores, el problema se resumía en que dyld no encontraba libquazip.1.dylib debido a una especificación incorrecta de su ruta de carga (install name). La solución era modificar este install name para que apuntara a una ubicación válida dentro del paquete de la aplicación.

En el caso del proyecto Qt, se configuró para que libquazip.1.dylib se copiara a quawindow.app/Contents/PlugIns/zip/. Luego, se utilizó install_name_tool para establecer el install name de la biblioteca a:

install_name_tool -id "@loader_path/../Plugins/zip/libquazip.1.dylib" /Users/hxq/Documents/quawindow.app/Contents/PlugIns/zip/libquazip.1.dylib

Alternativamente, se podría haber usado @executable_path. Con esta modificación, dyld pudo localizar y cargar la biblioteca dinámica correctamente, resolviendo el colapso de la aplicación.

6. Resumen

La investigación y resolución de este problema permitieron:

• Comprender a fondo el mecanismo de carga de bibliotecas dinámicas en macOS, incluyendo el papel de dyld y la importancia del install name.
• Familiarizarse con las convenciones de rutas relativas (@executable_path, @loader_path, @rpath) para bibliotecas incrustadas.
• Reafirmar la utilidad de herramientas como otool y install_name_tool para el análisis y modificación de binarios Mach-O.

La clave para resolver este tipo de errores es examinar cómo el binario principal o las bibliotecas referenciadas especifican la ubicación de sus dependencias dinámicas y asegurarse de que estas referencias sean válidas y accesibles en el entorno de despliegue.