This document describes the setup.cfg, a ini-like file used by Distutils2 to replace the setup.py file.
Each section contains a description of its options.
The sections are:
Contains global options for Distutils2. This section is shared with Distutils1 (legacy version distributed in python 2.X standard library).
commands: Defined Distutils2 command. A command is defined by its fully qualified name.
Examples:
[global]
commands =
package.sdist.CustomSdistCommand
*optional *multi
compilers: Defined Distutils2 compiler. A compiler is defined by its fully qualified name.
Example:
[global]
compiler =
package.compiler.CustomCCompiler
*optional *multi
setup_hook: defines a callable that will be called right after the 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 =
distutils2.tests.test_config.hook
The metadata section contains the metadata for the project as described in PEP 345.
Note
Field names are case-insensitive.
Fields:
Example:
[metadata]
name = pypi2rpm
version = 0.1
author = Tarek Ziade
author-email = tarek@ziade.org
summary = Script that transforms a sdist archive into a rpm archive
description-file = README
home-page = http://bitbucket.org/tarek/pypi2rpm
project-url: RSS feed, https://bitbucket.org/tarek/pypi2rpm/rss
classifier = Development Status :: 3 - Alpha
License :: OSI Approved :: Mozilla Public License 1.1 (MPL 1.1)
Note
Some metadata fields seen in PEP 345 are automatically generated (for instance Metadata-Version value).
This section describes the files included in the project.
Example:
[files]
packages_root = src
packages =
pypi2rpm
pypi2rpm.command
scripts =
pypi2rpm/pypi2rpm.py
extra_files =
setup.py
README
Note
In Distutils2, setup.cfg will be implicitly included.
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
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.
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 an example
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}
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 file section will be:
[files]
resources =
doc/* = {doc}
doc/RELEASES =
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 a separator to split the source in prefix suffix. The supported separator are :
- Whitespace
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 theses 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 theses 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
Warning
This part is intended for system administrator or packager.
The real paths of categories are registered in the sysconfig.cfg file installed in your python installation. The format of this file is INI-like. 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 one...
Standard categories’s paths are platform independent, they generally refers to other categories, which are platform dependent. Sysconfig module 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
Note
These examples are incremental but works unitarily.
Source tree:
babar-1.0/
README
babar.sh
launch.sh
babar.py
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.
Source tree:
babar-1.1/
README
scripts/
babar.sh
launch.sh
LAUNCH
babar.py
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 bash scripts into {scripts} instead of {scripts}/scripts.
Now let’s add some docs.
Source tree:
babar-1.2/
README
scripts/
babar.sh
launch.sh
LAUNCH
docs/
api
man
babar.py
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.
Source tree:
babar-1.3/
README
doc/
api
man
scripts/
babar.sh
launch.sh
babar.bat
launch.bat
LAUNCH
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 bash and batch scripts into {scripts} category.
Warning
In Distutils2, setup.py and README (or README.txt) files are not more included in source distribution by default
Each Distutils2 command can have its own user options defined in setup.cfg
Example:
[sdist]
manifest-builders = package.module.Maker
To override the build class in order to generate Python3 code from your Python2 base:
[build_py]
use-2to3 = True