Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 1 | .. highlightlang:: cfg |
| 2 | |
Éric Araujo | 0300b5c | 2011-06-06 01:54:54 +0200 | [diff] [blame] | 3 | .. _setupcfg-spec: |
Éric Araujo | 823759e | 2011-06-04 18:46:25 +0200 | [diff] [blame] | 4 | |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 5 | ******************************************* |
| 6 | Specification of the :file:`setup.cfg` file |
| 7 | ******************************************* |
| 8 | |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 9 | :version: 0.9 |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 10 | |
| 11 | This document describes the :file:`setup.cfg`, an ini-style configuration file |
Éric Araujo | ed4fd70 | 2011-06-06 02:07:24 +0200 | [diff] [blame] | 12 | used by Packaging to replace the :file:`setup.py` file used by Distutils. |
| 13 | This specification is language-agnostic, and will therefore repeat some |
| 14 | information that's already documented for Python in the |
| 15 | :class:`configparser.RawConfigParser` documentation. |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 16 | |
Éric Araujo | f0f9b22 | 2011-06-06 01:52:37 +0200 | [diff] [blame] | 17 | .. contents:: |
| 18 | :depth: 3 |
| 19 | :local: |
| 20 | |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 21 | |
| 22 | Syntax |
| 23 | ====== |
| 24 | |
Éric Araujo | ed4fd70 | 2011-06-06 02:07:24 +0200 | [diff] [blame] | 25 | The ini-style format used in the configuration file is a simple collection of |
| 26 | sections that group sets of key-value fields separated by ``=`` or ``:`` and |
| 27 | optional whitespace. Lines starting with ``#`` or ``;`` are comments and will |
| 28 | be ignored. Empty lines are also ignored. Example:: |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 29 | |
| 30 | [section1] |
| 31 | # comment |
| 32 | name = value |
| 33 | name2 = "other value" |
| 34 | |
| 35 | [section2] |
| 36 | foo = bar |
| 37 | |
| 38 | |
Éric Araujo | ed4fd70 | 2011-06-06 02:07:24 +0200 | [diff] [blame] | 39 | Parsing values |
| 40 | --------------- |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 41 | |
Éric Araujo | ed4fd70 | 2011-06-06 02:07:24 +0200 | [diff] [blame] | 42 | Here are a set of rules to parse values: |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 43 | |
Éric Araujo | ed4fd70 | 2011-06-06 02:07:24 +0200 | [diff] [blame] | 44 | - If a value is quoted with ``"`` chars, it's a string. If a quote character is |
| 45 | present in the quoted value, it can be escaped as ``\"`` or left as-is. |
| 46 | |
| 47 | - If the value is ``true``, ``t``, ``yes``, ``y`` (case-insensitive) or ``1``, |
| 48 | it's converted to the language equivalent of a ``True`` value; if it's |
| 49 | ``false``, ``f``, ``no``, ``n`` (case-insensitive) or ``0``, it's converted to |
| 50 | the equivalent of ``False``. |
| 51 | |
| 52 | - A value can contain multiple lines. When read, lines are converted into a |
| 53 | sequence of values. Each line after the first must start with a least one |
| 54 | space or tab character; this leading indentation will be stripped. |
| 55 | |
| 56 | - All other values are considered strings. |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 57 | |
| 58 | Examples:: |
| 59 | |
| 60 | [section] |
| 61 | foo = one |
| 62 | two |
| 63 | three |
| 64 | |
| 65 | bar = false |
| 66 | baz = 1.3 |
| 67 | boo = "ok" |
| 68 | beee = "wqdqw pojpj w\"ddq" |
| 69 | |
| 70 | |
| 71 | Extending files |
| 72 | --------------- |
| 73 | |
Éric Araujo | ed4fd70 | 2011-06-06 02:07:24 +0200 | [diff] [blame] | 74 | A configuration file can be extended (i.e. included) by other files. For this, |
| 75 | a ``DEFAULT`` section must contain an ``extends`` key which value points to one |
| 76 | or more files which will be merged into the current files by adding new sections |
| 77 | and fields. If a file loaded by ``extends`` contains sections or keys that |
| 78 | already exist in the original file, they will not override the previous values. |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 79 | |
Éric Araujo | 1389008 | 2011-06-06 01:58:25 +0200 | [diff] [blame] | 80 | Contents of :file:`one.cfg`:: |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 81 | |
| 82 | [section1] |
Éric Araujo | 1389008 | 2011-06-06 01:58:25 +0200 | [diff] [blame] | 83 | name = value |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 84 | |
| 85 | [section2] |
Éric Araujo | 1389008 | 2011-06-06 01:58:25 +0200 | [diff] [blame] | 86 | foo = foo from one.cfg |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 87 | |
Éric Araujo | 1389008 | 2011-06-06 01:58:25 +0200 | [diff] [blame] | 88 | Contents of :file:`two.cfg`:: |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 89 | |
| 90 | [DEFAULT] |
Éric Araujo | 1389008 | 2011-06-06 01:58:25 +0200 | [diff] [blame] | 91 | extends = one.cfg |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 92 | |
| 93 | [section2] |
Éric Araujo | 1389008 | 2011-06-06 01:58:25 +0200 | [diff] [blame] | 94 | foo = foo from two.cfg |
| 95 | baz = baz from two.cfg |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 96 | |
Éric Araujo | 1389008 | 2011-06-06 01:58:25 +0200 | [diff] [blame] | 97 | The result of parsing :file:`two.cfg` is equivalent to this file:: |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 98 | |
| 99 | [section1] |
Éric Araujo | 1389008 | 2011-06-06 01:58:25 +0200 | [diff] [blame] | 100 | name = value |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 101 | |
| 102 | [section2] |
Éric Araujo | 1389008 | 2011-06-06 01:58:25 +0200 | [diff] [blame] | 103 | foo = foo from one.cfg |
| 104 | baz = baz from two.cfg |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 105 | |
Éric Araujo | 1389008 | 2011-06-06 01:58:25 +0200 | [diff] [blame] | 106 | Example use of multi-line notation to include more than one file:: |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 107 | |
| 108 | [DEFAULT] |
Éric Araujo | 1389008 | 2011-06-06 01:58:25 +0200 | [diff] [blame] | 109 | extends = one.cfg |
| 110 | two.cfg |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 111 | |
Éric Araujo | ed4fd70 | 2011-06-06 02:07:24 +0200 | [diff] [blame] | 112 | When several files are provided, they are processed sequentially, following the |
| 113 | precedence rules explained above. This means that the list of files should go |
| 114 | from most specialized to most common. |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 115 | |
Éric Araujo | ed4fd70 | 2011-06-06 02:07:24 +0200 | [diff] [blame] | 116 | **Tools will need to provide a way to produce a merged version of the |
| 117 | file**. This will be useful to let users publish a single file. |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 118 | |
| 119 | |
| 120 | Description of sections and fields |
| 121 | ================================== |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 122 | |
| 123 | Each section contains a description of its options. |
| 124 | |
| 125 | - Options that are marked *multi* can have multiple values, one value per |
| 126 | line. |
| 127 | - Options that are marked *optional* can be omitted. |
| 128 | - Options that are marked *environ* can use environment markers, as described |
| 129 | in :PEP:`345`. |
| 130 | |
| 131 | |
| 132 | The sections are: |
| 133 | |
| 134 | global |
| 135 | Global options not related to one command. |
| 136 | |
| 137 | metadata |
| 138 | Name, version and other information defined by :PEP:`345`. |
| 139 | |
| 140 | files |
| 141 | Modules, scripts, data, documentation and other files to include in the |
| 142 | distribution. |
| 143 | |
| 144 | command sections |
| 145 | Options given for specific commands, identical to those that can be given |
| 146 | on the command line. |
| 147 | |
| 148 | |
| 149 | Global options |
| 150 | ============== |
| 151 | |
| 152 | Contains global options for Packaging. This section is shared with Distutils. |
| 153 | |
| 154 | |
| 155 | commands |
| 156 | Defined Packaging command. A command is defined by its fully |
| 157 | qualified name. *optional*, *multi* |
| 158 | |
| 159 | Examples:: |
| 160 | |
| 161 | [global] |
| 162 | commands = |
| 163 | package.setup.CustomSdistCommand |
| 164 | package.setup.BdistDeb |
| 165 | |
| 166 | compilers |
| 167 | Defined Packaging compiler. A compiler is defined by its fully |
| 168 | qualified name. *optional*, *multi* |
| 169 | |
| 170 | Example:: |
| 171 | |
| 172 | [global] |
| 173 | compilers = |
| 174 | hotcompiler.SmartCCompiler |
| 175 | |
| 176 | setup_hook |
| 177 | defines a callable that will be called right after the |
| 178 | :file:`setup.cfg` file is read. The callable receives the configuration |
| 179 | in form of a mapping and can make some changes to it. *optional* |
| 180 | |
| 181 | Example:: |
| 182 | |
| 183 | [global] |
| 184 | setup_hook = package.setup.customize_dist |
| 185 | |
| 186 | |
| 187 | Metadata |
| 188 | ======== |
| 189 | |
| 190 | The metadata section contains the metadata for the project as described in |
| 191 | :PEP:`345`. Field names are case-insensitive. |
| 192 | |
| 193 | Fields: |
| 194 | |
| 195 | name |
| 196 | Name of the project. |
| 197 | |
| 198 | version |
| 199 | Version of the project. Must comply with :PEP:`386`. |
| 200 | |
| 201 | platform |
| 202 | Platform specification describing an operating system |
| 203 | supported by the distribution which is not listed in the "Operating System" |
| 204 | Trove classifiers (:PEP:`301`). *optional*, *multi* |
| 205 | |
| 206 | supported-platform |
| 207 | Binary distributions containing a PKG-INFO file will |
| 208 | use the Supported-Platform field in their metadata to specify the OS and |
| 209 | CPU for which the binary distribution was compiled. The semantics of |
| 210 | the Supported-Platform field are free form. *optional*, *multi* |
| 211 | |
| 212 | summary |
| 213 | A one-line summary of what the distribution does. |
| 214 | (Used to be called *description* in Distutils1.) |
| 215 | |
| 216 | description |
| 217 | A longer description. (Used to be called *long_description* |
| 218 | in Distutils1.) A file can be provided in the *description-file* field. |
| 219 | *optional* |
| 220 | |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 221 | keywords |
| 222 | A list of additional keywords to be used to assist searching |
| 223 | for the distribution in a larger catalog. Comma or space-separated. |
| 224 | *optional* |
| 225 | |
| 226 | home-page |
| 227 | The URL for the distribution's home page. |
| 228 | |
| 229 | download-url |
| 230 | The URL from which this version of the distribution |
| 231 | can be downloaded. *optional* |
| 232 | |
| 233 | author |
| 234 | Author's name. *optional* |
| 235 | |
| 236 | author-email |
| 237 | Author's e-mail. *optional* |
| 238 | |
| 239 | maintainer |
| 240 | Maintainer's name. *optional* |
| 241 | |
| 242 | maintainer-email |
| 243 | Maintainer's e-mail. *optional* |
| 244 | |
| 245 | license |
| 246 | A text indicating the term of uses, when a trove classifier does |
| 247 | not match. *optional*. |
| 248 | |
| 249 | classifiers |
| 250 | Classification for the distribution, as described in PEP 301. |
| 251 | *optional*, *multi*, *environ* |
| 252 | |
| 253 | requires-dist |
| 254 | name of another packaging project required as a dependency. |
| 255 | The format is *name (version)* where version is an optional |
| 256 | version declaration, as described in PEP 345. *optional*, *multi*, *environ* |
| 257 | |
| 258 | provides-dist |
| 259 | name of another packaging project contained within this |
| 260 | distribution. Same format than *requires-dist*. *optional*, *multi*, |
| 261 | *environ* |
| 262 | |
| 263 | obsoletes-dist |
| 264 | name of another packaging project this version obsoletes. |
| 265 | Same format than *requires-dist*. *optional*, *multi*, *environ* |
| 266 | |
| 267 | requires-python |
Éric Araujo | fdeb8bf | 2011-06-06 19:57:02 +0200 | [diff] [blame] | 268 | Specifies the Python version the distribution requires. The value is a |
| 269 | comma-separated list of version predicates, as described in PEP 345. |
| 270 | *optional*, *environ* |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 271 | |
| 272 | requires-externals |
| 273 | a dependency in the system. This field is free-form, |
| 274 | and just a hint for downstream maintainers. *optional*, *multi*, |
| 275 | *environ* |
| 276 | |
| 277 | project-url |
| 278 | A label, followed by a browsable URL for the project. |
| 279 | "label, url". The label is limited to 32 signs. *optional*, *multi* |
| 280 | |
Éric Araujo | 8a4e7a9 | 2011-06-06 01:58:54 +0200 | [diff] [blame] | 281 | One extra field not present in PEP 345 is supported: |
| 282 | |
| 283 | description-file |
| 284 | Path to a text file that will be used to fill the ``description`` field. |
| 285 | ``description-file`` and ``description`` are mutually exclusive. *optional* |
| 286 | |
| 287 | |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 288 | |
| 289 | Example:: |
| 290 | |
| 291 | [metadata] |
| 292 | name = pypi2rpm |
| 293 | version = 0.1 |
| 294 | author = Tarek Ziadé |
| 295 | author-email = tarek@ziade.org |
| 296 | summary = Script that transforms an sdist archive into a RPM package |
| 297 | description-file = README |
| 298 | home-page = http://bitbucket.org/tarek/pypi2rpm/wiki/Home |
| 299 | project-url: |
| 300 | Repository, http://bitbucket.org/tarek/pypi2rpm/ |
| 301 | RSS feed, https://bitbucket.org/tarek/pypi2rpm/rss |
| 302 | classifier = |
| 303 | Development Status :: 3 - Alpha |
| 304 | License :: OSI Approved :: Mozilla Public License 1.1 (MPL 1.1) |
| 305 | |
| 306 | You should not give any explicit value for metadata-version: it will be guessed |
| 307 | from the fields present in the file. |
| 308 | |
| 309 | |
| 310 | Files |
| 311 | ===== |
| 312 | |
| 313 | This section describes the files included in the project. |
| 314 | |
| 315 | packages_root |
| 316 | the root directory containing all packages and modules |
| 317 | (default: current directory). *optional* |
| 318 | |
| 319 | packages |
| 320 | a list of packages the project includes *optional*, *multi* |
| 321 | |
| 322 | modules |
| 323 | a list of packages the project includes *optional*, *multi* |
| 324 | |
| 325 | scripts |
| 326 | a list of scripts the project includes *optional*, *multi* |
| 327 | |
| 328 | extra_files |
| 329 | a list of patterns to include extra files *optional*, |
| 330 | *multi* |
| 331 | |
| 332 | Example:: |
| 333 | |
| 334 | [files] |
| 335 | packages_root = src |
| 336 | packages = |
| 337 | pypi2rpm |
| 338 | pypi2rpm.command |
| 339 | |
| 340 | scripts = |
| 341 | pypi2rpm/pypi2rpm.py |
| 342 | |
| 343 | extra_files = |
| 344 | setup.py |
| 345 | README |
| 346 | |
| 347 | |
| 348 | .. Note:: |
| 349 | The :file:`setup.cfg` configuration file is included by default. Contrary to |
| 350 | Distutils, :file:`README` (or :file:`README.txt`) and :file:`setup.py` are |
| 351 | not included by default. |
| 352 | |
| 353 | |
| 354 | Resources |
| 355 | --------- |
| 356 | |
| 357 | This section describes the files used by the project which must not be installed |
| 358 | in the same place that python modules or libraries, they are called |
| 359 | **resources**. They are for example documentation files, script files, |
| 360 | databases, etc... |
| 361 | |
| 362 | For declaring resources, you must use this notation:: |
| 363 | |
| 364 | source = destination |
| 365 | |
| 366 | Data-files are declared in the **resources** field in the **file** section, for |
| 367 | example:: |
| 368 | |
| 369 | [files] |
| 370 | resources = |
| 371 | source1 = destination1 |
| 372 | source2 = destination2 |
| 373 | |
| 374 | The **source** part of the declaration are relative paths of resources files |
| 375 | (using unix path separator **/**). For example, if you've this source tree:: |
| 376 | |
| 377 | foo/ |
| 378 | doc/ |
| 379 | doc.man |
| 380 | scripts/ |
| 381 | foo.sh |
| 382 | |
| 383 | Your setup.cfg will look like:: |
| 384 | |
| 385 | [files] |
| 386 | resources = |
| 387 | doc/doc.man = destination_doc |
| 388 | scripts/foo.sh = destination_scripts |
| 389 | |
| 390 | The final paths where files will be placed are composed by : **source** + |
| 391 | **destination**. In the previous example, **doc/doc.man** will be placed in |
| 392 | **destination_doc/doc/doc.man** and **scripts/foo.sh** will be placed in |
| 393 | **destination_scripts/scripts/foo.sh**. (If you want more control on the final |
Éric Araujo | 0300b5c | 2011-06-06 01:54:54 +0200 | [diff] [blame] | 394 | path, take a look at :ref:`setupcfg-resources-base-prefix`). |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 395 | |
| 396 | The **destination** part of resources declaration are paths with categories. |
| 397 | Indeed, it's generally a bad idea to give absolute path as it will be cross |
| 398 | incompatible. So, you must use resources categories in your **destination** |
| 399 | declaration. Categories will be replaced by their real path at the installation |
| 400 | time. Using categories is all benefit, your declaration will be simpler, cross |
| 401 | platform and it will allow packager to place resources files where they want |
| 402 | without breaking your code. |
| 403 | |
| 404 | Categories can be specified by using this syntax:: |
| 405 | |
| 406 | {category} |
| 407 | |
| 408 | Default categories are: |
| 409 | |
| 410 | * config |
| 411 | * appdata |
| 412 | * appdata.arch |
| 413 | * appdata.persistent |
| 414 | * appdata.disposable |
| 415 | * help |
| 416 | * icon |
| 417 | * scripts |
| 418 | * doc |
| 419 | * info |
| 420 | * man |
| 421 | |
| 422 | A special category also exists **{distribution.name}** that will be replaced by |
| 423 | the name of the distribution, but as most of the defaults categories use them, |
| 424 | so it's not necessary to add **{distribution.name}** into your destination. |
| 425 | |
| 426 | If you use categories in your declarations, and you are encouraged to do, final |
| 427 | path will be:: |
| 428 | |
| 429 | source + destination_expanded |
| 430 | |
| 431 | .. _example_final_path: |
| 432 | |
| 433 | For example, if you have this setup.cfg:: |
| 434 | |
| 435 | [metadata] |
| 436 | name = foo |
| 437 | |
| 438 | [files] |
| 439 | resources = |
| 440 | doc/doc.man = {doc} |
| 441 | |
| 442 | And if **{doc}** is replaced by **{datadir}/doc/{distribution.name}**, final |
| 443 | path will be:: |
| 444 | |
| 445 | {datadir}/doc/foo/doc/doc.man |
| 446 | |
| 447 | Where {datafir} category will be platform-dependent. |
| 448 | |
| 449 | |
| 450 | More control on source part |
| 451 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 452 | |
| 453 | Glob syntax |
| 454 | """"""""""" |
| 455 | |
| 456 | When you declare source file, you can use a glob-like syntax to match multiples file, for example:: |
| 457 | |
| 458 | scripts/* = {script} |
| 459 | |
| 460 | Will match all the files in the scripts directory and placed them in the script category. |
| 461 | |
| 462 | Glob tokens are: |
| 463 | |
| 464 | * ``*``: match all files. |
| 465 | * ``?``: match any character. |
| 466 | * ``**``: match any level of tree recursion (even 0). |
| 467 | * ``{}``: will match any part separated by comma (example: ``{sh,bat}``). |
| 468 | |
| 469 | .. TODO Add examples |
| 470 | |
| 471 | Order of declaration |
| 472 | """""""""""""""""""" |
| 473 | |
| 474 | The order of declaration is important if one file match multiple rules. The last |
| 475 | rules matched by file is used, this is useful if you have this source tree:: |
| 476 | |
| 477 | foo/ |
| 478 | doc/ |
| 479 | index.rst |
| 480 | setup.rst |
| 481 | documentation.txt |
| 482 | doc.tex |
| 483 | README |
| 484 | |
| 485 | And you want all the files in the doc directory to be placed in {doc} category, |
| 486 | but README must be placed in {help} category, instead of listing all the files |
| 487 | one by one, you can declare them in this way:: |
| 488 | |
| 489 | [files] |
| 490 | resources = |
| 491 | doc/* = {doc} |
| 492 | doc/README = {help} |
| 493 | |
| 494 | Exclude |
| 495 | """"""" |
| 496 | |
| 497 | You can exclude some files of resources declaration by giving no destination, it |
| 498 | can be useful if you have a non-resources file in the same directory of |
| 499 | resources files:: |
| 500 | |
| 501 | foo/ |
| 502 | doc/ |
| 503 | RELEASES |
| 504 | doc.tex |
| 505 | documentation.txt |
| 506 | docu.rst |
| 507 | |
| 508 | Your **files** section will be:: |
| 509 | |
| 510 | [files] |
| 511 | resources = |
| 512 | doc/* = {doc} |
| 513 | doc/RELEASES = |
| 514 | |
| 515 | More control on destination part |
| 516 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 517 | |
Éric Araujo | 0300b5c | 2011-06-06 01:54:54 +0200 | [diff] [blame] | 518 | .. _setupcfg-resources-base-prefix: |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 519 | |
| 520 | Defining a base prefix |
| 521 | """""""""""""""""""""" |
| 522 | |
| 523 | When you define your resources, you can have more control of how the final path |
Éric Araujo | 60533e0 | 2011-06-06 02:00:54 +0200 | [diff] [blame] | 524 | is computed. |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 525 | |
| 526 | By default, the final path is:: |
| 527 | |
| 528 | destination + source |
| 529 | |
| 530 | This can generate long paths, for example (example_final_path_):: |
| 531 | |
| 532 | {datadir}/doc/foo/doc/doc.man |
| 533 | |
| 534 | When you declare your source, you can use whitespace to split the source in |
| 535 | **prefix** **suffix**. So, for example, if you have this source:: |
| 536 | |
| 537 | docs/ doc.man |
| 538 | |
| 539 | The **prefix** is "docs/" and the **suffix** is "doc.html". |
| 540 | |
| 541 | .. note:: |
| 542 | |
| 543 | Separator can be placed after a path separator or replace it. So these two |
| 544 | sources are equivalent:: |
| 545 | |
| 546 | docs/ doc.man |
| 547 | docs doc.man |
| 548 | |
| 549 | .. note:: |
| 550 | |
Éric Araujo | 60533e0 | 2011-06-06 02:00:54 +0200 | [diff] [blame] | 551 | Glob syntax is working the same way with standard source and split source. |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 552 | So these rules:: |
| 553 | |
| 554 | docs/* |
| 555 | docs/ * |
| 556 | docs * |
| 557 | |
| 558 | Will match all the files in the docs directory. |
| 559 | |
Éric Araujo | 60533e0 | 2011-06-06 02:00:54 +0200 | [diff] [blame] | 560 | When you use split source, the final path is computed this way:: |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 561 | |
| 562 | destination + prefix |
| 563 | |
| 564 | So for example, if you have this setup.cfg:: |
| 565 | |
| 566 | [metadata] |
| 567 | name = foo |
| 568 | |
| 569 | [files] |
| 570 | resources = |
| 571 | doc/ doc.man = {doc} |
| 572 | |
| 573 | And if **{doc}** is replaced by **{datadir}/doc/{distribution.name}**, final |
| 574 | path will be:: |
| 575 | |
| 576 | {datadir}/doc/foo/doc.man |
| 577 | |
| 578 | |
| 579 | Overwriting paths for categories |
| 580 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 581 | |
| 582 | This part is intended for system administrators or downstream OS packagers. |
| 583 | |
| 584 | The real paths of categories are registered in the *sysconfig.cfg* file |
| 585 | installed in your python installation. This file uses an ini format too. |
| 586 | The content of the file is organized into several sections: |
| 587 | |
| 588 | * globals: Standard categories's paths. |
| 589 | * posix_prefix: Standard paths for categories and installation paths for posix |
| 590 | system. |
| 591 | * other ones XXX |
| 592 | |
| 593 | Standard categories paths are platform independent, they generally refers to |
| 594 | other categories, which are platform dependent. :mod:`sysconfig` will choose |
| 595 | these category from sections matching os.name. For example:: |
| 596 | |
| 597 | doc = {datadir}/doc/{distribution.name} |
| 598 | |
| 599 | It refers to datadir category, which can be different between platforms. In |
| 600 | posix system, it may be:: |
| 601 | |
| 602 | datadir = /usr/share |
| 603 | |
| 604 | So the final path will be:: |
| 605 | |
| 606 | doc = /usr/share/doc/{distribution.name} |
| 607 | |
| 608 | The platform-dependent categories are: |
| 609 | |
| 610 | * confdir |
| 611 | * datadir |
| 612 | * libdir |
| 613 | * base |
| 614 | |
| 615 | |
| 616 | Defining extra categories |
| 617 | ^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 618 | |
| 619 | .. TODO |
| 620 | |
| 621 | |
| 622 | Examples |
| 623 | ^^^^^^^^ |
| 624 | |
| 625 | These examples are incremental but work unitarily. |
| 626 | |
| 627 | Resources in root dir |
| 628 | """"""""""""""""""""" |
| 629 | |
| 630 | Source tree:: |
| 631 | |
| 632 | babar-1.0/ |
| 633 | README |
| 634 | babar.sh |
| 635 | launch.sh |
| 636 | babar.py |
| 637 | |
| 638 | :file:`setup.cfg`:: |
| 639 | |
| 640 | [files] |
| 641 | resources = |
| 642 | README = {doc} |
| 643 | *.sh = {scripts} |
| 644 | |
| 645 | So babar.sh and launch.sh will be placed in {scripts} directory. |
| 646 | |
| 647 | Now let's move all the scripts into a scripts directory. |
| 648 | |
| 649 | Resources in sub-directory |
| 650 | """""""""""""""""""""""""" |
| 651 | |
| 652 | Source tree:: |
| 653 | |
| 654 | babar-1.1/ |
| 655 | README |
| 656 | scripts/ |
| 657 | babar.sh |
| 658 | launch.sh |
| 659 | LAUNCH |
| 660 | babar.py |
| 661 | |
| 662 | :file:`setup.cfg`:: |
| 663 | |
| 664 | [files] |
| 665 | resources = |
| 666 | README = {doc} |
| 667 | scripts/ LAUNCH = {doc} |
| 668 | scripts/ *.sh = {scripts} |
| 669 | |
| 670 | It's important to use the separator after scripts/ to install all the shell |
| 671 | scripts into {scripts} instead of {scripts}/scripts. |
| 672 | |
| 673 | Now let's add some docs. |
| 674 | |
| 675 | Resources in multiple sub-directories |
| 676 | """"""""""""""""""""""""""""""""""""" |
| 677 | |
| 678 | Source tree:: |
| 679 | |
| 680 | babar-1.2/ |
| 681 | README |
| 682 | scripts/ |
| 683 | babar.sh |
| 684 | launch.sh |
| 685 | LAUNCH |
| 686 | docs/ |
| 687 | api |
| 688 | man |
| 689 | babar.py |
| 690 | |
| 691 | :file:`setup.cfg`:: |
| 692 | |
| 693 | [files] |
| 694 | resources = |
| 695 | README = {doc} |
| 696 | scripts/ LAUNCH = {doc} |
| 697 | scripts/ *.sh = {scripts} |
| 698 | doc/ * = {doc} |
| 699 | doc/ man = {man} |
| 700 | |
| 701 | You want to place all the file in the docs script into {doc} category, instead |
| 702 | of man, which must be placed into {man} category, we will use the order of |
| 703 | declaration of globs to choose the destination, the last glob that match the |
| 704 | file is used. |
| 705 | |
| 706 | Now let's add some scripts for windows users. |
| 707 | |
| 708 | Complete example |
| 709 | """""""""""""""" |
| 710 | |
| 711 | Source tree:: |
| 712 | |
| 713 | babar-1.3/ |
| 714 | README |
| 715 | doc/ |
| 716 | api |
| 717 | man |
| 718 | scripts/ |
| 719 | babar.sh |
| 720 | launch.sh |
| 721 | babar.bat |
| 722 | launch.bat |
| 723 | LAUNCH |
| 724 | |
| 725 | :file:`setup.cfg`:: |
| 726 | |
| 727 | [files] |
| 728 | resources = |
| 729 | README = {doc} |
| 730 | scripts/ LAUNCH = {doc} |
| 731 | scripts/ *.{sh,bat} = {scripts} |
| 732 | doc/ * = {doc} |
| 733 | doc/ man = {man} |
| 734 | |
| 735 | We use brace expansion syntax to place all the shell and batch scripts into |
| 736 | {scripts} category. |
| 737 | |
| 738 | |
| 739 | Command sections |
| 740 | ================ |
| 741 | |
| 742 | To pass options to commands without having to type them on the command line |
| 743 | for each invocation, you can write them in the :file:`setup.cfg` file, in a |
| 744 | section named after the command. Example:: |
| 745 | |
| 746 | [sdist] |
| 747 | # special function to add custom files |
| 748 | manifest-builders = package.setup.list_extra_files |
| 749 | |
| 750 | [build] |
| 751 | use-2to3 = True |
| 752 | |
| 753 | [build_ext] |
| 754 | inplace = on |
| 755 | |
| 756 | [check] |
| 757 | strict = on |
| 758 | all = on |
| 759 | |
| 760 | Option values given in the configuration file can be overriden on the command |
| 761 | line. See :ref:`packaging-setup-config` for more information. |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 762 | |
| 763 | |
| 764 | Extensibility |
| 765 | ============= |
| 766 | |
Éric Araujo | 1cf8a32 | 2011-06-06 02:00:03 +0200 | [diff] [blame] | 767 | Every section can have fields that are not part of this specification. They are |
| 768 | called **extensions**. |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 769 | |
Éric Araujo | 1cf8a32 | 2011-06-06 02:00:03 +0200 | [diff] [blame] | 770 | An extension field starts with ``X-``. Example:: |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 771 | |
| 772 | [metadata] |
Éric Araujo | 1cf8a32 | 2011-06-06 02:00:03 +0200 | [diff] [blame] | 773 | name = Distribute |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 774 | X-Debian-Name = python-distribute |
| 775 | |
| 776 | |
| 777 | Changes in the specification |
| 778 | ============================ |
| 779 | |
Éric Araujo | a69ade8 | 2011-06-06 02:02:34 +0200 | [diff] [blame] | 780 | The versioning scheme for this specification is **MAJOR.MINOR**. Changes in the |
| 781 | specification will cause the version number to be updated. |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 782 | |
Éric Araujo | a69ade8 | 2011-06-06 02:02:34 +0200 | [diff] [blame] | 783 | Changes to the minor number reflect backwards-compatible changes: |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 784 | |
Éric Araujo | a69ade8 | 2011-06-06 02:02:34 +0200 | [diff] [blame] | 785 | - New fields and sections (optional or mandatory) can be added. |
| 786 | - Optional fields can be removed. |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 787 | |
Éric Araujo | a69ade8 | 2011-06-06 02:02:34 +0200 | [diff] [blame] | 788 | The major number will be incremented for backwards-incompatible changes: |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 789 | |
Éric Araujo | a69ade8 | 2011-06-06 02:02:34 +0200 | [diff] [blame] | 790 | - Mandatory fields or sections are removed. |
| 791 | - Fields change their meaning. |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 792 | |
Éric Araujo | a69ade8 | 2011-06-06 02:02:34 +0200 | [diff] [blame] | 793 | As a consequence, a tool written to consume 1.5 has these properties: |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 794 | |
Éric Araujo | a69ade8 | 2011-06-06 02:02:34 +0200 | [diff] [blame] | 795 | - Can read 1.1, 1.2 and all versions < 1.5, since the tool knows what |
| 796 | optional fields weren't there. |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 797 | |
Éric Araujo | a69ade8 | 2011-06-06 02:02:34 +0200 | [diff] [blame] | 798 | .. XXX clarify |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 799 | |
Éric Araujo | a69ade8 | 2011-06-06 02:02:34 +0200 | [diff] [blame] | 800 | - Can also read 1.6 and other 1.x versions: The tool will just ignore fields it |
| 801 | doesn't know about, even if they are mandatory in the new version. If |
| 802 | optional fields were removed, the tool will just consider them absent. |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 803 | |
Éric Araujo | a69ade8 | 2011-06-06 02:02:34 +0200 | [diff] [blame] | 804 | - Cannot read 2.x and should refuse to interpret such files. |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 805 | |
Éric Araujo | a69ade8 | 2011-06-06 02:02:34 +0200 | [diff] [blame] | 806 | A tool written to produce 1.x should have these properties: |
Éric Araujo | ba661a9 | 2011-06-04 02:31:14 +0200 | [diff] [blame] | 807 | |
Éric Araujo | a69ade8 | 2011-06-06 02:02:34 +0200 | [diff] [blame] | 808 | - Writes all mandatory fields. |
| 809 | - May write optional fields. |
Éric Araujo | 1cf8a32 | 2011-06-06 02:00:03 +0200 | [diff] [blame] | 810 | |
| 811 | |
| 812 | Acknowledgments |
| 813 | =============== |
| 814 | |
| 815 | This specification includes work and feedback from these people: |
| 816 | |
| 817 | - Tarek Ziadé |
| 818 | - Julien Jehannet |
| 819 | - Boris Feld |
| 820 | - Éric Araujo |
| 821 | |
| 822 | (If your name is missing, please :ref:`let us know <reporting-bugs>`.) |