Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(154684)

Side by Side Diff: Doc/distutils/setupscript.rst

Issue 19196: Improve cross-references in pickle documentation
Patch Set: Created 6 years, 2 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
« Doc/distutils/extending.rst ('K') | « Doc/distutils/extending.rst ('k') | no next file » | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 .. _setup-script: 1 .. _setup-script:
2 2
3 ************************ 3 ************************
4 Writing the Setup Script 4 Writing the Setup Script
5 ************************ 5 ************************
6 6
7 The setup script is the centre of all activity in building, distributing, and 7 The setup script is the centre of all activity in building, distributing, and
8 installing modules using the Distutils. The main purpose of the setup script is 8 installing modules using the Distutils. The main purpose of the setup script is
9 to describe your module distribution to the Distutils, so that the various 9 to describe your module distribution to the Distutils, so that the various
10 commands that operate on your modules do the right thing. As we saw in section 10 commands that operate on your modules do the right thing. As we saw in section
(...skipping 121 matching lines...) Expand 10 before | Expand all | Expand 10 after
132 pure Python modules, describing them to the Distutils is a bit more complicated. 132 pure Python modules, describing them to the Distutils is a bit more complicated.
133 Unlike pure modules, it's not enough just to list modules or packages and expect 133 Unlike pure modules, it's not enough just to list modules or packages and expect
134 the Distutils to go out and find the right files; you have to specify the 134 the Distutils to go out and find the right files; you have to specify the
135 extension name, source file(s), and any compile/link requirements (include 135 extension name, source file(s), and any compile/link requirements (include
136 directories, libraries to link with, etc.). 136 directories, libraries to link with, etc.).
137 137
138 .. XXX read over this section 138 .. XXX read over this section
139 139
140 All of this is done through another keyword argument to :func:`setup`, the 140 All of this is done through another keyword argument to :func:`setup`, the
141 :option:`ext_modules` option. :option:`ext_modules` is just a list of 141 :option:`ext_modules` option. :option:`ext_modules` is just a list of
142 :class:`Extension` instances, each of which describes a single extension module. 142 :class:`~distutils.core.Extension` instances, each of which describes a single e xtension module.
143 Suppose your distribution includes a single extension, called :mod:`foo` and 143 Suppose your distribution includes a single extension, called :mod:`foo` and
144 implemented by :file:`foo.c`. If no additional instructions to the 144 implemented by :file:`foo.c`. If no additional instructions to the
145 compiler/linker are needed, describing this extension is quite simple:: 145 compiler/linker are needed, describing this extension is quite simple::
146 146
147 Extension('foo', ['foo.c']) 147 Extension('foo', ['foo.c'])
148 148
149 The :class:`Extension` class can be imported from :mod:`distutils.core` along 149 The :class:`~distutils.core.Extension` class can be imported from :mod:`distutil s.core` along
Georg 2013/10/08 22:25:09 unneeded... etc.
storchaka 2013/10/09 10:05:55 Perhaps left one link per subsection?
Georg 2013/10/09 10:20:37 Yes, something like that is fine. On 2013/10/09 1
150 with :func:`setup`. Thus, the setup script for a module distribution that 150 with :func:`setup`. Thus, the setup script for a module distribution that
151 contains only this one extension and nothing else might be:: 151 contains only this one extension and nothing else might be::
152 152
153 from distutils.core import setup, Extension 153 from distutils.core import setup, Extension
154 setup(name='foo', 154 setup(name='foo',
155 version='1.0', 155 version='1.0',
156 ext_modules=[Extension('foo', ['foo.c'])], 156 ext_modules=[Extension('foo', ['foo.c'])],
157 ) 157 )
158 158
159 The :class:`Extension` class (actually, the underlying extension-building 159 The :class:`~distutils.core.Extension` class (actually, the underlying extension -building
160 machinery implemented by the :command:`build_ext` command) supports a great deal 160 machinery implemented by the :command:`build_ext` command) supports a great deal
161 of flexibility in describing Python extensions, which is explained in the 161 of flexibility in describing Python extensions, which is explained in the
162 following sections. 162 following sections.
163 163
164 164
165 Extension names and packages 165 Extension names and packages
166 ---------------------------- 166 ----------------------------
167 167
168 The first argument to the :class:`Extension` constructor is always the name of 168 The first argument to the :class:`~distutils.core.Extension` constructor is alwa ys the name of
169 the extension, including any package names. For example, :: 169 the extension, including any package names. For example, ::
170 170
171 Extension('foo', ['src/foo1.c', 'src/foo2.c']) 171 Extension('foo', ['src/foo1.c', 'src/foo2.c'])
172 172
173 describes an extension that lives in the root package, while :: 173 describes an extension that lives in the root package, while ::
174 174
175 Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c']) 175 Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])
176 176
177 describes the same extension in the :mod:`pkg` package. The source files and 177 describes the same extension in the :mod:`pkg` package. The source files and
178 resulting object code are identical in both cases; the only difference is where 178 resulting object code are identical in both cases; the only difference is where
(...skipping 10 matching lines...) Expand all
189 Extension('subpkg.bar', ['bar.c'])], 189 Extension('subpkg.bar', ['bar.c'])],
190 ) 190 )
191 191
192 will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to 192 will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to
193 :mod:`pkg.subpkg.bar`. 193 :mod:`pkg.subpkg.bar`.
194 194
195 195
196 Extension source files 196 Extension source files
197 ---------------------- 197 ----------------------
198 198
199 The second argument to the :class:`Extension` constructor is a list of source 199 The second argument to the :class:`~distutils.core.Extension` constructor is a l ist of source
200 files. Since the Distutils currently only support C, C++, and Objective-C 200 files. Since the Distutils currently only support C, C++, and Objective-C
201 extensions, these are normally C/C++/Objective-C source files. (Be sure to use 201 extensions, these are normally C/C++/Objective-C source files. (Be sure to use
202 appropriate extensions to distinguish C++\ source files: :file:`.cc` and 202 appropriate extensions to distinguish C++\ source files: :file:`.cc` and
203 :file:`.cpp` seem to be recognized by both Unix and Windows compilers.) 203 :file:`.cpp` seem to be recognized by both Unix and Windows compilers.)
204 204
205 However, you can also include SWIG interface (:file:`.i`) files in the list; the 205 However, you can also include SWIG interface (:file:`.i`) files in the list; the
206 :command:`build_ext` command knows how to deal with SWIG extensions: it will run 206 :command:`build_ext` command knows how to deal with SWIG extensions: it will run
207 SWIG on the interface file and compile the resulting C/C++ file into your 207 SWIG on the interface file and compile the resulting C/C++ file into your
208 extension. 208 extension.
209 209
(...skipping 15 matching lines...) Expand all
225 On some platforms, you can include non-source files that are processed by the 225 On some platforms, you can include non-source files that are processed by the
226 compiler and included in your extension. Currently, this just means Windows 226 compiler and included in your extension. Currently, this just means Windows
227 message text (:file:`.mc`) files and resource definition (:file:`.rc`) files for 227 message text (:file:`.mc`) files and resource definition (:file:`.rc`) files for
228 Visual C++. These will be compiled to binary resource (:file:`.res`) files and 228 Visual C++. These will be compiled to binary resource (:file:`.res`) files and
229 linked into the executable. 229 linked into the executable.
230 230
231 231
232 Preprocessor options 232 Preprocessor options
233 -------------------- 233 --------------------
234 234
235 Three optional arguments to :class:`Extension` will help if you need to specify 235 Three optional arguments to :class:`~distutils.core.Extension` will help if you need to specify
236 include directories to search or preprocessor macros to define/undefine: 236 include directories to search or preprocessor macros to define/undefine:
237 ``include_dirs``, ``define_macros``, and ``undef_macros``. 237 ``include_dirs``, ``define_macros``, and ``undef_macros``.
238 238
239 For example, if your extension requires header files in the :file:`include` 239 For example, if your extension requires header files in the :file:`include`
240 directory under your distribution root, use the ``include_dirs`` option:: 240 directory under your distribution root, use the ``include_dirs`` option::
241 241
242 Extension('foo', ['foo.c'], include_dirs=['include']) 242 Extension('foo', ['foo.c'], include_dirs=['include'])
243 243
244 You can specify absolute directories there; if you know that your extension will 244 You can specify absolute directories there; if you know that your extension will
245 only be built on Unix systems with X11R6 installed to :file:`/usr`, you can get 245 only be built on Unix systems with X11R6 installed to :file:`/usr`, you can get
(...skipping 449 matching lines...) Expand 10 before | Expand all | Expand 10 after
695 are trying to install a package. If they get a big long traceback from deep 695 are trying to install a package. If they get a big long traceback from deep
696 inside the guts of Distutils, they may think the package or the Python 696 inside the guts of Distutils, they may think the package or the Python
697 installation is broken because they don't read all the way down to the bottom 697 installation is broken because they don't read all the way down to the bottom
698 and see that it's a permission problem. 698 and see that it's a permission problem.
699 699
700 On the other hand, this doesn't help the developer to find the cause of the 700 On the other hand, this doesn't help the developer to find the cause of the
701 failure. For this purpose, the DISTUTILS_DEBUG environment variable can be set 701 failure. For this purpose, the DISTUTILS_DEBUG environment variable can be set
702 to anything except an empty string, and distutils will now print detailed 702 to anything except an empty string, and distutils will now print detailed
703 information what it is doing, and prints the full traceback in case an exception 703 information what it is doing, and prints the full traceback in case an exception
704 occurs. 704 occurs.
OLDNEW
« Doc/distutils/extending.rst ('K') | « Doc/distutils/extending.rst ('k') | no next file » | no next file with comments »

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+