mirror of
https://github.com/python/cpython
synced 2024-09-20 08:50:11 +00:00
Issue #25022: Add NEWS, fix docs to not mention the old example.
This commit is contained in:
parent
b54a068204
commit
3d9a9d47a8
|
@ -37,150 +37,9 @@ There are two approaches to building extension modules on Windows, just as there
|
||||||
are on Unix: use the :mod:`distutils` package to control the build process, or
|
are on Unix: use the :mod:`distutils` package to control the build process, or
|
||||||
do things manually. The distutils approach works well for most extensions;
|
do things manually. The distutils approach works well for most extensions;
|
||||||
documentation on using :mod:`distutils` to build and package extension modules
|
documentation on using :mod:`distutils` to build and package extension modules
|
||||||
is available in :ref:`distutils-index`. This section describes the manual
|
is available in :ref:`distutils-index`. If you find you really need to do
|
||||||
approach to building Python extensions written in C or C++.
|
things manually, it may be instructive to study the project file for the
|
||||||
|
:source:`winsound <PCbuild/winsound.vcxproj>` standard library module.
|
||||||
To build extensions using these instructions, you need to have a copy of the
|
|
||||||
Python sources of the same version as your installed Python. You will need
|
|
||||||
Microsoft Visual C++ "Developer Studio"; project files are supplied for VC++
|
|
||||||
version 7.1, but you can use older versions of VC++. Notice that you should use
|
|
||||||
the same version of VC++that was used to build Python itself. The example files
|
|
||||||
described here are distributed with the Python sources in the
|
|
||||||
:file:`PC\\example_nt\\` directory.
|
|
||||||
|
|
||||||
#. **Copy the example files** --- The :file:`example_nt` directory is a
|
|
||||||
subdirectory of the :file:`PC` directory, in order to keep all the PC-specific
|
|
||||||
files under the same directory in the source distribution. However, the
|
|
||||||
:file:`example_nt` directory can't actually be used from this location. You
|
|
||||||
first need to copy or move it up one level, so that :file:`example_nt` is a
|
|
||||||
sibling of the :file:`PC` and :file:`Include` directories. Do all your work
|
|
||||||
from within this new location.
|
|
||||||
|
|
||||||
#. **Open the project** --- From VC++, use the :menuselection:`File --> Open
|
|
||||||
Solution` dialog (not :menuselection:`File --> Open`!). Navigate to and select
|
|
||||||
the file :file:`example.sln`, in the *copy* of the :file:`example_nt` directory
|
|
||||||
you made above. Click Open.
|
|
||||||
|
|
||||||
#. **Build the example DLL** --- In order to check that everything is set up
|
|
||||||
right, try building:
|
|
||||||
|
|
||||||
#. Select a configuration. This step is optional. Choose
|
|
||||||
:menuselection:`Build --> Configuration Manager --> Active Solution Configuration`
|
|
||||||
and select either :guilabel:`Release` or :guilabel:`Debug`. If you skip this
|
|
||||||
step, VC++ will use the Debug configuration by default.
|
|
||||||
|
|
||||||
#. Build the DLL. Choose :menuselection:`Build --> Build Solution`. This
|
|
||||||
creates all intermediate and result files in a subdirectory called either
|
|
||||||
:file:`Debug` or :file:`Release`, depending on which configuration you selected
|
|
||||||
in the preceding step.
|
|
||||||
|
|
||||||
#. **Testing the debug-mode DLL** --- Once the Debug build has succeeded, bring
|
|
||||||
up a DOS box, and change to the :file:`example_nt\\Debug` directory. You should
|
|
||||||
now be able to repeat the following session (``C>`` is the DOS prompt, ``>>>``
|
|
||||||
is the Python prompt; note that build information and various debug output from
|
|
||||||
Python may not match this screen dump exactly)::
|
|
||||||
|
|
||||||
C>..\..\PCbuild\python_d
|
|
||||||
Adding parser accelerators ...
|
|
||||||
Done.
|
|
||||||
Python 2.2 (#28, Dec 19 2001, 23:26:37) [MSC 32 bit (Intel)] on win32
|
|
||||||
Type "copyright", "credits" or "license" for more information.
|
|
||||||
>>> import example
|
|
||||||
[4897 refs]
|
|
||||||
>>> example.foo()
|
|
||||||
Hello, world
|
|
||||||
[4903 refs]
|
|
||||||
>>>
|
|
||||||
|
|
||||||
Congratulations! You've successfully built your first Python extension module.
|
|
||||||
|
|
||||||
#. **Creating your own project** --- Choose a name and create a directory for
|
|
||||||
it. Copy your C sources into it. Note that the module source file name does
|
|
||||||
not necessarily have to match the module name, but the name of the
|
|
||||||
initialization function should match the module name --- you can only import a
|
|
||||||
module :mod:`spam` if its initialization function is called :c:func:`initspam`,
|
|
||||||
and it should call :c:func:`Py_InitModule` with the string ``"spam"`` as its
|
|
||||||
first argument (use the minimal :file:`example.c` in this directory as a guide).
|
|
||||||
By convention, it lives in a file called :file:`spam.c` or :file:`spammodule.c`.
|
|
||||||
The output file should be called :file:`spam.pyd` (in Release mode) or
|
|
||||||
:file:`spam_d.pyd` (in Debug mode). The extension :file:`.pyd` was chosen
|
|
||||||
to avoid confusion with a system library :file:`spam.dll` to which your module
|
|
||||||
could be a Python interface.
|
|
||||||
|
|
||||||
Now your options are:
|
|
||||||
|
|
||||||
#. Copy :file:`example.sln` and :file:`example.vcproj`, rename them to
|
|
||||||
:file:`spam.\*`, and edit them by hand, or
|
|
||||||
|
|
||||||
#. Create a brand new project; instructions are below.
|
|
||||||
|
|
||||||
In either case, copy :file:`example_nt\\example.def` to :file:`spam\\spam.def`,
|
|
||||||
and edit the new :file:`spam.def` so its second line contains the string
|
|
||||||
'``initspam``'. If you created a new project yourself, add the file
|
|
||||||
:file:`spam.def` to the project now. (This is an annoying little file with only
|
|
||||||
two lines. An alternative approach is to forget about the :file:`.def` file,
|
|
||||||
and add the option :option:`/export:initspam` somewhere to the Link settings, by
|
|
||||||
manually editing the setting in Project Properties dialog).
|
|
||||||
|
|
||||||
#. **Creating a brand new project** --- Use the :menuselection:`File --> New
|
|
||||||
--> Project` dialog to create a new Project Workspace. Select :guilabel:`Visual
|
|
||||||
C++ Projects/Win32/ Win32 Project`, enter the name (``spam``), and make sure the
|
|
||||||
Location is set to parent of the :file:`spam` directory you have created (which
|
|
||||||
should be a direct subdirectory of the Python build tree, a sibling of
|
|
||||||
:file:`Include` and :file:`PC`). Select Win32 as the platform (in my version,
|
|
||||||
this is the only choice). Make sure the Create new workspace radio button is
|
|
||||||
selected. Click OK.
|
|
||||||
|
|
||||||
You should now create the file :file:`spam.def` as instructed in the previous
|
|
||||||
section. Add the source files to the project, using :menuselection:`Project -->
|
|
||||||
Add Existing Item`. Set the pattern to ``*.*`` and select both :file:`spam.c`
|
|
||||||
and :file:`spam.def` and click OK. (Inserting them one by one is fine too.)
|
|
||||||
|
|
||||||
Now open the :menuselection:`Project --> spam properties` dialog. You only need
|
|
||||||
to change a few settings. Make sure :guilabel:`All Configurations` is selected
|
|
||||||
from the :guilabel:`Settings for:` dropdown list. Select the C/C++ tab. Choose
|
|
||||||
the General category in the popup menu at the top. Type the following text in
|
|
||||||
the entry box labeled :guilabel:`Additional Include Directories`::
|
|
||||||
|
|
||||||
..\Include,..\PC
|
|
||||||
|
|
||||||
Then, choose the General category in the Linker tab, and enter ::
|
|
||||||
|
|
||||||
..\PCbuild
|
|
||||||
|
|
||||||
in the text box labelled :guilabel:`Additional library Directories`.
|
|
||||||
|
|
||||||
Now you need to add some mode-specific settings:
|
|
||||||
|
|
||||||
Select :guilabel:`Release` in the :guilabel:`Configuration` dropdown list.
|
|
||||||
Choose the :guilabel:`Link` tab, choose the :guilabel:`Input` category, and
|
|
||||||
append ``pythonXY.lib`` to the list in the :guilabel:`Additional Dependencies`
|
|
||||||
box.
|
|
||||||
|
|
||||||
Select :guilabel:`Debug` in the :guilabel:`Configuration` dropdown list, and
|
|
||||||
append ``pythonXY_d.lib`` to the list in the :guilabel:`Additional Dependencies`
|
|
||||||
box. Then click the C/C++ tab, select :guilabel:`Code Generation`, and select
|
|
||||||
:guilabel:`Multi-threaded Debug DLL` from the :guilabel:`Runtime library`
|
|
||||||
dropdown list.
|
|
||||||
|
|
||||||
Select :guilabel:`Release` again from the :guilabel:`Configuration` dropdown
|
|
||||||
list. Select :guilabel:`Multi-threaded DLL` from the :guilabel:`Runtime
|
|
||||||
library` dropdown list.
|
|
||||||
|
|
||||||
If your module creates a new type, you may have trouble with this line::
|
|
||||||
|
|
||||||
PyVarObject_HEAD_INIT(&PyType_Type, 0)
|
|
||||||
|
|
||||||
Static type object initializers in extension modules may cause
|
|
||||||
compiles to fail with an error message like "initializer not a
|
|
||||||
constant". This shows up when building DLL under MSVC. Change it to::
|
|
||||||
|
|
||||||
PyVarObject_HEAD_INIT(NULL, 0)
|
|
||||||
|
|
||||||
and add the following to the module initialization function::
|
|
||||||
|
|
||||||
if (PyType_Ready(&MyObject_Type) < 0)
|
|
||||||
return NULL;
|
|
||||||
|
|
||||||
|
|
||||||
.. _dynamic-linking:
|
.. _dynamic-linking:
|
||||||
|
|
|
@ -517,6 +517,11 @@ Tools/Demos
|
||||||
|
|
||||||
- Issue #24031: make patchcheck now supports git checkouts, too.
|
- Issue #24031: make patchcheck now supports git checkouts, too.
|
||||||
|
|
||||||
|
Windows
|
||||||
|
-------
|
||||||
|
|
||||||
|
- Issue #25022: Removed very outdated PC/example_nt/ directory.
|
||||||
|
|
||||||
|
|
||||||
What's New in Python 3.4.3?
|
What's New in Python 3.4.3?
|
||||||
===========================
|
===========================
|
||||||
|
|
Loading…
Reference in a new issue