Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit e743fd0

Browse files
freddrakefreddrake
committed
Rationalize a word-space markup to not break in the LaTeX->*ML
conversion tools currently being constructed. Add a chapter from Jim Fulton on using Misc/Makefile.pre.in. Still preliminary. The "Dynamic Loading" chapter needs to be updated (and possibly removed, since it's no longer an issue for most (any?) users.
1 parent 1cb330c commit e743fd0

1 file changed

Lines changed: 173 additions & 2 deletions

File tree

‎Doc/ext/ext.tex‎

Lines changed: 173 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1243,8 +1243,8 @@ \subsection{NULL Pointers
12431243
other function --- if each function were to test for \NULL{},
12441244
there would be a lot of redundant tests and the code would run slower.
12451245

1246-
It is better to test for \NULL{} only at the ``source'', i.e.\
1247-
when a pointer that may be \NULL{} is received, e.g.\ from
1246+
It is better to test for \NULL{} only at the ``source'', i.e.\ when a
1247+
pointer that may be \NULL{} is received, e.g.\ from
12481248
\cfunction{malloc()} or from a function that may raise an exception.
12491249

12501250
The macros \cfunction{Py_INCREF()} and \cfunction{Py_DECREF()}
@@ -1283,6 +1283,177 @@ \section{Writing Extensions in \Cpp{}
12831283
\samp{__cplusplus} is defined (all recent \Cpp{} compilers define this
12841284
symbol).
12851285

1286+
1287+
1288+
\chapter{Building \C{} and \Cpp{} Extensions on \UNIX{}}
1289+
1290+
\sectionauthor{Fim Fulton}{[email protected]}
1291+
1292+
1293+
%The make file make file, building C extensions on Unix
1294+
1295+
1296+
Starting in Python 1.4, Python provides a special make file for
1297+
building make files for building dynamically-linked extensions and
1298+
custom interpreters. The make file make file builds a make file
1299+
that reflects various system variables determined by configure when
1300+
the Python interpreter was built, so people building module's don't
1301+
have to resupply these settings. This vastly simplifies the process
1302+
of building extensions and custom interpreters on Unix systems.
1303+
1304+
The make file make file is distributed as the file
1305+
\file{Misc/Makefile.pre.in} in the Python source distribution. The
1306+
first step in building extensions or custom interpreters is to copy
1307+
this make file to a development directory containing extension module
1308+
source.
1309+
1310+
The make file make file, \file{Makefile.pre.in} uses metadata
1311+
provided in a file named \file{Setup}. The format of the \file{Setup}
1312+
file is the same as the \file{Setup} (or \file{Setup.in}) file
1313+
provided in the \file{Modules/} directory of the Python source
1314+
distribution. The \file{Setup} file contains variable definitions::
1315+
1316+
\begin{verbatim}
1317+
EC=/projects/ExtensionClass
1318+
\end{verbatim}
1319+
1320+
and module description lines. It can also contain blank lines and
1321+
comment lines that start with \character{\#}.
1322+
1323+
A module description line includes a module name, source files,
1324+
options, variable references, and other input files, such
1325+
as libraries or object files. Consider a simple example::
1326+
1327+
\begin{verbatim}
1328+
ExtensionClass ExtensionClass.c
1329+
\end{verbatim}
1330+
1331+
This is the simplest form of a module definition line. It defines a
1332+
dule, \module{ExtensionClass}, which has a single source file,
1333+
\file{ExtensionClass.c}.
1334+
1335+
Here is a slightly more complex example that uses an \strong{-I}
1336+
option to specify an include directory:
1337+
1338+
\begin{verbatim}
1339+
cPersistence cPersistence.c -I$(EC)
1340+
\end{verbatim}
1341+
1342+
This example also illustrates the format for variable references.
1343+
1344+
For systems that support dynamic linking, the \file{Setup} file should
1345+
begin:
1346+
1347+
\begin{verbatim}
1348+
*shared*
1349+
\end{verbatim}
1350+
1351+
to indicate that the modules defined in \file{Setup} are to be built
1352+
as dynamically-linked linked modules.
1353+
1354+
Here is a complete \file{Setup} file for building a
1355+
\module{cPersistent} module:
1356+
1357+
\begin{verbatim}
1358+
# Set-up file to build the cPersistence module.
1359+
# Note that the text should begin in the first column.
1360+
*shared*
1361+
1362+
# We need the path to the directory containing the ExtensionClass
1363+
# include file.
1364+
EC=/projects/ExtensionClass
1365+
cPersistence cPersistence.c -I$(EC)
1366+
\end{verbatim}
1367+
1368+
After the \file{Setup} file has been created, \file{Makefile.pre.in}
1369+
is run with the \samp{boot} target to create a make file:
1370+
1371+
\begin{verbatim}
1372+
make -f Makefile.pre.in boot
1373+
\end{verbatim}
1374+
1375+
This creates the file, Makefile. To build the extensions, simply
1376+
run the created make file:
1377+
1378+
\begin{verbatim}
1379+
make
1380+
\end{verbatim}
1381+
1382+
It's not necessary to re-run \file{Makefile.pre.in} if the
1383+
\file{Setup} file is changed. The make file automatically rebuilds
1384+
itself if the \file{Setup} file changes.
1385+
1386+
\section{Building Custom Interpreters}
1387+
1388+
The make file built by \file{Makefile.pre.in} can be run with the
1389+
\samp{static} target to build an interpreter:
1390+
1391+
\begin{verbatim}
1392+
make static
1393+
\end{verbatim}
1394+
1395+
Any modules defined in the Setup file before the \samp{*shared*} line
1396+
will be statically linked into the interpreter. Typically, a
1397+
\samp{*shared*} line is omitted from the Setup file when a custom
1398+
interpreter is desired.
1399+
1400+
\section{Module Definition Options}
1401+
1402+
Several compiler options are supported:
1403+
1404+
\begin{tableii}{l|l}{}{Option}{Meaning}
1405+
\lineii{-C}{Tell the C pre-processor not to discard comments}
1406+
\lineii{-D\var{name}=\var{value}}{Define a macro}
1407+
\lineii{-I\var{dir}}{Specify an include directory, \var{dir}}
1408+
\lineii{-L\var{dir}}{Specify a library directory, \var{dir}}
1409+
\lineii{-l\var{lib}}{Link a library, \var{lib}}
1410+
\lineii{-U\var{name}}{Undefine a macro}
1411+
\end{tableii}
1412+
1413+
Other compiler options can be included (snuck in) by putting them
1414+
in variable variables.
1415+
1416+
Source files can include files with \file{.c}, \file{.C}, \file{.cc},
1417+
and \file{.c++} extensions.
1418+
1419+
Other input files include files with \file{.o} or \file{.a}
1420+
extensions.
1421+
1422+
1423+
\section{Example}
1424+
1425+
Here is a more complicated example from \file{Modules/Setup.in}:
1426+
1427+
\begin{verbatim}
1428+
GMP=/ufs/guido/src/gmp
1429+
mpz mpzmodule.c -I$(GMP) $(GMP)/libgmp.a
1430+
\end{verbatim}
1431+
1432+
which could also be written as:
1433+
1434+
\begin{verbatim}
1435+
mpz mpzmodule.c -I$(GMP) -L$(GMP) -lgmp
1436+
\end{verbatim}
1437+
1438+
1439+
\section{Distributing your extension modules
1440+
\label{distributing}}
1441+
1442+
When distributing your extension modules in source form, make sure to
1443+
include a \file{Setup} file. The \file{Setup} file should be named
1444+
\file{Setup.in} in the distribution. The make file make file,
1445+
\file{Makefile.pre.in}, will copy \file{Setup.in} to \file{Setup}.
1446+
Distributing a \file{Setup.in} file makes it easy for people to
1447+
customize the \file{Setup} file while keeping the original in
1448+
\file{Setup.in}.
1449+
1450+
It is a good idea to include a copy of \file{Makefile.pre.in} for
1451+
people who do not have a source distribution of Python.
1452+
1453+
Do not distribute a make file. People building your modules
1454+
should use \file{Makefile.pre.in} to build their own make file.
1455+
1456+
12861457
\chapter{Embedding Python in Another Application
12871458
\label{embedding}}
12881459

0 commit comments

Comments
 (0)