New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Feature/distutils docs #2657
Merged
Merged
Feature/distutils docs #2657
Changes from all commits
Commits
Show all changes
403 commits
Select commit
Hold shift + click to select a range
c9a96a1
#7973: Fix distutils options spelling.
birkenfeld 2f483dd
Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,8356…
birkenfeld ed9c8fb
Merged revisions 83593 via svnmerge from
birkenfeld 39f890e
Use a marker in generated MANIFEST files, don't touch files without i…
merwok fbfa411
Merged revisions 83993 via svnmerge from
merwok 3c46db2
Fix version{added,changed} and spacing in NEWS
merwok 5d9dbc9
Merged revisions 83993 via svnmerge from
merwok 9e1e39b
Manually merge r83995: Fix version{added,changed} and spacing in NEWS
merwok 09abd84
Fix typo
merwok 74644b4
Merged revisions 84050 via svnmerge from
merwok 0e4d801
Merged revisions 84050 via svnmerge from
merwok 10cb2e2
Fix bad merge
merwok 2331bf9
Consistency check for versionadded/changed directives.
birkenfeld a2b83eb
#9911: doc copyedits.
birkenfeld a3c1f8f
#9934. Correct a typo that was already fixed on py3k.
briancurtin f109561
Merged revisions 77236,77383,77399,77857,78238,78861-78862,78958 via …
birkenfeld de2bfbd
Merged revisions 82629,82632,82724,82757-82758,82760-82763,82798-8279…
birkenfeld f078ab0
Merged revisions 82805-82806,83523-83527,83536,83538,83542,83546-8354…
birkenfeld b20a0d1
Merged revisions 84142 via svnmerge from
birkenfeld 5e92a9a
Merged revisions 84945 via svnmerge from
birkenfeld a08d7b1
Merged revisions 84945 via svnmerge from
birkenfeld e0da8b0
Migrate to Sphinx 1.0 C language constructs.
birkenfeld 8e2e84d
Fix errors found by "make suspicious".
birkenfeld d3f2167
Merged revisions 85274 via svnmerge from
birkenfeld af05960
Fix sphinx role markups.
orsenthil 5f1300d
Fix wrong name in docstring and doc (#10693). Original patch by Eli …
merwok 4c1ab89
Merged revisions 87277 via svnmerge from
merwok 42a2856
Merged revisions 87277 via svnmerge from
merwok 6e1e6d6
Add missing read() in distutils doc.
merwok 6600659
Merged revisions 88613 via svnmerge from
merwok f56d8ab
Merged revisions 88613 via svnmerge from
merwok a0b2d67
Merged revisions 88613 via svnmerge from
merwok 22d3b0e
Dummy-merge 2.6 branch into 2.7 branch.
birkenfeld 5018dbc
Dummy-merge 3.1 branch into 3.2 branch.
birkenfeld deacc91
Dummy-merge 3.2 branch into default branch.
birkenfeld 710e7b1
#11843: remove duplicate line from table in distutil doc.
ezio-melotti 7efd31f
#11843: remove duplicate line from table in distutil doc.
ezio-melotti 8889f06
#11843: Merge with 3.1.
3c53874
#11843: Merge with 3.2.
ezio-melotti 2a6a811
Fix weird executable name
merwok 32c791f
Merge 3.1
merwok e3c3a80
Merge 3.2
merwok 6d1b398
Stop trying to use _xmlplus in the xml module. Closes #11164.
loewis 4cd8b86
merge 11164
loewis b9342e2
merge 11164
loewis f56f366
Backport doc improvements for distutils.cmd.Command (#9223).
merwok 3f3344d
Minor touch-ups in distutils.cmd.Command doc
merwok d1e86e1
Re-add missing doc stub for the distutils check command
merwok 92cbe4b
Merge doc touch-ups and fixes for #9831 and #9223 from 3.1
merwok 46fe9bd
Re-add missing doc stub for the distutils check command
merwok 43183ca
Merge touch-ups and fixes for #9831 (+port fix to packaging) and #922…
merwok bc1e827
Branch merge
merwok a090aad
Merge 3.2
merwok 1147a55
Fix markup: arguments in a class directive are __init__ arguments, no…
merwok 4274c39
Fix markup: arguments in a class directive are __init__ arguments, no…
merwok c0f78eb
Merge 3.2
merwok 0bd45ca
Add documentation for the packaging module.
merwok 82e62fd
Packaging doc: Add missing index file, improve main page description.
merwok 0e80c6a
Add examples that work on Windows to distutils docs (#1626300)
merwok d35dc00
Add examples that work on Windows to distutils docs (#1626300)
merwok 85d3b07
Merge doc fixes from 3.2
merwok d37f3f9
Remove duplicate "numbered" options for toctrees.
birkenfeld 94a05c3
Better English.
bitdancer beee648
Merge English fix.
bitdancer 767cc28
Better English.
bitdancer 5f64303
Turn raw URI into real link
merwok de09587
Turn raw URI into real link
merwok 63ed5ce
Merge from 3.2 (#10318, #12255, #12043, #12417 and other fixes)
merwok ace431e
Fix regression with distutils MANIFEST handing (#11104, #8688).
merwok ad7d9f5
Fix regression with distutils MANIFEST handing (#11104, #8688).
merwok b45cc3a
Merge fixes for #9860, #11104/#8688 and #12331 from 3.2
merwok cfe933a
Merge doc changes from 3.2 (#8617, #10745).
merwok 9a88371
Remove obsolete term + indicate how to find the program (#1626300).
merwok b67f02c
Merge 3.2
merwok 0721964
Fix typo in command name
merwok 293f269
Remove obsolete term + indicate how to find the program (#1626300).
merwok 2571448
Fix typo in command name
merwok b4181ce
Merge fixes for #12256 and typos from 3.2
merwok 507f7dc
Fix type information in distutils API reference (#9302).
merwok 5fae7cd
Document the "optional" argument of distutils’ Extension class
merwok b31194b
Document the "optional" argument of distutils’ Extension class
merwok bdd8fb7
Merge from 3.2 (#9302 fix and other changes)
merwok c0e0935
Synchronize packaging docs with distutils’ (includes fix for #9302)
merwok fb19b67
Fix type information in distutils API reference (#9302).
merwok 9d4440f
Document the "optional" argument of distutils’ Extension class
merwok 5433b81
Merge with release clone.
birkenfeld b734ac1
Merge with 3.2.
birkenfeld 031fcc9
Fix distutils byte-compilation to comply with PEP 3147 (#11254).
merwok 00e06a3
Merge fixes for #10526, #10359, #11254, #9100 and the bug without number
merwok 4aae50e
Replace a mention of EnvironmentError in the distutils docs.
pitrou 242b2bd
Remove duplication.
ezio-melotti d6f3f00
Remove duplication.
ezio-melotti 5f95877
Merge with 3.2.
ezio-melotti d3e8c27
update to new C roles and directives
sandrotosi 0fc0953
Hide or remove user-visible XXX notes from distutils doc (#13716).
merwok cd43501
Merge edits from 3.2 (#13716, #1040439, #2945, #13770, #6715)
merwok b15d21c
distutils 2.7’s Extension does not support optional (#13865).
merwok 91f14ee
Hide or remove user-visible XXX notes from distutils doc (#13716).
merwok 7350073
Remove packaging from the standard library.
merwok 7cd414c
Move distutils install doc back into place.
merwok 48d6907
Adapt mentions of future changes in doc
merwok 0c3f264
Ignore .nfs* files in distutils (#7719).
merwok 95d02d4
Issue #15321: update PyPI upload doc to say --no-raw passed to rst2ht…
eliben f72e718
Issue #15231: rephrase the last paragraph slightly
eliben 2e857c4
Issue #15321: update PyPI upload doc to say --no-raw passed to rst2ht…
eliben 5f644fd
Issue #15231: update PyPI upload doc to say --no-raw passed to rst2ht…
eliben e024e37
Issue #15538: Fix compilation of the getnameinfo() / getaddrinfo() em…
pitrou 8806d71
Graft a89d654adaa2 from 3.2 branch. Fixes #15620.
birkenfeld f6a6d6c
Remove unneeded "Release" and "Date" markers from doc index pages.
cjerdonek 1d13b77
Merge from 3.2: remove unneeded "Release" and "Date" markers from ind…
cjerdonek 20a1ede
Backport from 3.2: remove "Release" and "Date" markers from index pages.
cjerdonek 4494dd6
Update the description of which package versions PyPI displays (issue…
cjerdonek a23959f
Merge from 3.2: update the PyPI docs regarding listing versions (issu…
cjerdonek e2670a2
Backport from 3.2: update PyPI docs regarding listing versions (issue…
cjerdonek d596ba9
Add versionchanged note for a56cebff113a
merwok 2837ed9
Ignore .nfs* files in distutils (#7719).
merwok 6d73198
Merge fixes for #13614, #13512 and #7719 from 3.2
merwok fc7b293
Forward port new test for SSLSocket.connect_ex()
pitrou 673d1c2
Forward port new test for SSLSocket.connect_ex()
pitrou bcc4dda
Issue #16874: fix formatting of setup.py upload options in documentat…
cjerdonek 89f1afe
Issue #16874 (forward-port from 2.7): fix some documentation formatting.
cjerdonek 960a68b
Issue #16874 (merge from 3.2): fix some documentation formatting.
cjerdonek 8de498c
Issue #16403: Document how distutils uses the maintainer field in PKG…
akheron d3e2f8a
Issue #16403: Document how distutils uses the maintainer field in PKG…
akheron 6c2dc47
Issue #16403: Document how distutils uses the maintainer field in PKG…
akheron bd5c16c
Issue #16406: combine the doc pages for uploading and registering to …
cjerdonek 2f8c78e
Issue #16406: Combine the doc pages for uploading and registering to …
cjerdonek a0001e5
Issue #16406: Combine the doc pages for uploading and registering to …
cjerdonek ef5932b
Closes #4159: add LaTeX tabular column specifications to tables that …
birkenfeld 2017d94
Backport rev. 3ae74b361f53 to 2.7 branch.
birkenfeld 9da9655
#17614: IDLE no longer raises exception when quickly closing a file.
serwy 4a7db29
Fix missing period.
birkenfeld 7bb579e
#19196: Improved cross-references in distutils documentation.
serhiy-storchaka 21c65d6
Issue 19544 and Issue #7457: Restore the read_pkg_file method to dist…
jaraco bbbfa97
Issue #19544 and Issue #6516: Restore support for --user and --group …
akuchling cf70f0f
Issue #19544 and Issue #1180: Restore global option to ignore ~/.pyd…
akuchling f71ceb3
Issue #19407: add Python Packaging User Guide notes
ncoghlan caaafe4
Issue #19407: merge PPUG notes from 3.3
ncoghlan d28fb46
#16135: remove mentions of OS/2 from the documentation
akuchling 12e44f7
Avoid “error: None” messages from distutils (#4931).
merwok 7832ff3
Merge 3.3 (#4931)
merwok 4c07de9
Make distutils error messages more helpful (#11599).
merwok 835633e
Merge 3.3 (#11599)
merwok bdd6f5b
Close #19407: New installation & distribution guides
ncoghlan 5328876
Clarify distutils’ clean command (ref #6142)
merwok 7441dd1
Clarify distutils’ clean command (ref #6142)
merwok 01e5e58
Merge in all documentation changes since branching 3.4.0rc1.
larryhastings 7709012
Merged default into 3.4 branch. 3.4 branch is now effectively 3.4.1rc1.
larryhastings 76a17a8
Add missing parenthesis. Found by cocoatomo on docs@.
zware 3c18436
Remove superfluous open parenthesis. Noticed by cocoatomo on docs@.
zware 36826f0
Fix Issue #21528 - Fix documentation typos
dstufft ba6f2f1
Issue #21726: Remove unnecessary and contextually wrong line.
terryjreedy c3e06d9
Merge with 3.4
terryjreedy 4e149cf
Doc: remove invalid uses of ":option:" which will emit warnings in Sp…
birkenfeld 35adf08
merge with 3.4
birkenfeld 26f4ac4
#17325: Improve distutils PyPI documentation.
bitdancer d9210d5
Merge: #17325: Improve distutils PyPI documentation.
bitdancer 7499bd1
Use https:// URLs when referring to python.org hosts.
birkenfeld 55081f0
Merge with 3.4
birkenfeld 137cd90
Fixing broken links in doc, part 1: faq/
birkenfeld 0189bfe
merge with 3.4
birkenfeld 8854bbd
Fixing broken links in doc, part 4: some more breaks and redirects
birkenfeld 003764f
merge with 3.4
birkenfeld c2be7de
Doc: fix default role usage (except in unittest mock docs)
birkenfeld cb4aa18
Doc: fix default role usage (except in unittest mock docs)
birkenfeld 66f7fee
merge with 3.4
birkenfeld 0835a8e
distutils example: fix invalid rst in description string
birkenfeld 017c6a7
merge with 3.4
birkenfeld 4878d37
fix instances of consecutive articles (closes #23221)
benjaminp 591e2d4
merge 3.4 (#23221)
benjaminp ac5e667
Issue #23682: Delete Python 2.2 mention from distutils documentation.
berkerpeksag 34099c4
Issue #23682: Delete Python 2.2 mention from distutils documentation.
berkerpeksag ab8064d
Issue #23731: Implement PEP 488.
brettcannon 6474391
Issue #16314: Added support for the LZMA compression in distutils.
serhiy-storchaka 762d615
Back porting changeset db302b88fdb6 to 3.4 branch, which fixed multip…
orsenthil 0f722ad
null merge with 3.4
orsenthil 9fb5aaf
null merge 3.4 to 3.5 (9a0c5ffe7420 merged 3.4 to default, bypassing …
ned-deily 52dd2c2
null merge 3.5 to default (9a0c5ffe7420 merged 3.4 to default, bypass…
ned-deily fd199a1
Fix versionchanged directives
zware 3ce64f8
Merge 3.5
zware 6a02b76
fix name of argument in docstring and the docs (closes #25076)
benjaminp 44e85ae
merge 3.4
benjaminp bd652df
merge 3.5 (#25076)
benjaminp ce40227
Issue #25161: Add full stops in documentation; patch by Takase Arihiro
vadmium 1277abe
Issue #25161: Merge full stops from 3.4 into 3.5
vadmium 128a824
Issue #25161: Merge full stops from 3.5
vadmium 1d59f2e
Issue #25523: Further a-to-an corrections.
serhiy-storchaka a42c9b8
Issue #25523: Merge a-to-an corrections from 3.4.
serhiy-storchaka b9ed37a
Issue #25523: Merge a-to-an corrections from 3.5.
serhiy-storchaka d478d81
link to modern PUG url
benjaminp 754dc85
merge 3.4
benjaminp f1efeea
merge 3.5
benjaminp fe0cbda
Closes #26435: fix syntax in directives. Thanks to Jakub Stasiak.
birkenfeld de746a8
merge with 3.5
birkenfeld d8941f4
Closes #25910: fix dead and permanently redirected links in the docs.…
birkenfeld c9a798e
merge with 3.5
birkenfeld 7f1f468
Issue #26638: Fix links to some CLI options and section headings
vadmium 5ff800f
Issue #26638: Merge link fixes from 3.5
vadmium a5df731
Issue #26778: Fixed "a/an/and" typos in code comment and documentation.
serhiy-storchaka 82aa496
Issue #26778: Fixed "a/an/and" typos in code comment, documentation a…
serhiy-storchaka bc2bc7a
Issue #23921: Standardized documentation whitespace formatting.
serhiy-storchaka dca3f4d
Issue #23921: Standardized documentation whitespace formatting.
serhiy-storchaka da6d254
Issue #26014: Update 3.x packaging documentation:
ned-deily cc725e5
Issue #26462: Doc: reduce literal_block warnings, fix syntax highligh…
vadmium 753d446
Issue #26638: Mask undefined CLI options to defeat new Sphinx warnings
vadmium 2436e5f
Fix spacing after C++ in documentation
vadmium 0ea6937
Issue #29069: Update the default URL of PyPI server
berkerpeksag c2250ca
distutils docs: Fix a typo (GH-470)
Mariatta e9f6164
bpo-11913: Add README.rst to the distutils standard READMEs list (#563)
kirbyfan64 5284514
remove IRIX support (closes bpo-31341) (#3310)
benjaminp ca33b76
Remove all mention of Windows IA-64 support (GH-3389)
zware b129d05
bpo-31569: correct PCBuild/ case to PCbuild/ in build scripts and doc…
gronke 2ed774f
bpo-19610: setup() now raises TypeError for invalid types (GH-4519)
berkerpeksag 48df780
bpo-19610: Warn if distutils is provided something other than a list …
nascheme b62b9d8
bpo-25910: Link redirections in docs (#1933)
CuriousLearner 0319207
Improve highlighting of some code blocks. (GH-6401)
serhiy-storchaka 6432982
bpo-33297: Mention Pillow to work with more image formats. (#6505)
andresdelfino bb15219
bpo-33503: Fix the broken pypi link in the source and the documentati…
matrixise 9c2a778
bpo-33892: Doc: Use gender neutral words (GH-7770)
andresdelfino d4bb873
bpo-34962: make doctest in Doc/ now passes, and is enforced in CI (GH…
matrixise c6e0973
bpo-35027, distutils doc: Correct note on setup.py change in Python 3…
TilmanK 8dcc595
bpo-35042: Use the :pep: role where a PEP is specified (#10036)
matrixise bf2fc82
bpo-35110: Fix unintentional spaces around hyphens and dashes. (GH-10…
serhiy-storchaka 90912c9
bpo-35110: Fix yet few spaces before dashes. (GH-10255)
serhiy-storchaka 96864af
Add missing period in distutils.dep_util.newer_group doc (GH-11003)
andresdelfino f35f5d8
bpo-25592: Improve documentation of distutils data_files (GH-9767)
jdemeyer 601692e
bpo-21536: C extensions are no longer linked to libpython (GH-12946)
vstinner 77d2f47
bpo-21536: On Android, C extensions are linked to libpython (GH-12989)
xdegaye 8ace7cd
Doc: Fix missing bracket (GH-13163)
azalea 9ec0041
bpo-33071: remove outdated PyPI docs (GH-13087)
kojoidrissa 6e93c36
bpo-36797: Prune more legacy distutils documentation (GH-13092)
ncoghlan a2dc287
bpo-36797: Reduce levels of indirection in outdated distutils docs (#…
ncoghlan 0d3ecff
bpo-21536: On Cygwin, C extensions must be linked with libpython (GH-…
embray ceeaa6a
bpo-10945: Drop support for bdist_wininst on non-Windows systems (GH-…
hroncok 4686db0
bpo-37481: Deprecate distutils bdist_wininst command (GH-14553)
vstinner 7f891f2
bpo-36797: Fix a dead link in Doc/distutils/apiref (GH-15700)
hroncok a9a584f
bpo-38103: fix conflicting labels in the docs. (GH-15906)
ezio-melotti a831d3a
bpo-21063: Improve module synopsis for distutils (GH-17363)
GeniusLearner fb4296c
bpo-38021: Modify AIX platform_tag so it covers PEP 425 needs (GH-17303)
aixtools 9c8d213
bpo-38914 Do not require email field in setup.py. (GH-17388)
jugmac00 261f346
bpo-39586: Deprecate distutils bdist_msi command (GH-18415)
hugovk 1bfb4ba
Move docs to docs/distutils
jaraco 68f5b81
Merge ../python-distutils-docs into master
jaraco 466219b
Merge https://github.com/pypa/distutils into feature/distutils-docs
jaraco 109bde8
Move distutils docs into 'deprecated' section and link them from that…
jaraco 68b6847
Enable intersphinx to link against CPython docs
webknjaz 8848933
Correct broken refs in distutils docs
webknjaz 18b7a3e
Allow some refs to undocumented/undeclared objects
webknjaz 8b49463
Merge pull request #2438 from webknjaz/bugfixes/distutils-sphinx-refs
jaraco 4d7a11e
Merge branch 'main' into feature/distutils-docs
jaraco File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
.. note:: | ||
|
||
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. |
Large diffs are not rendered by default.
Oops, something went wrong.
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,106 @@ | ||
.. _reference: | ||
|
||
***************** | ||
Command Reference | ||
***************** | ||
|
||
.. include:: ./_setuptools_disclaimer.rst | ||
|
||
.. % \section{Building modules: the \protect\command{build} command family} | ||
.. % \label{build-cmds} | ||
.. % \subsubsection{\protect\command{build}} | ||
.. % \label{build-cmd} | ||
.. % \subsubsection{\protect\command{build\_py}} | ||
.. % \label{build-py-cmd} | ||
.. % \subsubsection{\protect\command{build\_ext}} | ||
.. % \label{build-ext-cmd} | ||
.. % \subsubsection{\protect\command{build\_clib}} | ||
.. % \label{build-clib-cmd} | ||
|
||
|
||
.. _install-cmd: | ||
|
||
Installing modules: the :command:`install` command family | ||
========================================================= | ||
|
||
The install command ensures that the build commands have been run and then runs | ||
the subcommands :command:`install_lib`, :command:`install_data` and | ||
:command:`install_scripts`. | ||
|
||
.. % \subsubsection{\protect\command{install\_lib}} | ||
.. % \label{install-lib-cmd} | ||
|
||
|
||
.. _install-data-cmd: | ||
|
||
:command:`install_data` | ||
----------------------- | ||
|
||
This command installs all data files provided with the distribution. | ||
|
||
|
||
.. _install-scripts-cmd: | ||
|
||
:command:`install_scripts` | ||
-------------------------- | ||
|
||
This command installs all (Python) scripts in the distribution. | ||
|
||
.. % \subsection{Cleaning up: the \protect\command{clean} command} | ||
.. % \label{clean-cmd} | ||
|
||
|
||
.. _sdist-cmd: | ||
|
||
Creating a source distribution: the :command:`sdist` command | ||
============================================================ | ||
|
||
.. XXX fragment moved down from above: needs context! | ||
|
||
The manifest template commands are: | ||
|
||
+-------------------------------------------+-----------------------------------------------+ | ||
| Command | Description | | ||
+===========================================+===============================================+ | ||
| :command:`include pat1 pat2 ...` | include all files matching any of the listed | | ||
| | patterns | | ||
+-------------------------------------------+-----------------------------------------------+ | ||
| :command:`exclude pat1 pat2 ...` | exclude all files matching any of the listed | | ||
| | patterns | | ||
+-------------------------------------------+-----------------------------------------------+ | ||
| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of | | ||
| ...` | the listed patterns | | ||
+-------------------------------------------+-----------------------------------------------+ | ||
| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of | | ||
| ...` | the listed patterns | | ||
+-------------------------------------------+-----------------------------------------------+ | ||
| :command:`global-include pat1 pat2 ...` | include all files anywhere in the source tree | | ||
| | matching --- & any of the listed patterns | | ||
+-------------------------------------------+-----------------------------------------------+ | ||
| :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree | | ||
| | matching --- & any of the listed patterns | | ||
+-------------------------------------------+-----------------------------------------------+ | ||
| :command:`prune dir` | exclude all files under *dir* | | ||
+-------------------------------------------+-----------------------------------------------+ | ||
| :command:`graft dir` | include all files under *dir* | | ||
+-------------------------------------------+-----------------------------------------------+ | ||
|
||
The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of | ||
regular filename characters, ``?`` matches any single regular filename | ||
character, and ``[range]`` matches any of the characters in *range* (e.g., | ||
``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename | ||
character" is platform-specific: on Unix it is anything except slash; on Windows | ||
anything except backslash or colon. | ||
|
||
.. XXX Windows support not there yet | ||
|
||
.. % \section{Creating a built distribution: the | ||
.. % \protect\command{bdist} command family} | ||
.. % \label{bdist-cmds} | ||
|
||
.. % \subsection{\protect\command{bdist}} | ||
.. % \subsection{\protect\command{bdist\_dumb}} | ||
.. % \subsection{\protect\command{bdist\_rpm}} | ||
.. % \subsection{\protect\command{bdist\_wininst}} | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,144 @@ | ||
.. _setup-config: | ||
|
||
************************************ | ||
Writing the Setup Configuration File | ||
************************************ | ||
|
||
.. include:: ./_setuptools_disclaimer.rst | ||
|
||
Often, it's not possible to write down everything needed to build a distribution | ||
*a priori*: you may need to get some information from the user, or from the | ||
user's system, in order to proceed. As long as that information is fairly | ||
simple---a list of directories to search for C header files or libraries, for | ||
example---then providing a configuration file, :file:`setup.cfg`, for users to | ||
edit is a cheap and easy way to solicit it. Configuration files also let you | ||
provide default values for any command option, which the installer can then | ||
override either on the command-line or by editing the config file. | ||
|
||
The setup configuration file is a useful middle-ground between the setup | ||
script---which, ideally, would be opaque to installers [#]_---and the command-line to | ||
the setup script, which is outside of your control and entirely up to the | ||
installer. In fact, :file:`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: | ||
|
||
.. % (If you have more advanced needs, such as determining which extensions | ||
.. % to build based on what capabilities are present on the target system, | ||
.. % then you need the Distutils ``auto-configuration'' facility. This | ||
.. % started to appear in Distutils 0.9 but, as of this writing, isn't mature | ||
.. % or stable enough yet for real-world use.) | ||
|
||
* installers can override some of what you put in :file:`setup.py` by editing | ||
:file:`setup.cfg` | ||
|
||
* you can provide non-standard defaults for options that are not easily set in | ||
:file:`setup.py` | ||
|
||
* installers can override anything in :file:`setup.cfg` using the command-line | ||
options to :file:`setup.py` | ||
|
||
The basic syntax of the configuration file is simple: | ||
|
||
.. code-block:: ini | ||
|
||
[command] | ||
option=value | ||
... | ||
|
||
where *command* is one of the Distutils commands (e.g. :command:`build_py`, | ||
:command:`install`), and *option* is one of the options that command supports. | ||
Any number of options can be supplied for each command, and any number of | ||
command sections can be included in the file. Blank lines are ignored, as are | ||
comments, which run from a ``'#'`` character until the end of the line. Long | ||
option values can be split across multiple lines simply by indenting the | ||
continuation lines. | ||
|
||
You can find out the list of options supported by a particular command with the | ||
universal :option:`!--help` option, e.g. | ||
|
||
.. code-block:: shell-session | ||
|
||
$ 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 | ||
[...] | ||
|
||
Note that an option spelled :option:`!--foo-bar` on the command-line is spelled | ||
``foo_bar`` in configuration files. | ||
|
||
.. _distutils-build-ext-inplace: | ||
|
||
For example, say you want your extensions to be built "in-place"---that is, you | ||
have an extension ``pkg.ext``, and you want the compiled extension file | ||
(:file:`ext.so` on Unix, say) to be put in the same source directory as your | ||
pure Python modules ``pkg.mod1`` and ``pkg.mod2``. You can always use the | ||
:option:`!--inplace` option on the command-line to ensure this: | ||
|
||
.. code-block:: sh | ||
|
||
python setup.py build_ext --inplace | ||
|
||
But this requires that you always specify the :command:`build_ext` command | ||
explicitly, and remember to provide :option:`!--inplace`. An easier way is to | ||
"set and forget" this option, by encoding it in :file:`setup.cfg`, the | ||
configuration file for this distribution: | ||
|
||
.. code-block:: ini | ||
|
||
[build_ext] | ||
inplace=1 | ||
|
||
This will affect all builds of this module distribution, whether or not you | ||
explicitly specify :command:`build_ext`. If you include :file:`setup.cfg` in | ||
your source distribution, it will also affect end-user builds---which is | ||
probably a bad idea for this option, since always building extensions in-place | ||
would break installation of the module distribution. In certain peculiar cases, | ||
though, modules are built right in their installation directory, so this is | ||
conceivably a useful ability. (Distributing extensions that expect to be built | ||
in their installation directory is almost always a bad idea, though.) | ||
|
||
Another example: certain commands take a lot of options that don't change from | ||
run to run; for example, :command:`bdist_rpm` needs to know everything required | ||
to generate a "spec" file for creating an RPM distribution. Some of this | ||
information comes from the setup script, and some is automatically generated by | ||
the Distutils (such as the list of files installed). But some of it has to be | ||
supplied as options to :command:`bdist_rpm`, which would be very tedious to do | ||
on the command-line for every run. Hence, here is a snippet from the Distutils' | ||
own :file:`setup.cfg`: | ||
|
||
.. code-block:: ini | ||
|
||
[bdist_rpm] | ||
release = 1 | ||
packager = Greg Ward <gward@python.net> | ||
doc_files = CHANGES.txt | ||
README.txt | ||
USAGE.txt | ||
doc/ | ||
examples/ | ||
|
||
Note that the ``doc_files`` option is simply a whitespace-separated string | ||
split across multiple lines for readability. | ||
|
||
|
||
.. seealso:: | ||
|
||
:ref:`inst-config-syntax` in "Installing Python Modules" | ||
More information on the configuration files is available in the manual for | ||
system administrators. | ||
|
||
|
||
.. rubric:: Footnotes | ||
|
||
.. [#] This ideal probably won't be achieved until auto-configuration is fully | ||
supported by the Distutils. | ||
|
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@jaraco this overrides the
intersphinx_mapping
declaration above, it needs a proper merge