boost/python
2
0
Fork 0
mirror of https://github.com/boostorg/python.git synced 2026-01-27 19:12:16 +00:00
Code Issues Projects Releases Wiki Activity

Tutorials...

Browse Source 
[SVN r15818]
This commit is contained in:
Joel de Guzman
2002-10-09 07:44:34 +00:00
parent e49e0d2705
commit a295ac6590
4 changed files with 302 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

129
doc/tutorial/doc/building_hello_world.html
View File

@@ -28,10 +28,131 @@
Now the first thing you'd want to do is to build the Hello World module and
try it for yourself in Python. In this section, we shall outline the steps
necessary to achieve that. We shall use the build tool that comes bundled
with every boost distribution: <b>bjam</b>. For a complete reference to building
Boost.Python, check out: <a href="../../building.html">
building.html</a></p>
<table border="0">
with every boost distribution: <b>bjam</b>.</p>
<p>
We shall skip over the details. Our objective will be to simply create the
hello world module and run it in Python. For a complete reference to
building Boost.Python, check out: <a href="../../building.html">
building.html</a>.
After this brief <i>bjam</i> tutorial, we should have built two DLLs:</p>
<ul><li>boost_python.dll</li><li>hello.pyd</li></ul><p>
This assumes of course that we are running on Windows.</p>
<p>
The tutorial example can be found in the directory:
<tt>/libs/python/example/tutorial</tt>. There, you can find:</p>
<ul><li>hello.cpp</li><li>Jamfile</li></ul><p>
The <tt>hello.cpp</tt> file is our C++ hello world example. The <tt>Jamfile</tt> is a
minimalist <i>bjam</i> script that builds the DLLs for us.</p>
<p>
Before anything else, you should have the bjam executable in your boost
directory. Pre-built Boost.Jam executables are available for some
platforms. For example, a pre-built Microsoft Windows bjam executable can
be downloaded <a href="http://boost.sourceforge.net/jam-executables/bin.ntx86/bjam.zip">
here</a>.
The complete list of bjam pre-built executables can be found <a href="../../../../../tools/build/index.html#Jam">
here</a>.</p>
<a name="lets_jam_"></a><h2>Lets Jam!</h2><p>
Here is our minimalist Jamfile:</p>
<code><pre>
subproject libs/python/example/tutorial ;
SEARCH on python.jam = $(BOOST_BUILD_PATH) ;
include python.jam ;
extension hello # Declare a Python extension called hello
: hello.cpp # source
&lt;dll&gt;../../build/boost_python # dependencies
;
</pre></code><p>
First, we need to specify our location in the boost project hierarchy.
It so happens that the tutorial example is located in <tt>/libs/python/example/tutorial</tt>.
Thus:</p>
<code><pre>
subproject libs/python/example/tutorial ;
</pre></code><p>
Then we will include the definitions needed by Python modules:</p>
<code><pre>
SEARCH on python.jam = $(BOOST_BUILD_PATH) ;
include python.jam ;
</pre></code><p>
Finally we declare our <tt>hello</tt> extension:</p>
<code><pre>
extension hello # Declare a Python extension called hello
: hello.cpp # source
&lt;dll&gt;../../build/boost_python # dependencies
;
</pre></code><a name="running_bjam"></a><h2>Running bjam</h2><p>
<i>bjam</i> is run using your operating system's command line interpreter.</p>
<blockquote><p>Start it up.</p></blockquote><p>
Make sure that the environment is set so that we can invoke the C++
compiler. With MSVC, that would mean running the <tt>Vcvars32.bat</tt> batch
file. For instance:</p>
<code><pre>
<span class=identifier>C</span><span class=special>:\</span><span class=identifier>Program </span><span class=identifier>Files</span><span class=special>\</span><span class=identifier>Microsoft </span><span class=identifier>Visual </span><span class=identifier>Studio</span><span class=special>\</span><span class=identifier>VC98</span><span class=special>\</span><span class=identifier>bin</span><span class=special>\</span><span class=identifier>Vcvars32</span><span class=special>.</span><span class=identifier>bat
</span></pre></code>
<p>
Some environment variables will have to be setup for proper building of our
Python modules. Example:</p>
<code><pre>
<span class=identifier>set </span><span class=identifier>PYTHON_ROOT</span><span class=special>=</span><span class=identifier>c</span><span class=special>:/</span><span class=identifier>dev</span><span class=special>/</span><span class=identifier>tools</span><span class=special>/</span><span class=identifier>python
</span><span class=identifier>set </span><span class=identifier>PYTHON_VERSION</span><span class=special>=</span><span class=number>2.2
</span></pre></code>
<p>
The above assumes that the Python installation is in <tt>c:/dev/tools/python</tt>
and that we are using Python version 2.2. Be sure not to include a third
number, e.g. <b>not</b> &quot;2.2.1&quot;, even if that's the version you have.</p>
<p>
Now we are ready... Be sure to <tt>cd</tt> to <tt>libs/python/example/tutorial</tt>
where the tutorial <tt>&quot;hello.cpp&quot;</tt> and the <tt>&quot;Jamfile&quot;</tt> is situated.</p>
<p>
Finally:</p>
<code><pre>
<span class=identifier>bjam </span><span class=special>-</span><span class=identifier>sTOOLS</span><span class=special>=</span><span class=identifier>msvc
</span></pre></code>
<p>
We are again assuming that we are using Microsoft Visual C++ version 6. If
not, then you will have to specify the appropriate tool. See
<a href="../../../../../tools/build/index.html">
Building Boost Libraries</a> for
further details.</p>
<p>
It should be building now:</p>
<code><pre>
cd C:\dev\boost\libs\python\example\tutorial
bjam -sTOOLS=msvc
...patience...
...found 1703 targets...
...updating 40 targets...
</pre></code><p>
And so on... Finally:</p>
<code><pre>
vc-C++ ..\..\..\..\libs\python\example\tutorial\bin\hello.pyd\msvc\debug\
runtime-link-dynamic\hello.obj
hello.cpp
vc-Link ..\..\..\..\libs\python\example\tutorial\bin\hello.pyd\msvc\debug\
runtime-link-dynamic\hello.pyd ..\..\..\..\libs\python\example\tutorial\bin\
hello.pyd\msvc\debug\runtime-link-dynamic\hello.lib
Creating library ..\..\..\..\libs\python\example\tutorial\bin\hello.pyd\
msvc\debug\runtime-link-dynamic\hello.lib and object ..\..\..\..\libs\python\
example\tutorial\bin\hello.pyd\msvc\debug\runtime-link-dynamic\hello.exp
...updated 40 targets...
</pre></code><p>
If all is well, you should now have:</p>
<ul><li>boost_python.dll</li><li>hello.pyd</li></ul><p>
<tt>boost_python.dll</tt> can be found somewhere in <tt>libs\python\build\bin</tt>
while <tt>hello.pyd</tt> can be found somewhere in
<tt>libs\python\example\tutorial\bin</tt>. After a successful build, you can just
link in these DLLs with the Python interpreter. In Windows for example, you
can simply put these libraries inside the directory where the Python
executable is.</p>
<p>
You may now fire up Python and run our hello module:</p>
<code><pre>
<span class=special>&gt;&gt;&gt; </span><span class=identifier>import </span><span class=identifier>hello
</span><span class=special>&gt;&gt;&gt; </span><span class=identifier>print </span><span class=identifier>hello</span><span class=special>.</span><span class=identifier>greet</span><span class=special>()
</span><span class=identifier>hello</span><span class=special>, </span><span class=identifier>world
</span></pre></code>
<blockquote><p><b>There you go... Have fun!</b></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"><a href="quickstart.html"><img src="theme/l_arr.gif" border="0"></a></td>

