4 Escritura del fichero de configuración de la instalación

A menudo, no es posible escribir cada cosa necesaria para construir una distribución a priori: puede que necesites obtener información del usuario o de su sistema para proseguir. Siempre que tal información sea simple (una lista de directorios en los que buscar cabeceras o bibliotecas de C, por ejemplo) resulta sencillo proporcionar un fichero de configuración, setup.cfg, y dejar que lo edite el usuario. Los ficheros de configuración también permiten proporcionar valores por omisión de cualquier opción de línea de órdenes que el usuario puede forzar mediante opciones en la línea de órdenes o mediante la edición de dichos ficheros..

Si las necesidades son más avanzadas, como, por ejemplo, determinar qué extensiones se han de construir dependiendo de las propiedades de la instalación del sistema, se necesita usar los servicios de ``auto-configuración'' de las Distutils. Empezaron a aparecer en la versión 0.9, pero, en el momento en que se escribe esto, no son suficientemente estables o maduras para su uso en entornos de producción.

** should reference description of distutils config files in ``Installing'' manual here **

El fichero de configuración de la instalación es un término medio entre el guion de instalación (que idealmente es transparente para el instalador²) y la línea de órdenes del guion de instalación, que queda totalmente fuera de tu control y al albedrío del instalador. De hecho, setup.cfg (y otros ficheros de configuración de Distutils presentes en el sistema final) se procesan tras el contenido del guion de instalación, pero antes de la línea de órdenes. Esto supone varias consecuencias favorables:

los instaladores pueden forzar cosas que pongas en setup.py editando setup.cfg
Puedes proporcionar valores por omisión no estándar para las opciones que no sean fáciles de incluir en setup.py
los instaladores pueden forzar cualquier cosa de setup.cfg usando las opciones de línea de órdenes de setup.py

La sintaxis básica del fichero de configuración es simple:

[orden]
opción=valor
...

donde orden es una de las órdenes de Distutils (por ejemplo, build_py o install) y opción es una de las opciones válidas para dicha orden. En el fichero se puede proporcionar cualquier número de opciones para cada orden y se puede incluir cualquier número de secciones de orden. Se pasan por alto las líneas en blanco y los comentarios (desde el carácter # hasta el fin de la línea). Se puede dividir los valores de opciones largos sangrando las líneas posteriores a la primera.

Se puede obtener la lista de opciones válidas para una orden particular con la opción universal --help (ayuda), por ejemplo:

> python setup.py --help build_ext
[...]
Options for 'build_ext' command:
  --build-lib (-b)     directory for compiled extension modules
  --build-temp (-t)    directory for temporary files (build by-products)
  --inplace (-i)       ignore build-lib and put compiled extensions into the
                       source directory alongside your pure Python modules
  --include-dirs (-I)  list of directories to search for header files
  --define (-D)        C preprocessor macros to define
  --undef (-U)         C preprocessor macros to undefine
[...]

o consultando la sección de este documento (la referencia de órdenes).

Observa que una opción que se escriba --pis-pas en la línea de órdenes se escribe pis_pas en los ficheros de configuración.

Supón, por ejemplo, que quieres que las extensiones se compilen ``en el sitio'': Hay una extensión pkg.ext y quieres que el fichero de la extensión compilada, ext.so en Unix, se genere en el mismo directorio de fuentes que los módulos de Python puro pkg.mod1 y pkg.mod2. Siempre puedes usar la opción --inplace de la línea de órdenes para asegurarlo:

python setup.py build_ext --inplace

Pero esto exige que se especifique siempre la orden build_ext y recordar proporcionar --inplace. Es más sencillo ``ajustar y olvidar'' esta opción incluyéndola en setup.cfg, el fichero de configuración de esta distribución:

[build_ext]
inplace=1

Esto afectará a todas las compilaciones de esta distribución de módulos, tanto si especificas build_ext como si no. Si incluyes setup.cfg en la distribución de fuentes, también afectará a las compilaciones del usuario final, lo que puede no resultar adecuado para esta opción, ya que compilar siempre ``en el sitio'' las extensiones dañaría la instalación de distribución de módulos. En ciertos casos concretos, sin embargo, se construyen en su mismo directorio de instalación, así que es una posibilidad que puede resultar útil (distribuir extensiones que se han de compilar en el directorio de instalación casi siempre es inconveniente, sin embargo).

Otro ejemplo: ciertas órdenes requieren muchas opciones que no cambian de una ejecución a la siguiente, por ejemplo, bdist_rpm requiere todo lo necesario para generar un fichero spec para generar una distribución RPM. Parte de esta información viene del guion de instalación y parte es generada automáticamente por las Distutils (la lista de ficheros instalados, por ejemplo). Sin embargo, otra parte debe ser proporcionada en forma de opciones de bdist_rpm, tediosas de repetir en la línea de órdenes para cada ejecución. Por ello, he aquí un fragmento del propio setup.cfg de las Distutils:

[bdist_rpm]
release = 1
packager = Greg Ward <gward@python.net>
doc_files = CHANGES.txt
            README.txt
            USAGE.txt
            doc/
            examples/

Observa que la opción doc_files es simplemente una ristra de cadenas separadas por blancos, dividida en múltiples líneas para favorecer la legibilidad.

Notas al pie

... instalador ²: Este ideal no se logrará, probablemente, hasta que las Distutils den servicio de auto-configuración completo.

Ver Sobre este documento... para obtener información sobre sugerencias.