Este capítulo describe las convenciones para escribir los Makefiles de los programas GNU. Usar Automake le ayudará a escribir un Makefile que siga estas convenciones. Si desea más información sobre Makefiles portables, consulte el estándar POSIX y el apartado Portable Make Programming del manual de Autoconf.
DESTDIR: soporte para instalaciones por etapasTodo Makefile debería incluir esta línea:
SHELL = /bin/sh
Sirve para evitar problemas en sistemas donde la variable SHELL podría heredarse del entorno. (Con GNU make esto nunca supone un problema.)
Algunos programas make tienen listas de sufijos y reglas implícitas incompatibles entre sí, y esto a veces genera confusión o un comportamiento erróneo. Por eso es buena idea fijar explícitamente la lista de sufijos usando solo los sufijos que se necesitan en ese Makefile concreto, de esta manera:
.SUFFIXES: .SUFFIXES: .c .o
La primera línea vacía la lista de sufijos; la segunda introduce todos los sufijos que pueden estar sujetos a reglas implícitas en este Makefile.
No dé por hecho que . (el directorio actual) está en la ruta de ejecución de órdenes. Cuando necesite ejecutar, durante el make, programas que forman parte de su propio paquete, asegúrese de anteponer ./ si el programa se construye como parte del make, o $(srcdir)/ si el archivo es una parte inmutable del código fuente. Sin alguno de estos prefijos, se usa la ruta de búsqueda vigente en ese momento.
La distinción entre ./ (el directorio de construcción) y $(srcdir)/ (el directorio fuente) es importante, porque los usuarios pueden construir en un directorio distinto mediante la opción «--srcdir» de configure. Una regla de la forma:
foo.1 : foo.man sedscript
sed -f sedscript foo.man > foo.1
fallará cuando el directorio de construcción no sea el directorio fuente, porque foo.man y sedscript están en el directorio fuente.
Al usar GNU make, confiar en «VPATH» para encontrar el archivo fuente funciona cuando hay un único prerrequisito (prerequisite), ya que la variable automática «$<» de make representa el archivo fuente esté donde esté. (Muchas versiones de make solo fijan «$<» dentro de las reglas implícitas.) Así pues, un objetivo de Makefile como
foo.o : bar.c
$(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
debería escribirse en su lugar de la siguiente manera:
foo.o : bar.c
$(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
para que «VPATH» funcione correctamente. Cuando el objetivo tiene varios prerrequisitos, usar explícitamente «$(srcdir)» es la forma más sencilla de hacer que la regla funcione bien. Por ejemplo, el objetivo anterior para foo.1 se escribe mejor así:
foo.1 : foo.man sedscript
sed -f $(srcdir)/sedscript $(srcdir)/foo.man > $@
Las distribuciones de GNU suelen contener algunos archivos que no son archivos fuente; por ejemplo, archivos Info, o la salida de Autoconf, Automake, Bison o Flex. Como estos archivos normalmente aparecen en el directorio fuente, deberían situarse siempre en el directorio fuente y no en el de construcción. Por tanto, las reglas del Makefile que los actualizan deberían dejar los archivos actualizados en el directorio fuente.
Sin embargo, los archivos que no forman parte de la distribución no deberían colocarse en el directorio fuente, porque construir un programa en circunstancias normales no debería modificar el directorio fuente en modo alguno.
Procure que, al menos, los objetivos de construcción e instalación (y todos sus subobjetivos) funcionen correctamente con un make en paralelo.
Escriba las órdenes del Makefile (y cualquier script de shell, como configure) para que funcionen bajo sh (tanto el shell Bourne tradicional como el shell POSIX), no bajo csh. No use ninguna característica especial de ksh o bash, ni características de POSIX que no estén ampliamente soportadas en el sh Bourne tradicional.
El script configure y las reglas del Makefile para la construcción y la instalación no deberían usar directamente ninguna utilidad salvo estas:
awk cat cmp cp diff echo expr false grep install-info ln ls mkdir mv printf pwd rm rmdir sed sleep sort tar test touch tr true
Los programas de compresión como gzip pueden usarse en la regla dist.
En general, limítese a las opciones y características ampliamente soportadas (normalmente especificadas por POSIX) de estos programas. Por ejemplo, no use «mkdir -p», por conveniente que resulte, porque hay unos pocos sistemas que no lo soportan en absoluto y, en otros, no es seguro para la ejecución en paralelo. Para una lista de incompatibilidades conocidas, consulte el apartado Portable Shell Programming del manual de Autoconf.
Es prudente evitar crear enlaces simbólicos en los makefiles, ya que unos pocos sistemas de archivos no los soportan.
Las reglas del Makefile para la construcción y la instalación también pueden usar compiladores y programas afines, pero deberían hacerlo a través de variables de make, de modo que el usuario pueda sustituirlos por alternativas. Estos son algunos de los programas a los que nos referimos:
ar bison cc flex install ld ldconfig lex make makeinfo ranlib texi2dvi yacc
Para ejecutar esos programas, use las siguientes variables de make:
$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX) $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
Cuando use ranlib o ldconfig, asegúrese de que no ocurra nada malo si el sistema no dispone de ese programa. Disponga las cosas para ignorar un error de esa orden e imprima un mensaje antes de la orden que indique al usuario que el fallo de esta orden no supone un problema. (La macro «AC_PROG_RANLIB» de Autoconf puede ayudar en esto.)
Si usa enlaces simbólicos, debería implementar una alternativa (fallback) para los sistemas que no tienen enlaces simbólicos.
Otras utilidades que pueden usarse a través de variables de Make son:
chgrp chmod chown mknod
En las partes del Makefile (o en los scripts) destinadas únicamente a sistemas concretos donde sabe que esas utilidades existen, está bien usar otras utilidades.
Los Makefiles deberían ofrecer variables para anular determinadas órdenes, opciones, etc.
En particular, debería ejecutar la mayoría de los programas de utilidad a través de variables. Así, si usa Bison, defina una variable llamada BISON cuyo valor por defecto se establezca con «BISON = bison», y refiérase a ella con $(BISON) cada vez que necesite usar Bison.
Las utilidades de gestión de archivos como ln, rm, mv, etc., no necesitan referenciarse a través de variables de este modo, ya que los usuarios no necesitan sustituirlas por otros programas.
Cada variable que representa un nombre de programa debería ir acompañada de una variable de opciones que sirva para pasar opciones a ese programa. El nombre de la variable de opciones se forma añadiendo «FLAGS» al final del nombre de la variable del programa; por ejemplo, BISONFLAGS. (Los nombres CFLAGS para el compilador de C, YFLAGS para yacc y LFLAGS para lex son excepciones a esta regla, pero los conservamos porque son estándar.) Use CPPFLAGS en cualquier orden de compilación que ejecute el preprocesador, y use LDFLAGS en cualquier orden de compilación que también enlace, así como en cualquier uso directo de ld.
Si hay opciones del compilador de C que deben usarse para compilar correctamente ciertos archivos, no las incluya en CFLAGS. Los usuarios esperan poder especificar CFLAGS libremente por sí mismos. En su lugar, disponga las cosas para pasar las opciones necesarias al compilador de C de forma independiente de CFLAGS, escribiéndolas explícitamente en las órdenes de compilación o definiendo una regla implícita, así:
CFLAGS = -g
ALL_CFLAGS = -I. $(CFLAGS)
.c.o:
$(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
Sí incluya la opción «-g» en CFLAGS, porque no es imprescindible para una compilación correcta. Puede considerarla un valor por defecto que solo se recomienda. Si el paquete está preparado para compilarse con GCC por defecto, bien podría incluir también «-O» en el valor por defecto de CFLAGS.
Coloque CFLAGS en último lugar en la orden de compilación, después de las demás variables que contienen opciones del compilador, de modo que el usuario pueda usar CFLAGS para anular las otras.
CFLAGS debería usarse en cada invocación del compilador de C, tanto en las que hacen compilación como en las que hacen enlazado.
Todo Makefile debería definir la variable INSTALL, que es la orden básica para instalar un archivo en el sistema.
Todo Makefile debería definir también las variables INSTALL_PROGRAM e INSTALL_DATA. (El valor por defecto de INSTALL_PROGRAM debería ser $(INSTALL); el de INSTALL_DATA debería ser ${INSTALL} -m 644.) Después, debería usar esas variables como las órdenes para la instalación real: la primera para los archivos ejecutables y la segunda para los no ejecutables. El uso mínimo de estas variables es el siguiente:
$(INSTALL_PROGRAM) foo $(bindir)/foo $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
No obstante, es preferible admitir un prefijo DESTDIR en los archivos de destino, como se explica en el apartado siguiente.
Se admite, aunque no es obligatorio, instalar varios archivos con una sola orden, siendo el último argumento un directorio, como en:
$(INSTALL_PROGRAM) foo bar baz $(bindir)
DESTDIR: soporte para instalaciones por etapas
DESTDIR es una variable que se antepone a cada archivo de destino instalado, así:
$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
El usuario especifica la variable DESTDIR en la línea de órdenes de make como un nombre de archivo absoluto. Por ejemplo:
make DESTDIR=/tmp/stage install
DESTDIR solo debería admitirse en los objetivos install* y uninstall*, ya que son los únicos objetivos en los que resulta útil.
Si su paso de instalación normalmente instalara /usr/local/bin/foo y /usr/local/lib/libfoo.a, entonces una instalación invocada como en el ejemplo anterior instalaría en su lugar /tmp/stage/usr/local/bin/foo y /tmp/stage/usr/local/lib/libfoo.a.
Anteponer de este modo la variable DESTDIR a cada destino permite las instalaciones por etapas (staged installs), en las que los archivos instalados no se colocan directamente en su ubicación prevista, sino que se copian a una ubicación temporal (DESTDIR). Aun así, los archivos instalados mantienen su estructura de directorios relativa y no se modifica ningún nombre de archivo incrustado en su contenido.
No debería fijar en absoluto el valor de DESTDIR dentro de su Makefile; de ese modo, por defecto los archivos se instalan en sus ubicaciones previstas. Además, especificar DESTDIR no debería cambiar de ninguna manera el funcionamiento del software, por lo que su valor no debería incluirse en el contenido de ningún archivo.
El soporte de DESTDIR se usa habitualmente en la creación de paquetes. También resulta útil para los usuarios que quieren entender qué instalará un paquete y dónde, y para permitir que usuarios que normalmente no tienen permiso para instalar en áreas protegidas puedan construir e instalar antes de obtener esos permisos. Por último, puede ser útil con herramientas como stow, que instalan el código en un sitio pero hacen que parezca instalado en otro mediante enlaces simbólicos u operaciones de montaje especiales. Por todo ello, aunque no es un requisito absoluto, recomendamos encarecidamente que los paquetes GNU admitan DESTDIR.
Los directorios de instalación deberían nombrarse siempre con variables, para que resulte fácil instalar en un lugar no estándar. A continuación se describen los nombres estándar de estas variables y los valores que deberían tener en los paquetes GNU. Se basan en una distribución estándar del sistema de archivos, cuyas variantes se usan en GNU/Linux y otros sistemas operativos modernos.
Se da por supuesto que quienes instalan pueden anular estos valores al invocar make (por ejemplo, make prefix=/usr install) o configure (por ejemplo, configure --prefix=/usr). Los paquetes GNU no deberían intentar adivinar qué valor sería apropiado para estas variables en el sistema en el que se instalan: use la configuración por defecto especificada aquí, de modo que todos los paquetes GNU se comporten igual y quien instala pueda lograr la distribución que desee.
Todos los directorios de instalación, y sus directorios padre, deberían crearse (si es necesario) antes de instalar en ellos.
Estas dos primeras variables fijan la raíz de la instalación. Todos los demás directorios de instalación deberían ser subdirectorios de uno de estos dos, y no debería instalarse nada directamente en estos dos directorios.
prefixUn prefijo que se usa para construir los valores por defecto de las variables que se enumeran a continuación. El valor por defecto de prefix debería ser /usr/local. Al construir el sistema GNU completo, el prefijo estará vacío y /usr será un enlace simbólico a /. (Si usa Autoconf, escríbalo como «@prefix@».)
Ejecutar «make install» con un valor de prefix distinto del que se usó para construir el programa no debería recompilar el programa.
exec_prefixUn prefijo que se usa para construir los valores por defecto de algunas de las variables que se enumeran a continuación. El valor por defecto de exec_prefix debería ser $(prefix). (Si usa Autoconf, escríbalo como «@exec_prefix@».)
En general, $(exec_prefix) se usa para los directorios que contienen archivos específicos de la máquina (como ejecutables y bibliotecas de subrutinas), mientras que $(prefix) se usa directamente para los demás directorios.
Ejecutar «make install» con un valor de exec_prefix distinto del que se usó para construir el programa no debería recompilar el programa.
Los programas ejecutables se instalan en uno de los siguientes directorios.
bindirEl directorio para instalar los programas ejecutables que los usuarios pueden ejecutar. Normalmente debería ser /usr/local/bin, pero se escribe como $(exec_prefix)/bin. (Si usa Autoconf, escríbalo como «@bindir@».)
sbindirEl directorio para instalar los programas ejecutables que pueden ejecutarse desde el shell, pero que en general solo son útiles para los administradores del sistema. Normalmente debería ser /usr/local/sbin, pero se escribe como $(exec_prefix)/sbin. (Si usa Autoconf, escríbalo como «@sbindir@».)
libexecdirEl directorio para instalar los programas ejecutables que ejecutan otros programas, y no los usuarios. Normalmente debería ser /usr/local/libexec, pero se escribe como $(exec_prefix)/libexec. (Si usa Autoconf, escríbalo como «@libexecdir@».)
La definición de «libexecdir» es la misma para todos los paquetes, por lo que debería instalar los datos de su paquete en un subdirectorio de ese directorio. La mayoría de los paquetes instalan sus datos bajo $(libexecdir)/package-name/, posiblemente dentro de subdirectorios adicionales de este (por ejemplo, $(libexecdir)/package-name/machine/version).
Los archivos de datos que usa el programa durante su ejecución se clasifican desde dos puntos de vista.
Esto da lugar a seis posibilidades distintas. Sin embargo, queremos desaconsejar el uso de archivos dependientes de la arquitectura, aparte de los archivos objeto y las bibliotecas. Es mucho más limpio hacer que los demás archivos de datos sean independientes de la arquitectura, y por lo general no resulta difícil.
Estas son las variables que los Makefiles deberían usar para especificar los directorios en los que colocar estos diversos tipos de archivos:
La raíz del árbol de directorios para los archivos de datos de solo lectura e independientes de la arquitectura. Normalmente debería ser /usr/local/share, pero se escribe como $(prefix)/share. (Si usa Autoconf, escríbalo como «@datarootdir@».) El valor por defecto de «datadir» se basa en esta variable; también el de «infodir», «mandir» y otros.
El directorio para instalar los archivos de datos de solo lectura, independientes de la arquitectura y propios de este programa. Suele ser el mismo lugar que «datarootdir», pero usamos dos variables separadas para que pueda mover estos archivos específicos del programa sin alterar la ubicación de los archivos Info, las páginas man, etc.
Normalmente debería ser /usr/local/share, pero se escribe como $(datarootdir). (Si usa Autoconf, escríbalo como «@datadir@».)
La definición de «datadir» es la misma para todos los paquetes, por lo que debería instalar sus datos en un subdirectorio de ese directorio. La mayoría de los paquetes instalan sus datos bajo $(datadir)/package-name/.
El directorio para instalar los archivos de datos de solo lectura que conciernen a una sola máquina, es decir, los archivos para configurar un host. Aquí pertenecen los archivos de configuración del correo y de la red, /etc/passwd, etc. Todos los archivos de este directorio deberían ser archivos de texto ASCII corriente. Normalmente debería ser /usr/local/etc, pero se escribe como $(prefix)/etc. (Si usa Autoconf, escríbalo como «@sysconfdir@».)
No instale ejecutables en este directorio (probablemente pertenecen a $(libexecdir) o $(sbindir)). Tampoco instale archivos que se modifiquen en el transcurso normal de su uso (excepto los programas cuyo propósito es cambiar la configuración del sistema). Estos probablemente pertenecen a $(localstatedir).
El directorio para instalar los archivos de datos independientes de la arquitectura que los programas modifican mientras se ejecutan. Normalmente debería ser /usr/local/com, pero se escribe como $(prefix)/com. (Si usa Autoconf, escríbalo como «@sharedstatedir@».)
El directorio para instalar los archivos de datos que los programas modifican mientras se ejecutan y que conciernen a una máquina concreta. Nunca debería ser necesario que un usuario modifique archivos de este directorio para configurar el funcionamiento del paquete; ponga esa información de configuración en archivos aparte, que vayan en $(datadir) o $(sysconfdir). $(localstatedir) normalmente es /usr/local/var, pero se escribe como $(prefix)/var. (Si usa Autoconf, escríbalo como «@localstatedir@».)
El directorio para instalar los archivos de datos que los programas modifican mientras se ejecutan, que conciernen a una máquina concreta y que no necesitan persistir más allá de la ejecución del programa. Los archivos que aquí se colocan suelen ser de larga vida, por ejemplo, hasta el siguiente reinicio. Un uso típico son los archivos PID de los demonios del sistema. Además, este directorio no debería limpiarse (salvo, quizá, en el reinicio), mientras que el /tmp general (TMPDIR) puede limpiarse en cualquier momento. Normalmente debería ser /var/run, pero se escribe como $(localstatedir)/run. Tenerlo como variable aparte permite usar, por ejemplo, /run si así se desea. (Si usa Autoconf 2.70 o posterior, escríbalo como «@runstatedir@».)
Las siguientes variables especifican el directorio para instalar ciertos tipos concretos de archivos, si su programa los tiene. Todo paquete GNU debería tener archivos Info, por lo que todo programa necesita «infodir», pero no todos necesitan «libdir» ni «lispdir».
El directorio para instalar los archivos de cabecera que los programas de usuario incluyen mediante la directiva de preprocesador «#include» de C. Normalmente debería ser /usr/local/include, pero se escribe como $(prefix)/include. (Si usa Autoconf, escríbalo como «@includedir@».)
La mayoría de los compiladores distintos de GCC no buscan archivos de cabecera en el directorio /usr/local/include. Por tanto, instalar los archivos de cabecera de este modo solo es útil con GCC. A veces esto no supone un problema, porque algunas bibliotecas están pensadas realmente para funcionar solo con GCC. Pero otras bibliotecas están pensadas para funcionar también con otros compiladores. Esas bibliotecas deberían instalar sus archivos de cabecera en dos lugares: uno especificado por includedir y otro especificado por oldincludedir.
El directorio para instalar los archivos de cabecera «#include» destinados a compiladores distintos de GCC. Normalmente es /usr/include. (Si usa Autoconf, puede escribirlo como «@oldincludedir@».)
Las órdenes del Makefile deberían comprobar si el valor de oldincludedir está vacío. Si lo está, no deberían intentar usarlo; deberían cancelar la segunda instalación de los archivos de cabecera.
Un paquete no debería reemplazar una cabecera existente en este directorio a menos que la cabecera provenga del mismo paquete. Así, si su paquete Foo proporciona un archivo de cabecera foo.h, entonces debería instalar el archivo de cabecera en el directorio oldincludedir si (1) no hay allí ningún foo.h, o (2) el foo.h que existe proviene del paquete Foo.
Para saber si foo.h proviene del paquete Foo, ponga en el archivo una cadena mágica (como parte de un comentario) y búsquela con grep.
El directorio para instalar los archivos de documentación (distintos de Info) de este paquete. Por defecto debería ser /usr/local/share/doc/yourpkg, pero se escribe como $(datarootdir)/doc/yourpkg. (Si usa Autoconf, escríbalo como «@docdir@».) El subdirectorio yourpkg (que puede incluir un número de versión) evita las colisiones entre archivos con nombres comunes, como README.
El directorio para instalar los archivos Info de este paquete. Por defecto debería ser /usr/local/share/info, pero se escribe como $(datarootdir)/info. (Si usa Autoconf, escríbalo como «@infodir@».) infodir está separado de docdir por compatibilidad con la práctica existente.
Directorios para instalar los archivos de documentación en el formato concreto correspondiente. Por defecto, todos deberían establecerse en $(docdir). (Si usa Autoconf, escríbalos como «@htmldir@», «@dvidir@», etc.) Los paquetes que ofrezcan varias traducciones de su documentación deberían instalarlas en «$(htmldir)/»ll, «$(pdfdir)/»ll, etc., donde ll es una abreviatura de localización (locale) como «en» o «pt_BR».
El directorio para los archivos objeto y las bibliotecas de código objeto. No instale ejecutables aquí; probablemente deberían ir en $(libexecdir). El valor de libdir normalmente es /usr/local/lib, pero se escribe como $(exec_prefix)/lib. (Si usa Autoconf, escríbalo como «@libdir@».)
El directorio para instalar los archivos de Emacs Lisp de este paquete. Por defecto debería ser /usr/local/share/emacs/site-lisp, pero se escribe como $(datarootdir)/emacs/site-lisp.
Si usa Autoconf, escriba el valor por defecto como «@lispdir@». Para que «@lispdir@» funcione, necesita las siguientes líneas en su archivo configure.ac:
lispdir='${datarootdir}/emacs/site-lisp'
AC_SUBST(lispdir)
El directorio para instalar los catálogos de mensajes específicos de localización (locale) de este paquete. Por defecto debería ser /usr/local/share/locale, pero se escribe como $(datarootdir)/locale. (Si usa Autoconf, escríbalo como «@localedir@».) Este directorio suele tener un subdirectorio por cada localización.
Las páginas man al estilo Unix se instalan en uno de los siguientes:
El directorio de nivel superior para instalar las páginas man (si las hay) de este paquete. Normalmente será /usr/local/share/man, pero debería escribirlo como $(datarootdir)/man. (Si usa Autoconf, escríbalo como «@mandir@».)
El directorio para instalar las páginas man de la sección 1. Se escribe como $(mandir)/man1.
El directorio para instalar las páginas man de la sección 2. Se escribe como $(mandir)/man2.
No haga que la documentación principal de ningún software GNU sea una página man. En su lugar, escriba un manual en Texinfo. Las páginas man son solo para quienes ejecutan software GNU en Unix, lo cual no es más que una aplicación secundaria.
La extensión del nombre de archivo de la página man instalada. Debería contener un punto seguido del dígito adecuado; normalmente «.1».
La extensión del nombre de archivo de las páginas man de la sección 1 instaladas.
La extensión del nombre de archivo de las páginas man de la sección 2 instaladas.
Use estos nombres en lugar de «manext» si el paquete necesita instalar páginas man en más de una sección del manual.
Y, por último, debería fijar la siguiente variable:
El directorio donde están las fuentes que se compilan. El valor de esta variable normalmente lo inserta el script de shell configure. (Si usa Autoconf, use «srcdir = @srcdir@».)
Un ejemplo:
# Common prefix for installation directories. # NOTE: This directory must exist when you start the install. prefix = /usr/local datarootdir = $(prefix)/share datadir = $(datarootdir) exec_prefix = $(prefix) # Where to put the executable for the command 'gcc'. bindir = $(exec_prefix)/bin # Where to put the directories used by the compiler. libexecdir = $(exec_prefix)/libexec # Where to put the Info files. infodir = $(datarootdir)/info
Si su programa instala un gran número de archivos en uno de los directorios estándar especificados por el usuario, podría resultar útil agruparlos en un subdirectorio propio de ese programa. Si lo hace, debería escribir la regla install de modo que cree esos subdirectorios.
No espere que el usuario incluya el nombre del subdirectorio en el valor de ninguna de las variables enumeradas arriba. La idea de disponer de un conjunto uniforme de nombres de variables para los directorios de instalación es permitir que el usuario especifique exactamente los mismos valores para varios paquetes GNU distintos. Para que esto sea útil, todos los paquetes deben estar diseñados de modo que funcionen con sensatez cuando el usuario lo haga.
A veces, puede que no todas estas variables estén implementadas en la versión actual de Autoconf y/o Automake; pero, a partir de Autoconf 2.60, creemos que todas lo están. Cuando falte alguna, las descripciones aquí sirven como especificaciones de lo que Autoconf debería implementar. Como programador, puede usar una versión de desarrollo de Autoconf o abstenerse de usar esas variables hasta que se publique una versión estable que las admita.
Todos los programas GNU deberían tener los siguientes objetivos en sus Makefiles:
Compila el programa entero. Este debería ser el objetivo por defecto. Este objetivo no necesita regenerar ningún archivo de documentación; los archivos Info normalmente deberían incluirse en la distribución, y los archivos DVI (y de otros formatos de documentación) deberían generarse solo cuando se soliciten explícitamente.
Por defecto, las reglas de Make deberían compilar y enlazar con «-g», de modo que los programas ejecutables tengan símbolos de depuración. De lo contrario, queda esencialmente indefenso ante un fallo, y a menudo no es nada fácil reproducirlo con una construcción nueva.
Compila el programa y copia los ejecutables, las bibliotecas, etc., a los nombres de archivo donde deberían residir para su uso real. Si existe una prueba sencilla para verificar que un programa se ha instalado correctamente, este objetivo debería ejecutar esa prueba.
No haga strip (eliminación de símbolos) de los ejecutables al instalarlos. Esto ayuda a una eventual depuración que pudiera necesitarse más adelante; además, hoy en día el espacio en disco es barato y los cargadores dinámicos normalmente se aseguran de que las secciones de depuración no se carguen durante la ejecución normal. Los usuarios que necesiten binarios con strip pueden invocar el objetivo install-strip para hacerlo.
Si es posible, escriba la regla del objetivo install de modo que no modifique nada en el directorio donde se construyó el programa, siempre que se acabe de hacer «make all». Esto es cómodo para construir el programa con un nombre de usuario e instalarlo con otro.
Las órdenes deberían crear todos los directorios en los que se van a instalar archivos, si aún no existen. Esto incluye los directorios especificados como valores de las variables prefix y exec_prefix, así como todos los subdirectorios que se necesiten. Una forma de hacerlo es mediante un objetivo installdirs, como se describe más abajo.
Anteponga «-» a cualquier orden que instale una página man, de modo que make ignore cualquier error. Esto es por si hay sistemas que no tienen instalado el sistema de documentación de páginas man de Unix.
La forma de instalar los archivos Info es copiarlos a $(infodir) con $(INSTALL_DATA) (consulte Variables para especificar órdenes) y, a continuación, ejecutar el programa install-info si está presente. install-info es un programa que edita el archivo dir de Info para añadir o actualizar la entrada de menú del archivo Info dado; forma parte del paquete Texinfo.
A continuación se muestra una regla de ejemplo para instalar un archivo Info que también intenta manejar algunas situaciones adicionales, como que install-info no esté presente.
do-install-info: foo.info installdirs
$(NORMAL_INSTALL)
# Prefer an info file in . to one in srcdir.
if test -f foo.info; then d=.; \
else d="$(srcdir)"; fi; \
$(INSTALL_DATA) $$d/foo.info \
"$(DESTDIR)$(infodir)/foo.info"
# Run install-info only if it exists.
# Use 'if' instead of just prepending '-' to the
# line so we notice real errors from install-info.
# Use '$(SHELL) -c' because some shells do not
# fail gracefully when there is an unknown command.
$(POST_INSTALL)
if $(SHELL) -c 'install-info --version' \
>/dev/null 2>&1; then \
install-info --dir-file="$(DESTDIR)$(infodir)/dir" \
"$(DESTDIR)$(infodir)/foo.info"; \
else true; fi
Al escribir el objetivo install, debe clasificar todas las órdenes en tres categorías: las normales, las órdenes de preinstalación (pre-installation) y las órdenes de posinstalación (post-installation). Consulte Categorías de órdenes de instalación.
Estos objetivos instalan la documentación en formatos distintos de Info; están pensados para que quien instala el paquete los invoque explícitamente, si desea ese formato. GNU prefiere los archivos Info, así que estos deben instalarse mediante el objetivo install.
Cuando tenga muchos archivos de documentación que instalar, recomendamos que evite las colisiones y el desorden disponiendo que estos objetivos instalen en subdirectorios del directorio de instalación apropiado, como htmldir. Por ejemplo, si su paquete tiene varios manuales y desea instalar documentación HTML con muchos archivos (como la del modo «dividido» que produce makeinfo --html), seguramente querrá usar subdirectorios; de lo contrario, dos nodos con el mismo nombre en manuales distintos se sobrescribirían mutuamente.
Haga que estos objetivos install-format invoquen las órdenes del objetivo format, por ejemplo, haciendo de format un prerrequisito.
Elimina todos los archivos instalados, es decir, las copias que crean los objetivos «install» e «install-*».
Esta regla no debería modificar los directorios donde se realiza la compilación, sino solo los directorios donde se instalan los archivos.
Las órdenes de desinstalación se clasifican en tres categorías, igual que las órdenes de instalación. Consulte Categorías de órdenes de instalación.
Como install, pero haciendo strip de los archivos ejecutables al instalarlos. En los casos sencillos, este objetivo puede usar el objetivo install de forma sencilla:
install-strip:
$(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
install
Pero si el paquete instala scripts además de ejecutables reales, el objetivo install-strip no puede limitarse a referirse al objetivo install: tiene que hacer strip de los ejecutables pero no de los scripts.
install-strip no debería hacer strip de los ejecutables en el directorio de construcción que se copian para la instalación. Solo debería hacer strip de las copias que se instalan.
Normalmente no recomendamos hacer strip de un ejecutable a menos que esté seguro de que el programa no tiene errores. No obstante, puede ser razonable instalar un ejecutable con strip para la ejecución real mientras se guarda el ejecutable sin strip en otro lugar, por si hay un error.
Elimina todos los archivos del directorio actual que normalmente se crean al construir el programa. También elimina archivos en otros directorios si los crea este makefile. Sin embargo, no elimine los archivos que registran la configuración. Conserve también los archivos que podrían generarse mediante la construcción, pero que normalmente no se generan porque la distribución ya los incluye. No hay necesidad de eliminar los directorios padre creados con «mkdir -p», ya que podrían haber existido de todos modos.
Elimine aquí los archivos .dvi si no forman parte de la distribución.
Elimina todos los archivos del directorio actual (o creados por este makefile) que se crean al configurar o construir el programa. Si ha desempaquetado las fuentes y ha construido el programa sin crear ningún otro archivo, «make distclean» debería dejar únicamente los archivos que estaban en la distribución. No obstante, no hay necesidad de eliminar los directorios padre creados con «mkdir -p», ya que podrían haber existido de todos modos.
Como «clean», pero puede abstenerse de eliminar unos pocos archivos que la gente normalmente no quiere recompilar. Por ejemplo, el objetivo «mostlyclean» de GCC no elimina libgcc.a, porque recompilarlo rara vez es necesario y lleva mucho tiempo.
Elimina casi todo lo que pueda reconstruirse con este Makefile. Esto incluye normalmente todo lo que elimina distclean, más cosas adicionales: los archivos fuente en C generados por Bison, las tablas de tags, los archivos Info, etc.
Decimos «casi todo» por una razón: ejecutar la orden «make maintainer-clean» no debería eliminar configure, aunque configure pueda regenerarse mediante una regla del Makefile. Más en general, «make maintainer-clean» no debería eliminar nada que deba existir para poder ejecutar configure y luego empezar a construir el programa. Tampoco hay necesidad de eliminar los directorios padre creados con «mkdir -p», ya que podrían haber existido de todos modos. Estas son las únicas excepciones; maintainer-clean debería eliminar todo lo demás que pueda reconstruirse.
El objetivo «maintainer-clean» está pensado para que lo use el mantenedor (maintainer) del paquete, no los usuarios corrientes. Podría necesitar herramientas especiales para reconstruir algunos de los archivos que elimina «make maintainer-clean». Como estos archivos normalmente se incluyen en la distribución, no nos preocupamos de que sean fáciles de reconstruir. Si descubre que necesita volver a desempaquetar la distribución completa, no nos eche la culpa.
Para que los usuarios sean conscientes de esto, las órdenes del objetivo especial maintainer-clean deberían empezar con estas dos:
@echo 'This command is intended for maintainers to use; it' @echo 'deletes files that may need special tools to rebuild.'
Actualiza una tabla de tags para este programa.
Genera los archivos Info necesarios. La mejor manera de escribir las reglas es la siguiente:
info: foo.info
foo.info: foo.texi chap1.texi chap2.texi
$(MAKEINFO) $(srcdir)/foo.texi
Debe definir la variable MAKEINFO en el Makefile. Debería ejecutar el programa makeinfo, que forma parte de la distribución de Texinfo.
Normalmente una distribución de GNU viene con archivos Info, lo que significa que los archivos Info están presentes en el directorio fuente. Por tanto, la regla de Make para un archivo Info debería actualizarlo en el directorio fuente. Cuando los usuarios construyen el paquete, lo habitual es que Make no actualice los archivos Info, porque ya estarán al día.
Genera los archivos de documentación en el formato dado. Estos objetivos deberían existir siempre, pero cualquiera de ellos (o todos) puede no hacer nada (no-op) si el formato de salida dado no puede generarse. Estos objetivos no deberían ser prerrequisitos del objetivo all; el usuario debe invocarlos manualmente.
Aquí tiene una regla de ejemplo para generar archivos DVI a partir de Texinfo:
dvi: foo.dvi
foo.dvi: foo.texi chap1.texi chap2.texi
$(TEXI2DVI) $(srcdir)/foo.texi
Debe definir la variable TEXI2DVI en el Makefile. Debería ejecutar el programa texi2dvi, que forma parte de la distribución de Texinfo. (texi2dvi usa TeX para hacer el trabajo real de composición. TeX no se distribuye con Texinfo.) Como alternativa, escriba solo los prerrequisitos y deje que GNU make proporcione la orden.
Aquí tiene otro ejemplo, este para generar HTML a partir de Texinfo:
html: foo.html
foo.html: foo.texi chap1.texi chap2.texi
$(TEXI2HTML) $(srcdir)/foo.texi
De nuevo, definiría la variable TEXI2HTML en el Makefile; por ejemplo, podría ejecutar makeinfo --no-split --html (makeinfo forma parte de la distribución de Texinfo).
Crea un archivo tar de distribución para este programa. El archivo tar debería disponerse de modo que los nombres de archivo dentro de él empiecen por el nombre de un subdirectorio que sea el nombre del paquete del que es distribución. Este nombre puede incluir el número de versión.
Por ejemplo, el archivo tar de distribución de GCC versión 1.40 se desempaqueta en un subdirectorio llamado gcc-1.40.
La manera más fácil de hacerlo es crear un subdirectorio con el nombre adecuado, usar ln o cp para instalar en él los archivos pertinentes y, luego, empaquetar ese subdirectorio con tar.
Comprima el archivo tar con gzip. Por ejemplo, el archivo de distribución real de GCC versión 1.40 se llama gcc-1.40.tar.gz. Está bien admitir también otros formatos de compresión libres.
El objetivo dist debería depender explícitamente de todos los archivos no fuente que están en la distribución, para asegurarse de que estén al día en ella. Consulte el apartado Making Releases de GNU Coding Standards.
Realiza las autopruebas (si las hay). El usuario debe construir el programa antes de ejecutar las pruebas, pero no necesita instalarlo; debería escribir las autopruebas de modo que funcionen cuando el programa está construido pero no instalado.
Los siguientes objetivos se proponen como nombres convencionales, para los programas en los que resultan útiles.
installcheckRealiza las pruebas de instalación (si las hay). El usuario debe construir e instalar el programa antes de ejecutar las pruebas. No dé por hecho que $(bindir) está en la ruta de búsqueda.
installdirsResulta útil añadir un objetivo llamado «installdirs» para crear los directorios donde se instalan los archivos, y sus directorios padre. Hay un script llamado mkinstalldirs que es cómodo para esto; puede encontrarlo en el paquete Gnulib. Puede usar una regla como esta:
# Make sure all installation directories (e.g. $(bindir))
# actually exist by making them if necessary.
installdirs: mkinstalldirs
$(srcdir)/mkinstalldirs $(bindir) $(datadir) \
$(libdir) $(infodir) \
$(mandir)
o, si desea admitir DESTDIR (algo muy recomendable),
# Make sure all installation directories (e.g. $(bindir))
# actually exist by making them if necessary.
installdirs: mkinstalldirs
$(srcdir)/mkinstalldirs \
$(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
$(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
$(DESTDIR)$(mandir)
Esta regla no debería modificar los directorios donde se realiza la compilación. No debería hacer nada salvo crear los directorios de instalación.
Al escribir el objetivo install, debe clasificar todas las órdenes en tres categorías: las normales, las órdenes de preinstalación (pre-installation) y las órdenes de posinstalación (post-installation).
Las órdenes normales mueven los archivos a su lugar correspondiente y fijan su modo (permisos). No deben alterar ningún archivo salvo los que provienen por completo del paquete al que pertenecen.
Las órdenes de preinstalación y de posinstalación pueden alterar otros archivos; en particular, pueden editar archivos de configuración globales o bases de datos.
Las órdenes de preinstalación se ejecutan normalmente antes que las órdenes normales, y las de posinstalación se ejecutan normalmente después de las órdenes normales.
El uso más común de una orden de posinstalación es ejecutar install-info. Esto no puede hacerse con una orden normal, ya que altera un archivo (el directorio de Info) que no proviene por completo y de forma exclusiva del paquete que se instala. Es una orden de posinstalación porque necesita ejecutarse después de la orden normal que instala los archivos Info del paquete.
La mayoría de los programas no necesitan ninguna orden de preinstalación, pero disponemos de esta característica por si fuera necesaria.
Para clasificar las órdenes de la regla install en estas tres categorías, intercale entre ellas líneas de categoría (category lines). Una línea de categoría especifica la categoría de las órdenes que la siguen.
Una línea de categoría consta de una tabulación y una referencia a una variable especial de Make, más un comentario opcional al final. Hay tres variables que puede usar, una por cada categoría; el nombre de la variable especifica la categoría. Las líneas de categoría no hacen nada (no-op) en la ejecución corriente, porque estas tres variables de Make normalmente están sin definir (y no debería definirlas en el makefile).
Aquí están las tres posibles líneas de categoría, cada una con un comentario que explica lo que significa:
$(PRE_INSTALL) # Siguen órdenes de preinstalación.
$(POST_INSTALL) # Siguen órdenes de posinstalación.
$(NORMAL_INSTALL) # Siguen órdenes normales.
Si no usa una línea de categoría al principio de la regla install, todas las órdenes hasta la primera línea de categoría se clasifican como normales. Si no usa ninguna línea de categoría, todas las órdenes se clasifican como normales.
Estas son las líneas de categoría para uninstall:
$(PRE_UNINSTALL) # Siguen órdenes de predesinstalación.
$(POST_UNINSTALL) # Siguen órdenes de posdesinstalación.
$(NORMAL_UNINSTALL) # Siguen órdenes normales.
Típicamente, una orden de predesinstalación se usaría para eliminar entradas del directorio de Info.
Si el objetivo install o uninstall tiene prerrequisitos que actúan como subrutinas de la instalación, entonces debería empezar las órdenes de cada prerrequisito con una línea de categoría, y empezar también las órdenes del objetivo principal con una línea de categoría. De este modo, puede asegurar que cada orden se coloque en la categoría correcta, independientemente de cuál de los prerrequisitos se ejecute realmente.
Las órdenes de preinstalación y de posinstalación no deberían ejecutar ningún programa salvo estos:
[ basename bash cat chgrp chmod chown cmp cp dd diff echo expand expr false find getopt grep gunzip gzip hostname install install-info kill ldconfig ln ls md5sum mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee test touch true uname xargs yes
La razón para distinguir las órdenes de este modo es la creación de paquetes binarios. Típicamente, un paquete binario contiene todos los ejecutables y demás archivos que necesitan instalarse, y tiene su propio método para instalarlos; por eso no necesita ejecutar las órdenes de instalación normales. Pero instalar el paquete binario sí necesita ejecutar las órdenes de preinstalación y de posinstalación.
Los programas que crean paquetes binarios funcionan extrayendo las órdenes de preinstalación y de posinstalación. Aquí tiene una forma de extraer las órdenes de preinstalación (la opción -s de make es necesaria para silenciar los mensajes sobre la entrada en subdirectorios):
make -s -n install -o all \
PRE_INSTALL=pre-install \
POST_INSTALL=post-install \
NORMAL_INSTALL=normal-install \
| gawk -f pre-install.awk
donde el archivo pre-install.awk podría contener lo siguiente:
$0 ~ /^(normal-install|post-install)[ \t]*$/ {on = 0}
on {print $0}
$0 ~ /^pre-install[ \t]*$/ {on = 1}