forked from boostorg/python
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathembedding.html
More file actions
78 lines (76 loc) · 4.66 KB
/
Copy pathembedding.html
File metadata and controls
78 lines (76 loc) · 4.66 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
<html>
<head>
<!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc -->
<title>Embedding</title>
<link rel="stylesheet" href="theme/style.css" type="text/css">
<link rel="next" href="using_the_interpreter.html">
</head>
<body>
<table width="100%" height="48" border="0" background="theme/bkd2.gif" cellspacing="2">
<tr>
<td width="10">
</td>
<td width="85%">
<font size="6" face="Verdana, Arial, Helvetica, sans-serif"><b>Embedding</b></font>
</td>
<td width="112"><a href="http://spirit.sf.net"><img src="theme/spirit.gif" align="right" border="0"></a></td>
</tr>
</table>
<br>
<table border="0">
<tr>
<td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
<td width="30"><img src="theme/l_arr_disabled.gif" border="0"></td>
<td width="20"><a href="using_the_interpreter.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<p>
By now you should know how to use Boost.Python to call your C++ code from Python. However, sometimes you may need to do the reverse: call Python code from the C++-side. This requires you to <i>embed</i> the Python interpreter into your C++ program. </p>
<p>
Currently, Boost.Python does not directly support everything you'll need when embedding. Therefore you'll need to use the <a href="http://www.python.org/doc/current/api/api.html">
Python/C API</a> to fill in the gaps. However, Boost.Python already makes embedding a lot easier and, in a future version, it may become unnecessary to touch the Python/C API at all. So stay tuned... <img src="theme/smiley.gif"></img></p>
<a name="building_embedded_programs"></a><h2>Building embedded programs</h2><p>
To be able to use embedding in your programs, they have to be linked to both Boost.Python's and Python's static link library. </p>
<p>
Boost.Python's static link library comes in two variants. Both are located in Boost's <tt>/libs/python/build/bin-stage</tt> subdirectory. On Windows, the variants are called <tt>boost_python.lib</tt> (for release builds) and <tt>boost_python_debug.lib</tt> (for debugging). If you can't find the libraries, you probably haven't built Boost.Python yet. See <a href="../../building.html">
Building and Testing</a> on how to do this.</p>
<p>
Python's static link library can be found in the <tt>/libs</tt> subdirectory of your Python directory. On Windows it is called pythonXY.lib where X.Y is your major Python version number. </p>
<p>
Additionally, Python's <tt>/include</tt> subdirectory has to be added to your include path.</p>
<p>
In a Jamfile, all the above boils down to:</p>
<code><pre>
projectroot c:\projects\embedded_program ; # location of the program
# bring in the rules for python
SEARCH on python.jam = $(BOOST_BUILD_PATH) ;
include python.jam ;
exe embedded_program # name of the executable
: #sources
embedded_program.cpp
: # requirements
<find-library>boost_python <library-path>c:\boost\libs\python
$(PYTHON_PROPERTIES)
<library-path>$(PYTHON_LIB_PATH)
<find-library>$(PYTHON_EMBEDDED_LIBRARY) ;
</pre></code><a name="getting_started"></a><h2>Getting started</h2><p>
Being able to build is nice, but there is nothing to build yet. Embedding the Python interpreter into one of your C++ programs requires these 4 steps:</p>
<ol><li>#include <tt><boost/python.hpp></tt><br><br></li><li>Call <a href="http://www.python.org/doc/current/api/initialization.html#l2h-652">
Py_Initialize</a>() to start the interpreter and create the <tt>__main__</tt> module.<br><br></li><li>Call other Python C API routines to use the interpreter.<br><br></li><li>Call <a href="http://www.python.org/doc/current/api/initialization.html#l2h-656">
Py_Finalize</a>() to stop the interpreter and release its resources.</li></ol><p>
(Of course, there can be other C++ code between all of these steps.)</p>
<blockquote><p><i><b>Now that we can embed the interpreter in our programs, lets see how to put it to use...</b></i></p></blockquote><table border="0">
<tr>
<td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
<td width="30"><img src="theme/l_arr_disabled.gif" border="0"></td>
<td width="20"><a href="using_the_interpreter.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<br>
<hr size="1"><p class="copyright">Copyright © 2002-2003 Dirk Gerrits <br><br>
<font size="2">Permission to copy, use, modify, sell and distribute this document
is granted provided this copyright notice appears in all copies. This document
is provided "as is" without express or implied warranty, and with
no claim as to its suitability for any purpose. </font> </p>
</body>
</html>