<commit_before>\chapter{Building C and \Cpp{} Extensions on Windows%
     \label{building-on-windows}}


This chapter briefly explains how to create a Windows extension module
for Python using Microsoft Visual \Cpp, and follows with more
detailed background information on how it works.  The explanatory
material is useful for both the Windows programmer learning to build
Python extensions and the \UNIX{} programmer interested in producing
software which can be successfully built on both \UNIX{} and Windows.

Module authors are encouraged to use the distutils approach for
building extension modules, instead of the one described in this
section. You will still need the C compiler that was used to build
Python; typically Microsoft Visual \Cpp.

\begin{notice}
  This chapter mentions a number of filenames that include an encoded
  Python version number.  These filenames are represented with the
  version number shown as \samp{XY}; in practive, \character{X} will
  be the major version number and \character{Y} will be the minor
  version number of the Python release you're working with.  For
  example, if you are using Python 2.2.1, \samp{XY} will actually be
  \samp{22}.
\end{notice}


\section{A Cookbook Approach \label{win-cookbook}}

There are two approaches to building extension modules on Windows,
just as there are on \UNIX: use the \refmodule{distutils} package to
control the build process, or do things manually.  The distutils
approach works well for most extensions; documentation on using
\refmodule{distutils} to build and package extension modules is
available in \citetitle[../dist/dist.html]{Distributing Python
Modules}.  This section describes the manual approach to building
Python extensions written in C or \Cpp.

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 \Cpp{} ``Developer Studio''; project
files are supplied for V\Cpp{} version 6, but you can use older
versions of V\Cpp.  The example files described here are distributed
with the Python sources in the \file{PC\textbackslash
example_nt\textbackslash} directory.

\begin{enumerate}
  \item
  \strong{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.

  \item
  \strong{Open the project}\\
    From V\Cpp, use the \menuselection{File \sub Open Workspace}
    dialog (not \menuselection{File \sub Open}!).  Navigate to and
    select the file \file{example.dsw}, in the \emph{copy} of the
    \file{example_nt} directory you made above.  Click Open.

  \item
  \strong{Build the example DLL}\\
    In order to check that everything is set up right, try building:

    \begin{enumerate}
      \item
        Select a configuration.  This step is optional.  Choose
        \menuselection{Build \sub Select Active Configuration} and
        select either ``example - Win32 Release'' or ``example - Win32
        Debug.''  If you skip this step, V\Cpp{} will use the Debug
        configuration by default.

      \item
        Build the DLL.  Choose \menuselection{Build \sub Build
        example_d.dll} in Debug mode, or \menuselection{Build \sub
        Build example.dll} in Release mode.  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.
    \end{enumerate}

  \item
  \strong{Testing the debug-mode DLL}\\
    Once the Debug build has succeeded, bring up a DOS box, and change
    to the \file{example_nt\textbackslash Debug} directory.  You
    should now be able to repeat the following session (\code{C>} is
    the DOS prompt, \code{>\code{>}>} is the Python prompt; note that
    build information and various debug output from Python may not
    match this screen dump exactly):

\begin{verbatim}
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]
>>>
\end{verbatim}

    Congratulations!  You've successfully built your first Python
    extension module.

  \item
  \strong{Cretating 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 \module{spam} if its initialization function
    is called \cfunction{initspam()}, and it should call
    \cfunction{Py_InitModule()} with the string \code{"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.dll} or \file{spam.pyd} (the latter is supported
    to avoid confusion with a system library \file{spam.dll} to which
    your module could be a Python interface) in Release mode, or
    \file{spam_d.dll} or \file{spam_d.pyd} in Debug mode.

    Now your options are:
<commit_msg>Fix a typo.<commit_after>\chapter{Building C and \Cpp{} Extensions on Windows%
     \label{building-on-windows}}


This chapter briefly explains how to create a Windows extension module
for Python using Microsoft Visual \Cpp, and follows with more
detailed background information on how it works.  The explanatory
material is useful for both the Windows programmer learning to build
Python extensions and the \UNIX{} programmer interested in producing
software which can be successfully built on both \UNIX{} and Windows.

Module authors are encouraged to use the distutils approach for
building extension modules, instead of the one described in this
section. You will still need the C compiler that was used to build
Python; typically Microsoft Visual \Cpp.

\begin{notice}
  This chapter mentions a number of filenames that include an encoded
  Python version number.  These filenames are represented with the
  version number shown as \samp{XY}; in practive, \character{X} will
  be the major version number and \character{Y} will be the minor
  version number of the Python release you're working with.  For
  example, if you are using Python 2.2.1, \samp{XY} will actually be
  \samp{22}.
\end{notice}


\section{A Cookbook Approach \label{win-cookbook}}

There are two approaches to building extension modules on Windows,
just as there are on \UNIX: use the \refmodule{distutils} package to
control the build process, or do things manually.  The distutils
approach works well for most extensions; documentation on using
\refmodule{distutils} to build and package extension modules is
available in \citetitle[../dist/dist.html]{Distributing Python
Modules}.  This section describes the manual approach to building
Python extensions written in C or \Cpp.

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 \Cpp{} ``Developer Studio''; project
files are supplied for V\Cpp{} version 6, but you can use older
versions of V\Cpp.  The example files described here are distributed
with the Python sources in the \file{PC\textbackslash
example_nt\textbackslash} directory.

\begin{enumerate}
  \item
  \strong{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.

  \item
  \strong{Open the project}\\
    From V\Cpp, use the \menuselection{File \sub Open Workspace}
    dialog (not \menuselection{File \sub Open}!).  Navigate to and
    select the file \file{example.dsw}, in the \emph{copy} of the
    \file{example_nt} directory you made above.  Click Open.

  \item
  \strong{Build the example DLL}\\
    In order to check that everything is set up right, try building:

    \begin{enumerate}
      \item
        Select a configuration.  This step is optional.  Choose
        \menuselection{Build \sub Select Active Configuration} and
        select either ``example - Win32 Release'' or ``example - Win32
        Debug.''  If you skip this step, V\Cpp{} will use the Debug
        configuration by default.

      \item
        Build the DLL.  Choose \menuselection{Build \sub Build
        example_d.dll} in Debug mode, or \menuselection{Build \sub
        Build example.dll} in Release mode.  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.
    \end{enumerate}

  \item
  \strong{Testing the debug-mode DLL}\\
    Once the Debug build has succeeded, bring up a DOS box, and change
    to the \file{example_nt\textbackslash Debug} directory.  You
    should now be able to repeat the following session (\code{C>} is
    the DOS prompt, \code{>\code{>}>} is the Python prompt; note that
    build information and various debug output from Python may not
    match this screen dump exactly):

\begin{verbatim}
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]
>>>
\end{verbatim}

    Congratulations!  You've successfully built your first Python
    extension module.

  \item
  \strong{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 \module{spam} if its initialization function
    is called \cfunction{initspam()}, and it should call
    \cfunction{Py_InitModule()} with the string \code{"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.dll} or \file{spam.pyd} (the latter is supported
    to avoid confusion with a system library \file{spam.dll} to which
    your module could be a Python interface) in Release mode, or
    \file{spam_d.dll} or \file{spam_d.pyd} in Debug mode.

    Now your options are:

{'fraction_non_alphanumeric': 0.07113483244378335, 'fraction_numerical': 0.006649750634351212, 'mean_word_length': 3.4964594807238396, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 31, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '307588', 'n_tokens_mistral': 3171, 'n_tokens_neox': 3051, 'n_words': 1532}