La estructura de construcción

La generación del código fuente para una API envoltorio del estilo de gtkmm requiere el uso de herramientas como gmmproc y generate_wrap_init.pl. En teoría, podría escribir sus propios archivos de construcción para usarlas apropiadamente, pero una opción mucho mejor es hacer uso de la infraestructura de construcción proporcionada por el módulo mm-common. Para empezar, ayuda mucho escoger un módulo de enlace existente como un ejemplo para consultar.

Por ejemplo, imagine que se quiere envolver una biblioteca de C llamada libexample. Proporciona una API basada en GObject con tipos nombrados, por ejemplo, ExampleThing y ExampleStuff.

G.1.1. Copiar el esqueleto del proyecto

Típicamente la biblioteca envoltorio se llamaría libsomethingmm. Se puede empezar copiando el esqueleto del árbol de código fuente desde el módulo mm-common.

  $ git clone git://git.gnome.org/mm-common
  $ cp -a mm-common/skeletonmm libsomethingmm

Esto proporciona una estructura de carpetas para los archivos de fuentes .hg y .ccg, y los archivos .h y .cc generados; con archivos de cabecera filelist.am de Automake que pueden especificar la variedad de archivos en uso, en términos de variables de Automake genéricas. La estructura de carpetas generalmente se ve así, después de haber renombrado las carpetas apropiadamente:

  • libsomethingmm: la carpeta de nivel superior.

    • libsomething: contiene el archivo de cabecera principal y el archivo .pc de pkg-config.

      • src: contiene los archivos de fuentes .hg y .ccg.

      • libsomethingmm: contiene los archivos .h y .cc generados y escritos a mano.

        • private: contiene los archivos *_p.h generados.

Además de renombrar las carpetas, se deben renombrar algunos de los archivos de fuentes. Por ejemplo:

$ for f in $(find libsomethingmm -depth -name '*skeleton*'); do \
    d="${f%/*}"; b="${f##*/}"; mv "$f" "$d/${b//skeleton/libsomething}"; \
  done
Algunos de los archivos esqueleto todavía deberán llenarse después con contenido específico del proyecto.

Tenga en cuenta que los archivos que terminan en .in se utilizan para generar archivos con el mismo nombre pero sin el sufijo .in, mediante la sustitución de algunas variables con valores reales durante la fase de configuración.

G.1.2. Modificar archivos de construcción

Ahora se editan los archivos para adaptarlos a las necesidades. Tal vez prefiera usar una utilidad para buscar y reemplazar múltiples archivos, como regexxer. Tenga en cuenta que casi todos los archivos proporcionados con el esqueleto del árbol de fuentes contienen texto con marcadores de posición. Es por esto que las sustituciones se deben hacer globalmente, y no limitarse a los archivos de Automake y Autoconf.

Todas las menciones de skeleton deben reemplazarse por el nombre correcto de la biblioteca de C que está envolviendo, como «something» o «libsomething». De la misma manera, todas las instancias de SKELETON deben reemplazarse por «SOMETHING» o «LIBSOMETHING», y todas las apariciones de Skeleton deben cambiarse por «Something».

De la misma manera, reemplace todas las instancias de Joe Hacker por el nombre del titular de los derechos de autor, quien probablemente sea usted. Haga lo mismo para la dirección de correo-e [email protected].

G.1.2.1. configure.ac

En configure.ac,

  • La línea AC_CONFIG_SRCDIR() debe mencionar un archivo en el árbol de fuentes. Se puede editar esto más tarde si todavía no se saben los nombres de ninguno de los archivos que se crearán.
  • Es común cuando se enlazan módulos rastrear el número de versión de la biblioteca que se está envolviendo. Entonces, por ejemplo, si la biblioteca de C está en una versión 1.23.4, el número de versión inicial del módulo de enlace sería 1.23.0. Sin embargo, evite comenzar con un número de versión menor par, ya que generalmente indica una versión estable.
  • La línea AC_CONFIG_HEADERS() se usa para generar dos o más archivos de cabecera de configuración. El primer archivo de cabecera en la lista contiene a todas las macros de configuración que se establecen durante la ejecución de «configure». Las cabeceras restantes en la lista contienen sólo una parte de las macros de configuración y el archivo configh.h.in correspondiente a estas no se autogenerará. La razón de esta separación es que las cabeceras de configuración con espacios de nombres se instalan con su biblioteca y definen macros públicamente visibles.
  • La línea AC_SUBST([SOMETHINGMM_MODULES], ['...']) tal vez necesite modificarse para verificar las dependencias correctas.
  • El bloque AC_CONFIG_FILES() debe mencionar a los nombres de carpetas correctos, como se describió anteriormente.

G.1.2.2. Archivos Makefile.am

A continuación se deben adaptar los archivos Makefile.am:

  • En skeleton/src/Makefile.am se deben mencionar los valores correctos para las variables genéricas que se usan en otros lados en el sistema de construcción:

    binding_name

    El nombre de la biblioteca, por ejemplo libsomethingmm.

    wrap_init_flags

    Opciones de línea de comandos adicionales pasadas al «script» generate_wrap_init.pl, como el espacio de nombres de C++ y el prefijo de la carpeta padre de los archivos de cabecera.

  • En skeleton/skeletonmm/Makefile.am se deben mencionar los valores correctos de las variables genéricas que se usan en otros lados en el sistema de construcción:

    lib_LTLIBRARIES

    Esta variable debe mencionar el nombre de la biblioteca correcta, y este nombre de biblioteca debe usarse para formar los nombres de variables _SOURCES, _LDFLAGS, y _LIBADD. Está permitido usar variables sustituidas por configure, como @SOMETHINGMM_API_VERSION@ como parte de los nombres de las variables.

    AM_CPPFLAGS

    Las opciones de línea de comandos pasadas al preprocesador de C.

    AM_CXXFLAGS

    Las opciones de línea de comandos pasadas al compilador de C++

G.1.2.3. Crear archivos .hg y .ccg

Ahora se deben crear los primeros archivos .hg y .ccg, para envolver uno de los objetos en la biblioteca de C. Ya existen un par de archivos de fuentes de ejemplo: skeleton.ccg y skeleton.hg. Cree copias de estos archivos si es necesario.

Se deben mencionar todos los archivos .hg y .ccg en el archivo skeleton/src/filelist.am, típicamente en la variable files_hg.

Cualquier archivo de fuentes .h y .cc adicional no generado se puede poner en skeleton/skeletonmm/ y listar en skeleton/skeletonmm/filelist.am, típicamente en las variables files_extra_h y files_extra_cc.

En la sección archivos .hg y .ccg puede aprender acerca de la sintaxis usada en estos archivos.