mirror of https://github.com/python/cpython
649 lines
15 KiB
ReStructuredText
649 lines
15 KiB
ReStructuredText
.. highlightlang:: cfg
|
|
|
|
*******************************************
|
|
Specification of the :file:`setup.cfg` file
|
|
*******************************************
|
|
|
|
.. :version: 1.0
|
|
|
|
This document describes the :file:`setup.cfg`, an ini-style configuration file
|
|
(compatible with :class:`configparser.RawConfigParser`) configuration file used
|
|
by Packaging to replace the :file:`setup.py` file.
|
|
|
|
Each section contains a description of its options.
|
|
|
|
- Options that are marked *multi* can have multiple values, one value per
|
|
line.
|
|
- Options that are marked *optional* can be omitted.
|
|
- Options that are marked *environ* can use environment markers, as described
|
|
in :PEP:`345`.
|
|
|
|
|
|
The sections are:
|
|
|
|
global
|
|
Global options not related to one command.
|
|
|
|
metadata
|
|
Name, version and other information defined by :PEP:`345`.
|
|
|
|
files
|
|
Modules, scripts, data, documentation and other files to include in the
|
|
distribution.
|
|
|
|
command sections
|
|
Options given for specific commands, identical to those that can be given
|
|
on the command line.
|
|
|
|
|
|
Global options
|
|
==============
|
|
|
|
Contains global options for Packaging. This section is shared with Distutils.
|
|
|
|
|
|
commands
|
|
Defined Packaging command. A command is defined by its fully
|
|
qualified name. *optional*, *multi*
|
|
|
|
Examples::
|
|
|
|
[global]
|
|
commands =
|
|
package.setup.CustomSdistCommand
|
|
package.setup.BdistDeb
|
|
|
|
compilers
|
|
Defined Packaging compiler. A compiler is defined by its fully
|
|
qualified name. *optional*, *multi*
|
|
|
|
Example::
|
|
|
|
[global]
|
|
compilers =
|
|
hotcompiler.SmartCCompiler
|
|
|
|
setup_hook
|
|
defines a callable that will be called right after the
|
|
:file:`setup.cfg` file is read. The callable receives the configuration
|
|
in form of a mapping and can make some changes to it. *optional*
|
|
|
|
Example::
|
|
|
|
[global]
|
|
setup_hook = package.setup.customize_dist
|
|
|
|
|
|
Metadata
|
|
========
|
|
|
|
The metadata section contains the metadata for the project as described in
|
|
:PEP:`345`. Field names are case-insensitive.
|
|
|
|
Fields:
|
|
|
|
name
|
|
Name of the project.
|
|
|
|
version
|
|
Version of the project. Must comply with :PEP:`386`.
|
|
|
|
platform
|
|
Platform specification describing an operating system
|
|
supported by the distribution which is not listed in the "Operating System"
|
|
Trove classifiers (:PEP:`301`). *optional*, *multi*
|
|
|
|
supported-platform
|
|
Binary distributions containing a PKG-INFO file will
|
|
use the Supported-Platform field in their metadata to specify the OS and
|
|
CPU for which the binary distribution was compiled. The semantics of
|
|
the Supported-Platform field are free form. *optional*, *multi*
|
|
|
|
summary
|
|
A one-line summary of what the distribution does.
|
|
(Used to be called *description* in Distutils1.)
|
|
|
|
description
|
|
A longer description. (Used to be called *long_description*
|
|
in Distutils1.) A file can be provided in the *description-file* field.
|
|
*optional*
|
|
|
|
description-file
|
|
path to a text file that will be used for the
|
|
**description** field. *optional*
|
|
|
|
keywords
|
|
A list of additional keywords to be used to assist searching
|
|
for the distribution in a larger catalog. Comma or space-separated.
|
|
*optional*
|
|
|
|
home-page
|
|
The URL for the distribution's home page.
|
|
|
|
download-url
|
|
The URL from which this version of the distribution
|
|
can be downloaded. *optional*
|
|
|
|
author
|
|
Author's name. *optional*
|
|
|
|
author-email
|
|
Author's e-mail. *optional*
|
|
|
|
maintainer
|
|
Maintainer's name. *optional*
|
|
|
|
maintainer-email
|
|
Maintainer's e-mail. *optional*
|
|
|
|
license
|
|
A text indicating the term of uses, when a trove classifier does
|
|
not match. *optional*.
|
|
|
|
classifiers
|
|
Classification for the distribution, as described in PEP 301.
|
|
*optional*, *multi*, *environ*
|
|
|
|
requires-dist
|
|
name of another packaging project required as a dependency.
|
|
The format is *name (version)* where version is an optional
|
|
version declaration, as described in PEP 345. *optional*, *multi*, *environ*
|
|
|
|
provides-dist
|
|
name of another packaging project contained within this
|
|
distribution. Same format than *requires-dist*. *optional*, *multi*,
|
|
*environ*
|
|
|
|
obsoletes-dist
|
|
name of another packaging project this version obsoletes.
|
|
Same format than *requires-dist*. *optional*, *multi*, *environ*
|
|
|
|
requires-python
|
|
Specifies the Python version the distribution requires.
|
|
The value is a version number, as described in PEP 345.
|
|
*optional*, *multi*, *environ*
|
|
|
|
requires-externals
|
|
a dependency in the system. This field is free-form,
|
|
and just a hint for downstream maintainers. *optional*, *multi*,
|
|
*environ*
|
|
|
|
project-url
|
|
A label, followed by a browsable URL for the project.
|
|
"label, url". The label is limited to 32 signs. *optional*, *multi*
|
|
|
|
|
|
Example::
|
|
|
|
[metadata]
|
|
name = pypi2rpm
|
|
version = 0.1
|
|
author = Tarek Ziadé
|
|
author-email = tarek@ziade.org
|
|
summary = Script that transforms an sdist archive into a RPM package
|
|
description-file = README
|
|
home-page = http://bitbucket.org/tarek/pypi2rpm/wiki/Home
|
|
project-url:
|
|
Repository, http://bitbucket.org/tarek/pypi2rpm/
|
|
RSS feed, https://bitbucket.org/tarek/pypi2rpm/rss
|
|
classifier =
|
|
Development Status :: 3 - Alpha
|
|
License :: OSI Approved :: Mozilla Public License 1.1 (MPL 1.1)
|
|
|
|
You should not give any explicit value for metadata-version: it will be guessed
|
|
from the fields present in the file.
|
|
|
|
|
|
Files
|
|
=====
|
|
|
|
This section describes the files included in the project.
|
|
|
|
packages_root
|
|
the root directory containing all packages and modules
|
|
(default: current directory). *optional*
|
|
|
|
packages
|
|
a list of packages the project includes *optional*, *multi*
|
|
|
|
modules
|
|
a list of packages the project includes *optional*, *multi*
|
|
|
|
scripts
|
|
a list of scripts the project includes *optional*, *multi*
|
|
|
|
extra_files
|
|
a list of patterns to include extra files *optional*,
|
|
*multi*
|
|
|
|
Example::
|
|
|
|
[files]
|
|
packages_root = src
|
|
packages =
|
|
pypi2rpm
|
|
pypi2rpm.command
|
|
|
|
scripts =
|
|
pypi2rpm/pypi2rpm.py
|
|
|
|
extra_files =
|
|
setup.py
|
|
README
|
|
|
|
|
|
.. Note::
|
|
The :file:`setup.cfg` configuration file is included by default. Contrary to
|
|
Distutils, :file:`README` (or :file:`README.txt`) and :file:`setup.py` are
|
|
not included by default.
|
|
|
|
|
|
Resources
|
|
---------
|
|
|
|
This section describes the files used by the project which must not be installed
|
|
in the same place that python modules or libraries, they are called
|
|
**resources**. They are for example documentation files, script files,
|
|
databases, etc...
|
|
|
|
For declaring resources, you must use this notation::
|
|
|
|
source = destination
|
|
|
|
Data-files are declared in the **resources** field in the **file** section, for
|
|
example::
|
|
|
|
[files]
|
|
resources =
|
|
source1 = destination1
|
|
source2 = destination2
|
|
|
|
The **source** part of the declaration are relative paths of resources files
|
|
(using unix path separator **/**). For example, if you've this source tree::
|
|
|
|
foo/
|
|
doc/
|
|
doc.man
|
|
scripts/
|
|
foo.sh
|
|
|
|
Your setup.cfg will look like::
|
|
|
|
[files]
|
|
resources =
|
|
doc/doc.man = destination_doc
|
|
scripts/foo.sh = destination_scripts
|
|
|
|
The final paths where files will be placed are composed by : **source** +
|
|
**destination**. In the previous example, **doc/doc.man** will be placed in
|
|
**destination_doc/doc/doc.man** and **scripts/foo.sh** will be placed in
|
|
**destination_scripts/scripts/foo.sh**. (If you want more control on the final
|
|
path, take a look at base_prefix_).
|
|
|
|
The **destination** part of resources declaration are paths with categories.
|
|
Indeed, it's generally a bad idea to give absolute path as it will be cross
|
|
incompatible. So, you must use resources categories in your **destination**
|
|
declaration. Categories will be replaced by their real path at the installation
|
|
time. Using categories is all benefit, your declaration will be simpler, cross
|
|
platform and it will allow packager to place resources files where they want
|
|
without breaking your code.
|
|
|
|
Categories can be specified by using this syntax::
|
|
|
|
{category}
|
|
|
|
Default categories are:
|
|
|
|
* config
|
|
* appdata
|
|
* appdata.arch
|
|
* appdata.persistent
|
|
* appdata.disposable
|
|
* help
|
|
* icon
|
|
* scripts
|
|
* doc
|
|
* info
|
|
* man
|
|
|
|
A special category also exists **{distribution.name}** that will be replaced by
|
|
the name of the distribution, but as most of the defaults categories use them,
|
|
so it's not necessary to add **{distribution.name}** into your destination.
|
|
|
|
If you use categories in your declarations, and you are encouraged to do, final
|
|
path will be::
|
|
|
|
source + destination_expanded
|
|
|
|
.. _example_final_path:
|
|
|
|
For example, if you have this setup.cfg::
|
|
|
|
[metadata]
|
|
name = foo
|
|
|
|
[files]
|
|
resources =
|
|
doc/doc.man = {doc}
|
|
|
|
And if **{doc}** is replaced by **{datadir}/doc/{distribution.name}**, final
|
|
path will be::
|
|
|
|
{datadir}/doc/foo/doc/doc.man
|
|
|
|
Where {datafir} category will be platform-dependent.
|
|
|
|
|
|
More control on source part
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Glob syntax
|
|
"""""""""""
|
|
|
|
When you declare source file, you can use a glob-like syntax to match multiples file, for example::
|
|
|
|
scripts/* = {script}
|
|
|
|
Will match all the files in the scripts directory and placed them in the script category.
|
|
|
|
Glob tokens are:
|
|
|
|
* ``*``: match all files.
|
|
* ``?``: match any character.
|
|
* ``**``: match any level of tree recursion (even 0).
|
|
* ``{}``: will match any part separated by comma (example: ``{sh,bat}``).
|
|
|
|
.. TODO Add examples
|
|
|
|
Order of declaration
|
|
""""""""""""""""""""
|
|
|
|
The order of declaration is important if one file match multiple rules. The last
|
|
rules matched by file is used, this is useful if you have this source tree::
|
|
|
|
foo/
|
|
doc/
|
|
index.rst
|
|
setup.rst
|
|
documentation.txt
|
|
doc.tex
|
|
README
|
|
|
|
And you want all the files in the doc directory to be placed in {doc} category,
|
|
but README must be placed in {help} category, instead of listing all the files
|
|
one by one, you can declare them in this way::
|
|
|
|
[files]
|
|
resources =
|
|
doc/* = {doc}
|
|
doc/README = {help}
|
|
|
|
Exclude
|
|
"""""""
|
|
|
|
You can exclude some files of resources declaration by giving no destination, it
|
|
can be useful if you have a non-resources file in the same directory of
|
|
resources files::
|
|
|
|
foo/
|
|
doc/
|
|
RELEASES
|
|
doc.tex
|
|
documentation.txt
|
|
docu.rst
|
|
|
|
Your **files** section will be::
|
|
|
|
[files]
|
|
resources =
|
|
doc/* = {doc}
|
|
doc/RELEASES =
|
|
|
|
More control on destination part
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. _base_prefix:
|
|
|
|
Defining a base prefix
|
|
""""""""""""""""""""""
|
|
|
|
When you define your resources, you can have more control of how the final path
|
|
is compute.
|
|
|
|
By default, the final path is::
|
|
|
|
destination + source
|
|
|
|
This can generate long paths, for example (example_final_path_)::
|
|
|
|
{datadir}/doc/foo/doc/doc.man
|
|
|
|
When you declare your source, you can use whitespace to split the source in
|
|
**prefix** **suffix**. So, for example, if you have this source::
|
|
|
|
docs/ doc.man
|
|
|
|
The **prefix** is "docs/" and the **suffix** is "doc.html".
|
|
|
|
.. note::
|
|
|
|
Separator can be placed after a path separator or replace it. So these two
|
|
sources are equivalent::
|
|
|
|
docs/ doc.man
|
|
docs doc.man
|
|
|
|
.. note::
|
|
|
|
Glob syntax is working the same way with standard source and splitted source.
|
|
So these rules::
|
|
|
|
docs/*
|
|
docs/ *
|
|
docs *
|
|
|
|
Will match all the files in the docs directory.
|
|
|
|
When you use splitted source, the final path is compute in this way::
|
|
|
|
destination + prefix
|
|
|
|
So for example, if you have this setup.cfg::
|
|
|
|
[metadata]
|
|
name = foo
|
|
|
|
[files]
|
|
resources =
|
|
doc/ doc.man = {doc}
|
|
|
|
And if **{doc}** is replaced by **{datadir}/doc/{distribution.name}**, final
|
|
path will be::
|
|
|
|
{datadir}/doc/foo/doc.man
|
|
|
|
|
|
Overwriting paths for categories
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
This part is intended for system administrators or downstream OS packagers.
|
|
|
|
The real paths of categories are registered in the *sysconfig.cfg* file
|
|
installed in your python installation. This file uses an ini format too.
|
|
The content of the file is organized into several sections:
|
|
|
|
* globals: Standard categories's paths.
|
|
* posix_prefix: Standard paths for categories and installation paths for posix
|
|
system.
|
|
* other ones XXX
|
|
|
|
Standard categories paths are platform independent, they generally refers to
|
|
other categories, which are platform dependent. :mod:`sysconfig` will choose
|
|
these category from sections matching os.name. For example::
|
|
|
|
doc = {datadir}/doc/{distribution.name}
|
|
|
|
It refers to datadir category, which can be different between platforms. In
|
|
posix system, it may be::
|
|
|
|
datadir = /usr/share
|
|
|
|
So the final path will be::
|
|
|
|
doc = /usr/share/doc/{distribution.name}
|
|
|
|
The platform-dependent categories are:
|
|
|
|
* confdir
|
|
* datadir
|
|
* libdir
|
|
* base
|
|
|
|
|
|
Defining extra categories
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. TODO
|
|
|
|
|
|
Examples
|
|
^^^^^^^^
|
|
|
|
These examples are incremental but work unitarily.
|
|
|
|
Resources in root dir
|
|
"""""""""""""""""""""
|
|
|
|
Source tree::
|
|
|
|
babar-1.0/
|
|
README
|
|
babar.sh
|
|
launch.sh
|
|
babar.py
|
|
|
|
:file:`setup.cfg`::
|
|
|
|
[files]
|
|
resources =
|
|
README = {doc}
|
|
*.sh = {scripts}
|
|
|
|
So babar.sh and launch.sh will be placed in {scripts} directory.
|
|
|
|
Now let's move all the scripts into a scripts directory.
|
|
|
|
Resources in sub-directory
|
|
""""""""""""""""""""""""""
|
|
|
|
Source tree::
|
|
|
|
babar-1.1/
|
|
README
|
|
scripts/
|
|
babar.sh
|
|
launch.sh
|
|
LAUNCH
|
|
babar.py
|
|
|
|
:file:`setup.cfg`::
|
|
|
|
[files]
|
|
resources =
|
|
README = {doc}
|
|
scripts/ LAUNCH = {doc}
|
|
scripts/ *.sh = {scripts}
|
|
|
|
It's important to use the separator after scripts/ to install all the shell
|
|
scripts into {scripts} instead of {scripts}/scripts.
|
|
|
|
Now let's add some docs.
|
|
|
|
Resources in multiple sub-directories
|
|
"""""""""""""""""""""""""""""""""""""
|
|
|
|
Source tree::
|
|
|
|
babar-1.2/
|
|
README
|
|
scripts/
|
|
babar.sh
|
|
launch.sh
|
|
LAUNCH
|
|
docs/
|
|
api
|
|
man
|
|
babar.py
|
|
|
|
:file:`setup.cfg`::
|
|
|
|
[files]
|
|
resources =
|
|
README = {doc}
|
|
scripts/ LAUNCH = {doc}
|
|
scripts/ *.sh = {scripts}
|
|
doc/ * = {doc}
|
|
doc/ man = {man}
|
|
|
|
You want to place all the file in the docs script into {doc} category, instead
|
|
of man, which must be placed into {man} category, we will use the order of
|
|
declaration of globs to choose the destination, the last glob that match the
|
|
file is used.
|
|
|
|
Now let's add some scripts for windows users.
|
|
|
|
Complete example
|
|
""""""""""""""""
|
|
|
|
Source tree::
|
|
|
|
babar-1.3/
|
|
README
|
|
doc/
|
|
api
|
|
man
|
|
scripts/
|
|
babar.sh
|
|
launch.sh
|
|
babar.bat
|
|
launch.bat
|
|
LAUNCH
|
|
|
|
:file:`setup.cfg`::
|
|
|
|
[files]
|
|
resources =
|
|
README = {doc}
|
|
scripts/ LAUNCH = {doc}
|
|
scripts/ *.{sh,bat} = {scripts}
|
|
doc/ * = {doc}
|
|
doc/ man = {man}
|
|
|
|
We use brace expansion syntax to place all the shell and batch scripts into
|
|
{scripts} category.
|
|
|
|
|
|
Command sections
|
|
================
|
|
|
|
To pass options to commands without having to type them on the command line
|
|
for each invocation, you can write them in the :file:`setup.cfg` file, in a
|
|
section named after the command. Example::
|
|
|
|
[sdist]
|
|
# special function to add custom files
|
|
manifest-builders = package.setup.list_extra_files
|
|
|
|
[build]
|
|
use-2to3 = True
|
|
|
|
[build_ext]
|
|
inplace = on
|
|
|
|
[check]
|
|
strict = on
|
|
all = on
|
|
|
|
Option values given in the configuration file can be overriden on the command
|
|
line. See :ref:`packaging-setup-config` for more information.
|