147
doc/tutorial/doc/quickstart.txt
View File

@@ -55,8 +55,151 @@ resulting DLL is now visible to Python. Here's a sample Python session:
Now the first thing you'd want to do is to build the Hello World module and
try it for yourself in Python. In this section, we shall outline the steps
necessary to achieve that. We shall use the build tool that comes bundled
with every boost distribution: [*bjam]. For a complete reference to building
Boost.Python, check out: [@../../building.html building.html]
with every boost distribution: [*bjam].
We shall skip over the details. Our objective will be to simply create the
hello world module and run it in Python. For a complete reference to
building Boost.Python, check out: [@../../building.html building.html].
After this brief ['bjam] tutorial, we should have built two DLLs:
* boost_python.dll
* hello.pyd
This assumes of course that we are running on Windows.
The tutorial example can be found in the directory:
[^/libs/python/example/tutorial]. There, you can find:
* hello.cpp
* Jamfile
The [^hello.cpp] file is our C++ hello world example. The [^Jamfile] is a
minimalist ['bjam] script that builds the DLLs for us.
Before anything else, you should have the bjam executable in your boost
directory. Pre-built Boost.Jam executables are available for some
platforms. For example, a pre-built Microsoft Windows bjam executable can
be downloaded [@http://boost.sourceforge.net/jam-executables/bin.ntx86/bjam.zip here].
The complete list of bjam pre-built executables can be found [@../../../../../tools/build/index.html#Jam here].
[h2 Lets Jam!]
Here is our minimalist Jamfile:
[pre
subproject libs/python/example/tutorial ;
SEARCH on python.jam = $(BOOST_BUILD_PATH) ;
include python.jam ;
extension hello # Declare a Python extension called hello
: hello.cpp # source
<dll>../../build/boost_python # dependencies
;
]
First, we need to specify our location in the boost project hierarchy.
It so happens that the tutorial example is located in [^/libs/python/example/tutorial].
Thus:
[pre
subproject libs/python/example/tutorial ;
]
Then we will include the definitions needed by Python modules:
[pre
SEARCH on python.jam = $(BOOST_BUILD_PATH) ;
include python.jam ;
]
Finally we declare our [^hello] extension:
[pre
extension hello # Declare a Python extension called hello
: hello.cpp # source
<dll>../../build/boost_python # dependencies
;
]
[h2 Running bjam]
['bjam] is run using your operating system's command line interpreter.
[:Start it up.]
Make sure that the environment is set so that we can invoke the C++
compiler. With MSVC, that would mean running the [^Vcvars32.bat] batch
file. For instance:
C:\Program Files\Microsoft Visual Studio\VC98\bin\Vcvars32.bat
Some environment variables will have to be setup for proper building of our
Python modules. Example:
set PYTHON_ROOT=c:/dev/tools/python
set PYTHON_VERSION=2.2
The above assumes that the Python installation is in [^c:/dev/tools/python]
and that we are using Python version 2.2. Be sure not to include a third
number, e.g. [*not] "2.2.1", even if that's the version you have.
Now we are ready... Be sure to [^cd] to [^libs/python/example/tutorial]
where the tutorial [^"hello.cpp"] and the [^"Jamfile"] is situated.
Finally:
bjam -sTOOLS=msvc
We are again assuming that we are using Microsoft Visual C++ version 6. If
not, then you will have to specify the appropriate tool. See
[@../../../../../tools/build/index.html Building Boost Libraries] for
further details.
It should be building now:
[pre
cd C:\dev\boost\libs\python\example\tutorial
bjam -sTOOLS=msvc
...patience...
...found 1703 targets...
...updating 40 targets...
]
And so on... Finally:
[pre
vc-C++ ..\..\..\..\libs\python\example\tutorial\bin\hello.pyd\msvc\debug\
runtime-link-dynamic\hello.obj
hello.cpp
vc-Link ..\..\..\..\libs\python\example\tutorial\bin\hello.pyd\msvc\debug\
runtime-link-dynamic\hello.pyd ..\..\..\..\libs\python\example\tutorial\bin\
hello.pyd\msvc\debug\runtime-link-dynamic\hello.lib
Creating library ..\..\..\..\libs\python\example\tutorial\bin\hello.pyd\
msvc\debug\runtime-link-dynamic\hello.lib and object ..\..\..\..\libs\python\
example\tutorial\bin\hello.pyd\msvc\debug\runtime-link-dynamic\hello.exp
...updated 40 targets...
]
If all is well, you should now have:
* boost_python.dll
* hello.pyd
[^boost_python.dll] can be found somewhere in [^libs\python\build\bin]
while [^hello.pyd] can be found somewhere in
[^libs\python\example\tutorial\bin]. After a successful build, you can just
link in these DLLs with the Python interpreter. In Windows for example, you
can simply put these libraries inside the directory where the Python
executable is.
You may now fire up Python and run our hello module:
>>> import hello
>>> print hello.greet()
hello, world
[:[*There you go... Have fun!]]
[page Exposing Classes]

15
example/tutorial/Jamfile Normal file
View File

@@ -0,0 +1,15 @@
# Hello World Example from the tutorial
# [Joel de Guzman 10/9/2002]
# Specify our location in the boost project hierarchy
subproject libs/python/example/tutorial ;
# Include definitions needed for Python modules
SEARCH on python.jam = $(BOOST_BUILD_PATH) ;
include python.jam ;
extension hello # Declare a Python extension called hello
: hello.cpp # source
<dll>../../build/boost_python # dependencies
;

17
example/tutorial/hello.cpp Normal file
View File

@@ -0,0 +1,17 @@
// Hello World Example from the tutorial
// [Joel de Guzman 10/9/2002]
char const* greet()
{
return "hello, world";
}
#include <boost/python/module.hpp>
#include <boost/python/def.hpp>
using namespace boost::python;
BOOST_PYTHON_MODULE(hello)
{
def("greet", greet);
}