3. Writing the Setup Configuration File
***************************************

Nota:

  Este documento está siendo mantenido solamente hasta que la
  documentación de "setuptools" en
  https://setuptools.readthedocs.io/en/latest/setuptools.html cubra
  independientemente toda la información relevante actualmente
  incluida 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.

The setup configuration file is a useful middle-ground between the
setup script---which, ideally, would be opaque to installers [1]---and
the command-line to the setup script, which is outside of your control
and entirely up to the installer.  In fact, "setup.cfg" (and any other
Distutils configuration files present on the target system) are
processed after the contents of the setup script, but before the
command-line.  This has  several useful consequences:

* 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*.
