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

Nota:

  This document is being retained solely until the "setuptools"
  documentation at
  https://setuptools.readthedocs.io/en/latest/setuptools.html
  independently covers all of the relevant information currently
  included here.

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 ]-

[1] Es probable que este ideal no se logre hasta que la configuración
    automática sea completamente admitida por *Distutils*.
