Spanish/Doc/TutorialAutomake

From The Player Project

Revision as of 10:40, 6 June 2009 by Thjc (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

/** @ingroup tutorials @defgroup tutorial_automake Usar Player con Automake @brief Una breve introducción a cómo funciona Automake

@note Partes de este documente han sido adaptadas del documento de trucos de programación en C y C++ de Vishal Patil. Para un mayor conocimiento del tema se sugiere el documento original.

Índice:

- @ref directory - @ref configuration - @ref example

   - @ref configure
   - @ref makefile
   - @ref doc

- @ref bootstrap - @ref build


@p Automake y @p Autoconf son herramientas diseñadas para ayudar a los desarroladores a solucionar los problemas asocioados con escribir ficheros @p Makefile en proyectos. Estas herramientas ayudan durante el desarrollo del software y durante la instalación en varios tipos de sistemas. Haré una pequeña introducción a estas herramientas y explicaré cómo utilizarlas para aplicaciones propias.

@section directory Estructura de directorios

El directorio de un proyecto normalmente tiene los siguientes subdirectorios:

- @b src : Contiene el código fuente para ser compilado. A menudo, el directorio @p src contiene información para un solo ejecutable o librería , pero es posible que se creen varios ejecutables por directorio.

- @b doc : Contiene la documentación del proyecto. Si se usa doxigen o cualquier otro programa para autogenerar la documentación, es una buena idea construir el fichero @p Makefile en ese directorio de tal forma que se pueda ejecutar allí @p make @p doc para generar automáticamente la documentación.

Player tiene una estructura de directorios más grande y ligeramente diferente, pero que funciona con los mismos principios generales.

@section configuration Ficheros de configuración

Hay dos ficheros de configuración principales usados por estas herramientas

- @b configure.ac : Usado por @p autoconf para generar el script de configuración específico para la plataforma. Solamente uno es necesario por cada proyecto. - @b Makefile.am : Usado por @p automake para general los ficheros @p Makefile en cada uno de los directorios fuentes. Típicamente un proyecto contendrá un fichero @b Makefile.am en cada directorio.

@section example Un pequeño ejemplo

A veces la mejor forma de explicar un nuevo tema es usando un ejemplo. Crearemos un proyecto que usa @p automake y @p autoconf para construcir una aplicación C++. Todo el código para este ejemplo está incluido en examples/tutorial_automake

@subsection configure configure.ac

Este fichero es usado por @p autoconf para general el script de configure para la plataforma, y como tal contiene diversas macros para examinar el sistema.

@include /tutorial_automake/configure.ac

En el fichero @p configure.ac del ejemplo de arriba, los parametros que se pasan a la función AM_INIT_AUTOMAKE representan el nombre del paquete y el número de versión respectivamente.

La macro PKG_CHECK_MODULES es entonces usada para buscar un fichero llamado @p playerc++.pc. La mayoría de los proyectos que usan @p autotools proporcional a los usuarios el fichero de configuración del paquete. Este fichero contiene información sobre donde se ha instalado el programa en el sistema e información sobre cualquier opción que se necesite para las bibliotecas o el compilador.

@note Si se está instalando Player, necesita estar seguro de que el PKG_CONFIG_PATH es ajustado de tal forma que el directorio donde el código está instalado es incluido en el path de búsqueda. Si se está usando Bash, puede añadir lo siguiente (o algo similar) en su ~/.bashrc. @verbatim

  1. for .pc in /usr/local

export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/usr/local/lib/pkgconfig/ @endverbatim

AC_SUBST es entonces usado para hacer que las variables CFLAGS y LIBS puedan ser usadas por los ficheros @p Makefile.am, esto lo explicaré en su momento.

La función AC_CONFIG_FILES necesita los path de los @p Makefiles que necesitan ser generados basados en el @p Makefile.am de cada directorio.

@subsection makefile Makefile.am

Un fichero Makefile.am es un conjunto de reglas específicas usadas para saber como las variables son usadas y asignadas en los ficheros @p Makefile.am. Discutiré algunas de las más interesantes, pero el resto están más allá de los propósitos de este manual. Los siguientes correspondencias son generales para todos el fichero @p Makefile actual.

@verbatim AM_CPPFLAGS = SOME_FLAGS -g INCLUDES = -I/some_include_directory LDFLAGS = -L/some_lib_directory LDADD = -llibname @endverbatim

- En AM_CPPFLAGS es donde se insertan las opciones c/cpp que le gustarían que fueran usadas por el precompilador, como por ejemplo DEBUG or flags similares. También se pueden especificar las opciones del compilador aquí.

- En INCLUDES es donde se insertan las opciones -I necesarias para el compilador. Si el código de este directorio depende en una biblioteca en otro directorio del mismo paquete, entonces la opción -I debe apuntar a ese directorio.

- En LDFLAGS es donde se insertan las opciones -L que se necesitan por el compilador cuando enlaza todos los ficheros objetos para crear un ejecutable.

- En LDADD es donde se enumeran un confunto de bibliotecas instaladas con las cuales se quieren enlazar todos los ejecutables. Solo se puede utilizar la opción -l para las bibliotecas que están instaladas. Se pueden enumerar las bibliotecas que han sido construidas pero no instaladas también pero sólo si se proporciona el camino completo hasta esas bibliotecas.


Si tu paquete contiene subdirectorios con bibliotecas y quieres enlazar esas bibliotecas en otro subdirectorio, se necesita las opciones '-I' y '-L' en las dos variables anteriores. Para expresar el camino a esos otros subdirectorios, se usa la variable $(top srcdir). Por ejemplo si quieres acceder a una biblioteca en src/libfoo, en el 'Makefile.am' de cada nivel de directorios que quiera acceder a esas bibliotecas. se debe indicar lo siguiente:

@verbatim INCLUDES = ... -I$(top_srcdir)/src/libfoo ... LDFLAGS = ... -L$(top_srcdir)/src/libfoo ... @endverbatim

Además, debe asegurarse de que las bibliotecas sean construidas antes de que ese nivel de directorio sea construido. Para garantizar esto, hay que enumerar los directorios con las bibliotecas en SUBDIRS antes que los niveles de directorios que dependen de ellas. Una forma de hacer esto es poner todos los directorios con ejecutables en el directorio @p bin y todas las bibliotecas en el directorio @p lib. En el @ Makefile.am para los niveles de directorio que contienen @p lib y @p bin pondremos:

@verbatim SUBDIRS = lib bin @endverbatim

@subsection targets Resultados de la compilación

Para cada objetivo se puede especificar los parámetros INCLUDES, LDFLAG, y/o LDADD. Estos están asociados a cómo se define los objetivos para la compilación. En nuestro caso tenemos un ejecutable llamado @p example.

@include /tutorial_automake/src/Makefile.am

- La macro bin_PROGRAMS indica qué objetivos se compilaremos. Hay una gran cantidad de formas para especificar esos objetivos. La etiqueta @p bin_ indica que se desea instalar el programa cuando se ejecuta @p make @p install. Podemos también especificar @p noinst_ que indica que no queremos instalar ese programa (útil para programas usados como herramientas de pruebas). También se puede indicar que se está construyendo una biblioteca con lib_LTLIBRARIES (esto es usado para los drivers usados en Player como plugin).

Para cada objetivo, además, se puede especificar SOURCES, CPPFLAGS, LDFLAGS, y/o LDADD.

@subsection doc Generando documentación

Para demostrar otro aspecto de los ficheros @p Makefile.am, configuraremos el código necesario para ejecutar el comando @p make @p doc en el directorio doc y construir los documentación a partir de comentarios, gracias a Doxygen. Para usar Doxygen automáticamente para generar documentación se usa el siguiente comando:

@verbatim > doxygen example.dox @endverbatim

donde example.dox es un fichero de configuración de doxygen típicamente generado por una herramienta como @p doxywizard. Para conseguir esto con un fichero @p makefile, se debe usar la ventaja de poder introducir sintaxis tradicional de @p Makefile dentro de un fichero @p Makefile.am. Por ejemplo:

@include /tutorial_automake/doc/Makefile.am

EXTRA_DIST indica que el fichero @p example.dox es parte del proyecto y debe ser distribuido. Esto es útil si se empaqueta el código para distribuirlo con el comando @p make @p dist. Hay que notar que la línea con el comando doxigen está en la sintaxis típica de @p Makefile y por tanto, se necesita asegurar que se ha usado un caracter TAB en vez de espacios delante de @p doxygen.

@section bootstrap Generando los scripts de construcción de la aplicación

Se necesitan ejecutar los siguientes comandos para generar los scripts de construcción. Típicamente, están agrupados juntos en un único script llamado @p bootstrap. También proveeremos de algunas opciones para forzar ciertas tareas que pueden llevarse a cabo, no son necesarias pero útiles.

@include /tutorial_automake/bootstrap

Después de generar los scripts, se puede ejecutar el típico @p configure para acabar de configurar la aplicación.

@section build Opciones

Se necesita ejecutar el script configure antes de construir el proyecto usando make. Despues de ejecutar sin errores el script configure las siguientes opciones están disponibles para make:

- @p make : Construye el proyecto: ejecutables y bibliotecas. - @p make @p clean : Limpia el proyecto: Borra los ejecutables. - @p make @p install  : Construye e instala el proyecto: Los ejecutables son copiados en /prefix/bin, los ficheros .h en /prefix/include y las bibliotecas en /prefix/lib donde prefix suele ser /usr/local. - @p make @p uninstall : Desinstala el proyecto: Borra los ficheros añadidos a /prefix/bin/, /prefix/include y /prefix/lib - @p make @p dist : Crea una distribución del proyecto (fichero \<package-name\>- \<version\>.tar.gz )

@section references Referencias

- <a href="http://autotoolset.sourceforge.net/tutorial.html">

   Learning the GNU development tools</a>

- <a href="http://sources.redhat.com/automake/">GNU Automake</a> - <a href="http://www.geocities.com/foetsch/mfgraph/automake.htm">GNU Automake By Example</a> - <a href="http://autoconf-archive.cryp.to/">Autoconf Macro Archive</a> - <a href="http://ac-archive.sourceforge.net/">AC-Archive</a>

  • /
Personal tools