3. Escribiendo el archivo de configuración de instalación (setup)

Nota

Este documento se conserva únicamente hasta que la documentación de setuptools en https://setuptools.readthedocs.io/en/latest/setuptools.html cubra de forma independiente toda la información relevante que se incluye actualmente aquí.

A menudo, no es posible escribir todo lo necesario para construir una distribución a priori: es posible que deba obtener alguna información del usuario, o del sistema del usuario, para poder continuar. Mientras que esa información sea bastante simple —una lista de directorios para buscar archivos de encabezado de o bibliotecas, por ejemplo— proporcionar un archivo de configuración, setup.cfg, para que los usuarios lo editen es una forma fácil y barata de solicitarla. Los archivos de configuración también permiten proporcionar valores predeterminados para cualquier opción de comando, que el instalador puede invalidar en la línea de comando o editando el archivo de configuración.

La configuración del archivo de instalación (setup) es un punto medio útil entre el script de configuración— que, idealmente, sería opaco para los instaladores [1]—y la línea de comandos para el script de configuración, que está fuera de su control y depende totalmente del instalador. De hecho, setup.cfg (y cualquiera otros archivos de configuración de Distutils presentes en el sistema destino) se procesa después del contenido del script de configuración, pero antes de la línea de comandos. Esto tiene varias consecuencias útiles:

  • los instaladores pueden anular o invalidar algo que pongas en setup.py editando setup.cfg

  • puedes proporcionar valores predeterminados no estándares para las opciones que se pueden configurar fácilmente en setup.py

  • los instaladores pueden invalidar cualquier cosa en setup.cfg usando las opciones de línea de comandos para setup.py

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

[command]
option=value
...

donde command es uno de los comandos de Distutils (por ejemplo: build_py, install), y option es una de las opciones que el comando admite. Se puede proporcionar cualquier cantidad de opciones para cada comando, y se puede incluir cualquier número de secciones de comando en el archivo. Las líneas en blanco son ignoradas, al igual que los comentarios, que empiezan desde el carácter '#' hasta el final de la línea. Los valores de opción largos pueden dividirse en varias líneas simplemente indentando las líneas a continuación.

Puedes encontrar la lista de opciones admitidas por un comando particular con la opción universal --help, por ej.

$ 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
  --swig-opts          list of SWIG command line options
[...]

Tenga en cuenta que una opción escrita --foo-bar en la línea de comandos es escribe foo_bar en los archivos de configuración.

Por ejemplo, digamos que quiere que sus extensiones se construyan «en el lugar» (in-place)—esto es, tienes una extensión pkg.ext, y quieres el archivo de extensión compilado (ext.so en Unix, digamos) para ser colocado en el mismo directorio origen que los módulos de Python puro pkg.mod1 y pkg.mod2. Siempre puedes utilizar la opción --inplace en la línea de comandos para asegurarte de eso:

python setup.py build_ext --inplace

Pero esto requiere que siempre especifiques el comando build_ext explícitamente, y recuerdes proporcionarle --inplace. Una forma mas fácil es «configurar y olvidar» esta opción, poniéndolo en setup.cfg, el archivo de configuración para esta distribución:

[build_ext]
inplace=1

Esto afectará a todas las compilaciones de la distribución de este módulo, independientemente de si especificas o no explícitamente build_ext. Si incluyes setup.cfg en tu distribución de origen, también afectará las compilaciones de los usuarios finales— lo que probablemente sea una mala idea para esta opción, ya que siempre construir extensiones en el lugar interrumpiría la instalación de la distribución del módulo. En ciertos casos particulares, sin embargo, los módulos son compilados directamente en el directorio de instalación, por lo que sería una habilidad útil. (Sin embargo, distribuir extensiones que se espera que sean compiladas en su directorio de instalación es casi siempre una mala idea).

Otro ejemplo: ciertos comandos toman muchas opciones que no cambian de ejecución a ejecución; por ejemplo, bdist_rpm necesita conocer todo lo necesario para generar un archivo «spec» para crear una distribución RPM. Parte de esta información proviene del script de configuración, y otra es generada automáticamente por Distutils (como la lista de archivos instalados). Pero parte de esto tiene que ser suministrado como opciones para bdist_rpm, lo cual sería muy tedioso hacer en la línea de comandos para cada ejecución. Por lo tanto, aquí hay un fragmento del propio de Distutils setup.cfg:

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

Tenga en cuenta que la opción doc_files es simplemente una cadena de texto separada por espacios dividida en varias líneas para facilitar la lectura.

Ver también

Archivos de configuración de sintaxis en «Instalar módulos de Python»

Más información sobre los archivos de configuración está disponible en el manual para administradores del sistema.

Notas al pie