diff options
author | Hugo Lima <hugo.lima@openbossa.org> | 2009-11-03 20:10:09 -0200 |
---|---|---|
committer | Hugo Lima <hugo.lima@openbossa.org> | 2009-11-03 20:10:09 -0200 |
commit | dea207ee699d9d4e9abbe034b7b035df1161613b (patch) | |
tree | c233903ef076cabd9956b52420e7a9cf425041a4 /doc | |
parent | 2d8b5d3467e34757bf462211e7bbd8e4e1453ac3 (diff) |
Removed useless/outdated/wrong documentation from shiboken.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/_templates/index.html | 21 | ||||
-rw-r--r-- | doc/compiling.rst | 2 | ||||
-rw-r--r-- | doc/compiling/cmake-primer.rst | 68 | ||||
-rw-r--r-- | doc/compiling/compiling.rst | 9 | ||||
-rw-r--r-- | doc/compiling/setup-apiextractor.rst | 56 | ||||
-rw-r--r-- | doc/compiling/setup-generator.rst | 54 | ||||
-rw-r--r-- | doc/contents.rst | 5 | ||||
-rw-r--r-- | doc/faq.rst | 55 | ||||
-rw-r--r-- | doc/overview.rst | 46 | ||||
-rw-r--r-- | doc/tutorial/bindinglibfoo.rst | 76 | ||||
-rw-r--r-- | doc/tutorial/buildingthebinding.rst | 133 | ||||
-rw-r--r-- | doc/tutorial/globalheader.rst | 36 | ||||
-rw-r--r-- | doc/tutorial/images/generatorworkings.png | bin | 37257 -> 0 bytes | |||
-rw-r--r-- | doc/tutorial/images/generatorworkings.svg | 392 | ||||
-rw-r--r-- | doc/tutorial/introduction.rst | 31 | ||||
-rw-r--r-- | doc/tutorial/libfoo.rst | 68 | ||||
-rw-r--r-- | doc/tutorial/typesystemcreation.rst | 136 |
17 files changed, 12 insertions, 1176 deletions
diff --git a/doc/_templates/index.html b/doc/_templates/index.html index f1a289077..8492c3ae5 100644 --- a/doc/_templates/index.html +++ b/doc/_templates/index.html @@ -1,34 +1,25 @@ {% extends "layout.html" %} {% set title = 'Overview' %} {% block body %} +<div class="section"> <h1>{{ project }} {{ version }}</h1> - <p>{{ project }} is a tool that eases the development of Python bindings for Qt-based libraries by - automating most of the process. It relies heavily on the ApiExtractor library to parse the - header files and manipulate the classes information while generating the code. This generated - code uses the - <a href="http://www.boost.org/doc/libs/1_39_0/libs/python/doc/index.html">Boost::Python library</a> - in order to bridge the C++ library and Python.</p> - - <p>{{ project }} is based on the - <a href="http://labs.trolltech.com/page/Projects/QtScript/Generator">QtScriptGenerator</a> project.</p> + <p>{{ project }} is a plugin for Generator Runner, thsi generator generates CPython code instead of boost::python code as BoostPythonGenerator does.</p> <h2>Documentation</h2> <table class="contentstable" align="center" style="margin-left: 30px"><tr> <td width="50%"> - <p class="biglink"><a class="biglink" href="{{ pathto("overview") }}">Overview</a><br/> - <span class="linkdescr">how generator works</span></p> - <p class="biglink"><a class="biglink" href="{{ pathto("tutorial/introduction") }}">Tutorial</a><br/> - <span class="linkdescr">start here</span></p> <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Contents</a><br/> <span class="linkdescr">for a complete overview</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("sequenceprotocol") }}">Sequence Protocol</a><br/> + <span class="linkdescr">support for python sequence protocol</span></p> </td> <td width="50%"> - <p class="biglink"><a class="biglink" href="{{ pathto("compiling/compiling") }}">Compiling/Installing</a><br/> + <p class="biglink"><a class="biglink" href="{{ pathto("compiling") }}">Compiling/Installing</a><br/> <span class="linkdescr">how to compile and install {{ project }}</span></p> <p class="biglink"><a class="biglink" href="{{ pathto("faq") }}">FAQ</a><br/> <span class="linkdescr">answers for frequent asked questions</span></p> </td></tr> </table> - +</div> {% endblock %} diff --git a/doc/compiling.rst b/doc/compiling.rst new file mode 100644 index 000000000..510b22ba3 --- /dev/null +++ b/doc/compiling.rst @@ -0,0 +1,2 @@ +Compiling +--------- diff --git a/doc/compiling/cmake-primer.rst b/doc/compiling/cmake-primer.rst deleted file mode 100644 index 884cf15c1..000000000 --- a/doc/compiling/cmake-primer.rst +++ /dev/null @@ -1,68 +0,0 @@ - -.. _cmake-primer: - -************ -CMake primer -************ - -This chapter will is a basic introduction to CMake, the build system -used by PyQtB and the binding generator. - -The practical steps will be focusing in using cmake in a unix-like -(GNU/Linux) environment. - - -Configuring -=========== - -Project file - CMakeLists.txt ------------------------------ - -CMake parses the file CMakeLists.txt for information about the project, -like project name, dependencies, what should be compiled, what should be -shipped. - - -CMake variables ---------------- - -CMake can have its default behavior modified by providing some - -* ``CMAKE_INSTALL_PREFIX=<some path here>`` sets the install prefix to - the specified path. -* ``CMAKE_MODULE_PATH=<some path here>`` sets the extra directories - where CMake will try to find its modules. -* ``CMAKE_TOOLCHAIN_FILE=<file path>`` sets the path to the file that - describes the toolchain used to compile this project. Is is very useful - when using CMake with icecc to speedup compilation. - -You can define a variable using the ``-D<VARIABLE>`` switch. - -Invoking CMake --------------- - -After writing the CMakeLists.txt and deciding which flags will be used, -you can invoke CMake using:: - - cmake <CMake flags> <path to toplevel CMakeLists.txt file> - -For example, if you use the ``build/`` folder to build the project and -want it to be installed into ``/opt/sandbox/``, use the following lines:: - - cd build/ - cmake -DCMAKE_INSTALL_PREFIX=/opt/sandbox .. - -CMake will process the project file and write the output files in the -current directory - -Building -======== - -After the configuration process, the Makefiles are written and you can build -the project using :program:`make`. - -Installing -========== - -As in the building process, ``make install`` will install the files into -the target directory. diff --git a/doc/compiling/compiling.rst b/doc/compiling/compiling.rst deleted file mode 100644 index 638efa91a..000000000 --- a/doc/compiling/compiling.rst +++ /dev/null @@ -1,9 +0,0 @@ -Compiling -********* - -.. toctree:: - :maxdepth: 3 - - cmake-primer - setup-apiextractor - setup-generator diff --git a/doc/compiling/setup-apiextractor.rst b/doc/compiling/setup-apiextractor.rst deleted file mode 100644 index 68c162f8b..000000000 --- a/doc/compiling/setup-apiextractor.rst +++ /dev/null @@ -1,56 +0,0 @@ - -.. _api-extractor: - -************** -API Extractor -************** - -Overview -======== - -The **API Extractor** library is used by the binding generator to -parse the header and typesystem files to create an internal -representation of the API. It is based on the QtScriptGenerator -codebase. - -Getting the sources -=================== - -.. todo:: - Replace with the OSS project repo info - -* Git URL: https://dvcs.projects.maemo.org/git/python/apiextractor -* Web interface: https://dvcs.projects.maemo.org/git/?p=python/apiextractor - -To checkout the most updated version, use the following command:: - - $ git clone https://dvcs.projects.maemo.org/git/python/apiextractor/ - -Build requirements -================== - -* Qt4.5 development headers and libraries >= 4.5.0 -* libboost-graph >= 1.38.0 -* cmake >= 2.6.0 - -Building and installing -======================= - -To build and install just follow the generic cmake instructions in section -:ref:`cmake-primer`. - -Debian packaging -================ - -In order to compile this package in a debian environment, make sure the -following packages are installed: - -* debhelper (>= 5) -* cdbs -* cmake (>= 2.6.0) -* libboost-graph1.38-dev (>= 1.38.0) -* libqt4-dev (>= 4.5) - -And then you can build the package using:: - - $ dpkg-buildpackage -rfakeroot diff --git a/doc/compiling/setup-generator.rst b/doc/compiling/setup-generator.rst deleted file mode 100644 index 28fe2fbb3..000000000 --- a/doc/compiling/setup-generator.rst +++ /dev/null @@ -1,54 +0,0 @@ - -.. _python-bindings-generator: - -************************* -Python Bindings Generator -************************* - -Overview -========================================= - -The **Python Bindings Generator** (A.K.A. :program:`shiboken`) is -the program that creates the bindings source files from Qt headers and -auxiliary files (typesystems, ``global.h`` and glue files). It makes -heavy use of the :ref:`api-extractor` library. - - -Getting the sources -=================== - -* Git URL: https://dvcs.projects.maemo.org/git/python/shiboken -* Web interface: https://dvcs.projects.maemo.org/git/?p=python/shiboken - -To checkout the most updated version, use the following command:: - - $ git svn clone https://dvcs.projects.maemo.org/git/?p=python/shiboken - -Build requirements -================== - -+ CMake >= 2.6.0 -+ Qt4.5 libraries and development headers >= 4.5.0 -+ :ref:`api-extractor` + development headers - -Building and installing -======================= - -To build and install just follow the generic cmake instructions in -section :ref:`cmake-primer`. - -Debian packaging -================ - -In order to compile this package in a debian environment, make sure the -following packages are installed: - -* debhelper (>= 5) -* cdbs -* cmake (>= 2.6.0) -* libqt4-dev (>= 4.5) -* libapiextractor-dev (>= 0.1) - -And then you can build the package using:: - - $ dpkg-buildpackage -rfakeroot diff --git a/doc/contents.rst b/doc/contents.rst index 31d16dc9d..057191204 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -4,7 +4,6 @@ Table of contents :numbered: :maxdepth: 3 - overview.rst faq.rst - tutorial/introduction.rst - compiling/compiling.rst + sequenceprotocol.rst + compiling.rst diff --git a/doc/faq.rst b/doc/faq.rst index 38cc3f186..469e9651b 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -8,52 +8,19 @@ suggest new entries! General ======= -What is the generator? ----------------------- +What is Shiboken? +----------------- Here the name generator refers actually to a program composed of a set of *generator classes* that output different resources based on information contained inside C++ header files. -What is the API Extractor? --------------------------- - -It is a library that parses C++ header files and builds a data model around -them in order to ease the work of manipulating these data inside -*generators*. - - -Is there any similar tools around? ----------------------------------- - -The generator framework actually started as a fork of the qtscriptgenerator, -with the focus on python bindings instead of QtScript. After some time, the -python-specific code was split from the the header parsing and data model -code. The former became what we call *generator* while the latter is now -called *API Extractor*. - -What's the relationship between the generator and the API Extractor? --------------------------------------------------------------------- - -The generator system relies heavily in the API Extractor classes, using -them as syntatic sugar to access the data model of the classes being -wrapped. - -What are the dependencies to run the generator? ------------------------------------------------ - -API Extractor, QtCore and QtXml. - Creating bindings ================= Can I wrap non-Qt libraries? ---------------------------- -Although it's not yet well tested, there's a good chance that non-Qt -libraries can be wrapped using the generator. But remember that -generator injects runtime dependency on Qt for the generated binding. - Is there any runtime dependency on the generated binding? --------------------------------------------------------- @@ -87,21 +54,3 @@ What is 'inject code'? That's how we call customized code that will be *injected* into the generated at specific locations. They are specified inside the typesytem. -How can I document my project? ------------------------------- - -The generator also can generate the API documentation based on the -C++ headers documentation using the qdoc syntax. Optionally you can -inject documentation at specific parts. Likewise *inject code*, the -customized documentation is specified inside the typesystem. - -Other -===== - -Is there any current limitation within the generator/API Extractor? -------------------------------------------------------------------- - -The generator currently does not automatically detects implicit C++ -type conversions. Also the code snippets in function signature and -examples are still in C++ inside the generated documentation. - diff --git a/doc/overview.rst b/doc/overview.rst deleted file mode 100644 index 2ceb42fb8..000000000 --- a/doc/overview.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. _gen-overview: - -****************** -Generator Overview -****************** - -In a few words, the Generator is a system that -parses a collecion of header and typesystem files, generating other -files (code, documentation, etc.) as result. - -Creating new bindings -===================== - -.. figure:: images/bindinggen-development.png - :scale: 80 - :align: center - - Creating new bindings - -Each module of the generator system has a specific role. - -1. Provide enough data about the classes and functions. -2. Generate valid code, with modifications from typesystems and - injected codes. -3. Modify the API to expose the objects in a Python-friendly way. -4. Insert customizations where handwritten code is needed. - -.. figure:: images/boostqtarch.png - :scale: 80 - :align: center - - Runtime architecture - -Handwritten inputs -================== - -Creating new bindings involves creating two pieces of "code": -The typesystem and the inject code. - -:typesystem: XML files that provides the developer with a tool to - customize the way that the generators will see the classes - and functions. For example, functions can be renamed, have - its signature changed and many other actions. -:inject code: allows the developer to insert handwritten code where - the generated code is not suitable or needs some customization. - diff --git a/doc/tutorial/bindinglibfoo.rst b/doc/tutorial/bindinglibfoo.rst deleted file mode 100644 index fc256fbaa..000000000 --- a/doc/tutorial/bindinglibfoo.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. highlight:: xml - -.. _gentut-bindinglibfoo: - -Binding libfoo with the Generator -================================= - -In order to create bindings for a library based on Qt4 a number of components -must be available in the system. - - + Qt4 library (with headers and pkg-config .pc files for development -- the - ``-dev`` packages in a Debian distribution). - + Qt4 Python bindings made with **boostgenerator**. - + Typesystems for the Qt4 Python bindings. - + Headers for the library to be bound. - -With the above listed in place the developer must write the components from -where the generator will gather information to create the binding source code. - - + Typesystem file describing the way the binding must be done. - + **global.h** including all the **libfoo** headers and defining required macros. - + A build system to direct the process of generating, compiling and linking the binding. - -The directory structure for the binding project could be something like the tree -shown below: - -:: - - foobinding/ - |-- data/ - `-- module_dir/ - `-- glue/ - - -The **data** directory should contain the **global.h** and the typesystem -file. This typesystem need to refer to the ones used to create the Qt4 bindings, -commonly located on **/usr/share/PyQtB/typesystem**, the exact location -can be checked with pkg-config: - -:: - - $ pkg-config qt4python --variable=typesystemdir - - -The **module_dir** directory is the place where the sources generated should -be placed. It starts empty except for the build instructions file (Makefile, -Makefile.am, CMakeLists.txt, etc). The realname of this directory must be the -same written in the typesystem file: - -:: - - <typesystem package="module_dir"> - - -If there is any need for handwritten source code longer than a couple of lines, -making them unconfortable to be put on the typesystem xml file, the sources -could be orderly placed in a **glue** directory, also referred in the -new binding typesystem. - -When writing the typesystem file (more on this later) there is no need to refer -to the other required typesystem files with absolute paths, the locations where -they can be found could be passed to the generator through a command line -option (``--typesystem-paths=PATH1:PATH2:[...]``) or the environment variable -**TYPESYSTEMPATH**. - -For **libfoo** no glue code will be needed so this directory is not used, -the other directories are created with proper names. - -:: - - foobinding/ - |-- data/global.h - | `-- typesystem_foo.xml - `-- foo/ - `-- Makefile - diff --git a/doc/tutorial/buildingthebinding.rst b/doc/tutorial/buildingthebinding.rst deleted file mode 100644 index bc60fe284..000000000 --- a/doc/tutorial/buildingthebinding.rst +++ /dev/null @@ -1,133 +0,0 @@ -.. _gentut-buildingthebinding: - -Building The Binding -==================== - -As mentioned before the build system used must perform the following tasks -in the correct order: - - + Gather data about locations of headers and external needed typesystems. - + Run the generator with the correct parameters. - + Compile and link the binding. - -The first and last are the usual, being the second the only novelty in the -process. - -Running the Generator ---------------------- - -The generator is called with the following parameters and options: - -:: - - $ boostgenerator global_headers.h \ - --include-paths=$(PATHS_TO_HEADERS)) \ - --typesystem-paths=$(PATHS_TO_TYPESYSTEMS) \ - --output-directory=. \ - typesystem.xml - -Notice that the variables for include and typesystem paths could be determined -at build time with the pkg-config tool. - -Collecting information with pkg-config -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The Qt4 bindings include compile and build information through the pkg-config -mechanism. The pkg-config name for Qt4 Python bindings is **qt4python** and a -simple ``pkg-config qt4python --cflags --libs`` will retrieve the information -needed to build the new binding. - -The Qt4 bindings file ``qt4python.pc`` for the use of pkg-config requires -the ``.pc`` files from Qt4 to be installed. If the library is in an unusual -location, e.g. ``/opt/qt45``, remember to export it to the ``PKG_CONFIG_PATH`` -environment variable. -For example: ``export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/opt/qt45/lib/pkgconfig`` - -There is a vital information also available through pkg-config: -the **typesystemdir** variable. It is used like this: -``pkg-config qt4python --variable=typesystemdir`` This provides information -where to find the typesystem files used to create the Qt4 bindings, and as said -before the binding being created needs this to complement its own binding -information for the generation proccess. - -Makefile --------- - -Below is a plain Makefile for the binding project. - -**foobinding/foo/Makefile** -:: - - LIBTEST_DIR = ../../libfoo - LIBS = -lboost_python-gcc43-1_38-py25 -lpython2.5 \ - `pkg-config qt4python --libs` \ - -lfoo -L$(LIBTEST_DIR) \ - -lpthread -ldl -lutil - CFLAGS = -I/usr/share/qt4/mkspecs/linux-g++ -I. \ - -I$(LIBTEST_DIR) \ - `pkg-config qt4python --cflags` \ - -I/usr/include/python2.5\ - -I/usr/include/boost/python - QT4TYPESYSTEM_DIR = `pkg-config --variable=typesystemdir qt4python` - QT4HEADER_DIRS = `pkg-config --variable=includedir QtCore`:`pkg-config --variable=includedir QtCore`/.. - - SOURCES = math_wrapper.cpp foo_module_wrapper.cpp foo_global_functions_wrapper.cpp - OBJECTS = math_wrapper.o foo_module_wrapper.o foo_global_functions_wrapper.o - - all: generate compile link - - generate: - boostgenerator ../data/global.h \ - --include-paths=$(LIBTEST_DIR):$(QT4HEADER_DIRS):/usr/include \ - --typesystem-paths=../data:$(QT4TYPESYSTEM_DIR) \ - --output-directory=.. \ - ../data/typesystem_foo.xml - - compile: $(SOURCES) - g++ -fPIC -DPIC $(CFLAGS) math_wrapper.cpp -c - g++ -fPIC -DPIC $(CFLAGS) foo_global_functions_wrapper.cpp -c - g++ -fPIC -DPIC $(CFLAGS) foo_module_wrapper.cpp -c - - link: - g++ -shared -Wl,-soname,foo.so -o foo.so $(LIBS) $(OBJECTS) - - test: - LD_LIBRARY_PATH=$(LIBTEST_DIR) python -c \ - "import foo; print dir(foo); m = foo.Math(); print m.squared(5)" - - clean: - rm -rf *.o *.so *.?pp *.log - - -Keepe in mind that the Makefile above expects the ``libfoo`` and -``foobinding`` directories to be in the same level in the directory -hierarchy, remember to change any path references accordingly if -you choose to change things. - -**Warning:** - The order in which the link flags are passed matters. - **libboost_python** must come first, otherwise weeping - and gnashing of teeth will follow. - -Testing the Binding -------------------- -Now compile the binding with ``make``: - -:: - - $ cd foobinding/foo - $ make - -To test if the new binding is working (it can pass the build phase but still -blow up at runtime) start up a Python terminal and import it by the name. - -:: - - $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/libfoo/shared/object/dir - $ export PYTHONPATH=$PYTHONPATH:/path/to/foo/python/module/file/dir - $ python - >> import foo - >> print dir(foo) - >> m = foo.Math() - >> print m.squared(5) - diff --git a/doc/tutorial/globalheader.rst b/doc/tutorial/globalheader.rst deleted file mode 100644 index d1ac2392e..000000000 --- a/doc/tutorial/globalheader.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. highlight:: cpp - -.. _gentut-globalheader: - -The Global Header -================= - -Besides the information provided by the typesystem, the generator needs to -gather more data from the library headers containing the classes to be exposed -in Python. If there is a header that include all the others (or just one, as is -the case of **libfoo**) this could be passed directly to the generator. - -If such a file is not available, or only a subset of the library is desired, or -if some flags must be defined before parsing the library headers, then a -``global.h`` file must be provided. - -The use of a ``global.h`` file is preferred if some macros must be defined -before the parser gather data from the headers. For example, if ``NULL`` is not -defined and it is used as a default paramater for some constructor or method, -the parser will not recognize it. - -The solve this create a ``global.h`` including all the desired headers and the -defined (and undefined) flags as follows: - -**foobinding/data/global.h** -:: - - #undef QT_NO_STL - #undef QT_NO_STL_WCHAR - - #ifndef NULL - #define NULL 0 - #endif - - #include <foo.h> - diff --git a/doc/tutorial/images/generatorworkings.png b/doc/tutorial/images/generatorworkings.png Binary files differdeleted file mode 100644 index d35a565ff..000000000 --- a/doc/tutorial/images/generatorworkings.png +++ /dev/null diff --git a/doc/tutorial/images/generatorworkings.svg b/doc/tutorial/images/generatorworkings.svg deleted file mode 100644 index 85a7782af..000000000 --- a/doc/tutorial/images/generatorworkings.svg +++ /dev/null @@ -1,392 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> -<svg - xmlns:dc="http://purl.org/dc/elements/1.1/" - xmlns:cc="http://creativecommons.org/ns#" - xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" - xmlns:svg="http://www.w3.org/2000/svg" - xmlns="http://www.w3.org/2000/svg" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" - xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - width="680" - height="280" - id="svg2" - sodipodi:version="0.32" - inkscape:version="0.46" - sodipodi:docname="generatorworkings.svg" - inkscape:output_extension="org.inkscape.output.svg.inkscape" - inkscape:export-filename="generatorworkings.png" - inkscape:export-xdpi="86.970001" - inkscape:export-ydpi="86.970001" - version="1.0"> - <defs - id="defs4"> - <marker - inkscape:stockid="Arrow1Lstart" - orient="auto" - refY="0" - refX="0" - id="Arrow1Lstart" - style="overflow:visible"> - <path - id="path4293" - d="M 0,0 L 5,-5 L -12.5,0 L 5,5 L 0,0 z" - style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" - transform="matrix(0.8,0,0,0.8,10,0)" /> - </marker> - <linearGradient - inkscape:collect="always" - id="linearGradient3235"> - <stop - style="stop-color:#000000;stop-opacity:1;" - offset="0" - id="stop3237" /> - <stop - style="stop-color:#000000;stop-opacity:0;" - offset="1" - id="stop3239" /> - </linearGradient> - <marker - inkscape:stockid="Arrow1Lend" - orient="auto" - refY="0" - refX="0" - id="Arrow1Lend" - style="overflow:visible"> - <path - id="path3282" - d="M 0,0 L 5,-5 L -12.5,0 L 5,5 L 0,0 z" - style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" - transform="matrix(-0.8,0,0,-0.8,-10,0)" /> - </marker> - <inkscape:perspective - sodipodi:type="inkscape:persp3d" - inkscape:vp_x="0 : 526.18109 : 1" - inkscape:vp_y="6.1230318e-14 : 1000 : 0" - inkscape:vp_z="744.09448 : 526.18109 : 1" - inkscape:persp3d-origin="372.04724 : 350.78739 : 1" - id="perspective10" /> - <linearGradient - inkscape:collect="always" - xlink:href="#linearGradient3235" - id="linearGradient3241" - x1="-29.816929" - y1="320.97046" - x2="191.17912" - y2="322.7244" - gradientUnits="userSpaceOnUse" /> - </defs> - <sodipodi:namedview - id="base" - pagecolor="#ffffff" - bordercolor="#666666" - borderopacity="1.0" - gridtolerance="10000" - guidetolerance="10" - objecttolerance="10" - inkscape:pageopacity="0.0" - inkscape:pageshadow="2" - inkscape:zoom="1.4420481" - inkscape:cx="361.95624" - inkscape:cy="122.34225" - inkscape:document-units="px" - inkscape:current-layer="g3297" - showgrid="false" - inkscape:window-width="1279" - inkscape:window-height="944" - inkscape:window-x="391" - inkscape:window-y="38" - showguides="true" - inkscape:guide-bbox="true"> - <sodipodi:guide - orientation="1,0" - position="-228.99296,-21.575354" - id="guide3165" /> - </sodipodi:namedview> - <metadata - id="metadata7"> - <rdf:RDF> - <cc:Work - rdf:about=""> - <dc:format>image/svg+xml</dc:format> - <dc:type - rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> - </cc:Work> - </rdf:RDF> - </metadata> - <g - inkscape:label="Layer 1" - inkscape:groupmode="layer" - id="layer1" - transform="translate(291.86879,-366.35864)"> - <text - xml:space="preserve" - style="font-size:40px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="324.86121" - y="308.08389" - id="text3395" - transform="translate(-28.960129,110.67739)"><tspan - sodipodi:role="line" - id="tspan3397" - x="324.86121" - y="308.08389" /></text> - <g - id="g3254"> - <g - id="g3297" - transform="translate(15,11.795533)"> - <rect - style="fill:#e4fae3;fill-opacity:0.65882353;stroke:#8eff89;stroke-width:0.52055138;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" - id="rect3609" - width="323.15158" - height="216.66933" - x="-151.9006" - y="364.42294" - ry="7.354454" - rx="5.3701153" /> - <path - style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Lstart);marker-end:none;stroke-opacity:1;display:inline" - d="M 195.16416,473.16835 L 149.88745,473.08346" - id="path3285" - inkscape:connector-type="polyline" - sodipodi:nodetypes="cc" - inkscape:connection-start="#g3276" /> - <g - id="g3276" - transform="translate(-47.379381,-25.682818)"> - <rect - ry="11.816782" - rx="12.0209" - y="462.87637" - x="242.78513" - height="72.257683" - width="163.85461" - id="rect2461" - style="fill:#9dcdf9;fill-opacity:1;stroke:#0084ff;stroke-width:0.48317167;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> - <text - id="text2463" - y="494.80786" - x="324.45514" - style="font-size:144px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - xml:space="preserve"><tspan - style="font-size:22px;text-align:center;text-anchor:middle" - y="494.80786" - x="324.45514" - id="tspan2465" - sodipodi:role="line">binding</tspan><tspan - style="font-size:22px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;font-family:FreeMono;-inkscape-font-specification:FreeMono" - y="519.56543" - x="324.45514" - sodipodi:role="line" - id="tspan3018">source code</tspan></text> - </g> - <path - style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Lstart);marker-end:none;stroke-opacity:1;display:inline" - d="M -130.41272,567.21015 L -180.20217,584.91297" - id="path3054" - inkscape:connector-type="polyline" - sodipodi:nodetypes="cc" /> - <path - style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Lstart);marker-end:none;stroke-opacity:1;display:inline" - d="M -129.57075,528.12072 L -181.18287,504.96225" - id="path3056" - inkscape:connector-type="polyline" - sodipodi:nodetypes="cc" /> - <g - id="g3147" - transform="translate(74.301071,9.8268847)"> - <g - transform="translate(62.764666,-13.729771)" - id="g2986"> - <rect - style="fill:#fafcc5;fill-opacity:1;stroke:#f9ff00;stroke-width:0.3511245;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" - id="rect2970" - width="115.38314" - height="55.650036" - x="-430.1297" - y="481.9653" - rx="11.184198" - ry="13.895926" /> - <text - xml:space="preserve" - style="font-size:144px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="-371.96939" - y="505.29422" - id="text2972"><tspan - id="tspan2976" - sodipodi:role="line" - x="-371.96939" - y="505.29422" - style="font-size:16px;text-align:center;text-anchor:middle">typesystem</tspan><tspan - id="tspan2980" - sodipodi:role="line" - x="-371.96939" - y="525.29419" - style="font-size:16px;text-align:center;text-anchor:middle">descriptions</tspan></text> - </g> - <g - transform="translate(74.533053,61.297656)" - id="g3020"> - <rect - style="fill:#fafcc5;fill-opacity:1;stroke:#f9ff00;stroke-width:0.36426121;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" - id="rect3022" - width="91.833252" - height="75.250854" - x="-418.35477" - y="472.16489" - rx="9.1466599" - ry="12.17058" /> - <text - xml:space="preserve" - style="font-size:144px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - x="-372.64865" - y="494.13867" - id="text3024"><tspan - id="tspan3026" - sodipodi:role="line" - x="-372.64865" - y="494.13867" - style="font-size:16px;text-align:center;text-anchor:middle">custom</tspan><tspan - id="tspan3028" - sodipodi:role="line" - x="-372.64865" - y="513.88837" - style="font-size:18px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;font-family:FreeMono;-inkscape-font-specification:FreeMono">source</tspan><tspan - id="tspan3030" - sodipodi:role="line" - x="-372.64865" - y="536.38837" - style="font-size:18px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;font-family:FreeMono;-inkscape-font-specification:FreeMono">code</tspan></text> - </g> - </g> - <path - style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Lstart);marker-end:none;stroke-opacity:1;display:inline" - d="M -40.946515,396.85213 L -179.16818,396.16834" - id="path3098" - inkscape:connector-type="polyline" - sodipodi:nodetypes="cc" /> - <g - id="g3141" - transform="translate(66.255107,-6.2939423)"> - <rect - ry="11.897643" - rx="9.5758715" - y="381.30014" - x="-342.70132" - height="47.647366" - width="98.790642" - id="rect2415" - style="fill:#fafcc5;fill-opacity:1;stroke:#f9ff00;stroke-width:0.30063155;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> - <text - id="text2417" - y="401.08865" - x="-293.63803" - style="font-size:144px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - xml:space="preserve"><tspan - style="font-size:16px;text-align:center;text-anchor:middle" - y="401.08865" - x="-293.63803" - id="tspan2419" - sodipodi:role="line">library</tspan><tspan - style="font-size:16px;text-align:center;text-anchor:middle" - y="421.08865" - x="-293.63803" - sodipodi:role="line" - id="tspan2949">headers</tspan></text> - </g> - <path - style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Lstart);marker-end:none;stroke-opacity:1;display:inline" - d="M 33.165609,503.00316 L 32.819729,546.19947" - id="path3167" - inkscape:connector-type="polyline" - sodipodi:nodetypes="cc" /> - <path - style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Lstart);marker-end:none;stroke-opacity:1;display:inline" - d="M 33.145722,443.9261 L 32.799842,391.41316" - id="path3169" - inkscape:connector-type="polyline" - sodipodi:nodetypes="cc" /> - <g - id="g2944" - transform="translate(85.554958,3.1233551)"> - <rect - rx="6.8840375" - ry="10.365664" - y="371.05527" - x="-125.40932" - height="44.903805" - width="101.06483" - id="rect3625" - style="fill:#bff3bc;fill-opacity:1;stroke:#0af400;stroke-width:0.36750945;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> - <text - transform="scale(1.0000266,0.9999734)" - id="text3627" - y="401.12787" - x="-75.810593" - style="font-size:38.71272278px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - xml:space="preserve"><tspan - style="font-size:21.29199791px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans Bold" - y="401.12787" - x="-75.810593" - sodipodi:role="line" - id="tspan3697">Parser</tspan></text> - </g> - <g - id="g3093" - transform="translate(-22.960524,10.08797)"> - <rect - ry="8.5151205" - rx="9.4630651" - y="433.92093" - x="9.3588104" - height="58.626995" - width="163.91852" - id="rect2446" - style="fill:#b2d7b5;fill-opacity:1;stroke:#34ff34;stroke-width:0.20534486;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:0.69008268" /> - <text - id="text2448" - y="457.49274" - x="90.813187" - style="font-size:144px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - xml:space="preserve"><tspan - style="font-size:22px;font-weight:bold;text-align:center;text-anchor:middle" - y="457.49274" - x="90.813187" - id="tspan2450" - sodipodi:role="line">Generator</tspan><tspan - style="font-size:22px;font-weight:bold;text-align:center;text-anchor:middle" - y="484.99274" - x="90.813187" - sodipodi:role="line" - id="tspan3340">Backend</tspan></text> - </g> - <g - id="g3160" - transform="translate(94.301071,19.633862)"> - <rect - rx="5.7330456" - ry="8.3964748" - y="506.2883" - x="-225.62247" - height="44.764942" - width="192.46243" - id="rect2933" - style="fill:#bff3bc;fill-opacity:1;stroke:#0af400;stroke-width:0.50637114;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> - <text - transform="scale(1.0000266,0.9999734)" - id="text2935" - y="534.47565" - x="-128.93036" - style="font-size:38.71272278px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" - xml:space="preserve"><tspan - style="font-size:21.29199791px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans Bold" - y="534.47565" - x="-128.93036" - sodipodi:role="line" - id="tspan2937">TypeDatabase</tspan></text> - </g> - </g> - </g> - </g> -</svg> diff --git a/doc/tutorial/introduction.rst b/doc/tutorial/introduction.rst deleted file mode 100644 index 5234551b7..000000000 --- a/doc/tutorial/introduction.rst +++ /dev/null @@ -1,31 +0,0 @@ -Binding Generation Tutorial -*************************** - -This tutorial intends to describe the process of binding creation with -|project| and using a very simple Qt4 based library will be used as an -example. - -The image below shows the inputs needed to generate the binding source code. - -.. image:: images/generatorworkings.png - -Putting in words, the user provides the headers for the library along with a -typesystem file describing how the classes will be exposed in the target -language, as well as any needed custom source code to be merged with -the generated source code. - -This tutorial will go through the steps needed to have the binding -being able to be imported and used from a Python program. - -**NOTE:** the binding generator is intended to be used with Qt4 based libraries -only, at least for the time being. - -.. toctree:: - :maxdepth: 3 - - libfoo - bindinglibfoo - typesystemcreation - globalheader - buildingthebinding - diff --git a/doc/tutorial/libfoo.rst b/doc/tutorial/libfoo.rst deleted file mode 100644 index 217577a4f..000000000 --- a/doc/tutorial/libfoo.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. highlight:: cpp - -.. _gentut-libfoo: - -Creating the foo library -========================= - -In this section is the code and build instructions for a very simple Qt4 based -library which will serve as a subject for this tutorial. - -The Source Code ---------------- - -There is only one class on this foo library plus a ``.pro`` file which means -that the build system used will be Trolltech's **qmake**. - -Put the files below in a directory called **libfoo**. Be aware that this -directory will be refered by the binding Makefile presented in a next section -of this tutorial. If you want to use other names or paths change the binding -Makefile accordingly. Blind copy'n'paste shortens your life. - -**libfoo/foo.h** -:: - - #ifndef FOO_H - #define FOO_H - - #include <QtCore/QtCore> - - class Math : public QObject - { - Q_OBJECT - public: - Math() {} - virtual ~Math() {} - int squared(int x); - }; - #endif // FOO_H - - -**libfoo/foo.cpp** -:: - - #include "foo.h" - - int Math::squared(int x) - { - return x * x; - } - - -**libfoo/foo.pro** -:: - - TEMPLATE = lib - TARGET = foo - DEPENDPATH += . - INCLUDEPATH += . - HEADERS += foo.h - SOURCES += foo.cpp - -To build the lib: - -:: - - $ cd libfoo - $ qmake - $ make diff --git a/doc/tutorial/typesystemcreation.rst b/doc/tutorial/typesystemcreation.rst deleted file mode 100644 index f36a8769a..000000000 --- a/doc/tutorial/typesystemcreation.rst +++ /dev/null @@ -1,136 +0,0 @@ -.. highlight:: xml - -.. _gentut-typesystem: - -Creating the Typesystem Description -=================================== - -The type system is a specification used when mapping a C++ based library onto a -corresponding Python module. The specification is a handwritten XML document -listing the types that will be available in the generated binding, alterations -to classes and function signatures to better suit the target language, -and listing the components that should be rejected for the binding. - -**PyQtB** uses a typesystem format similar to the ones used **QtJambi** and -**QtScript**, thoroughly described in the page *"The Qt Jambi Type System"*. [#]_ - -The divergences between **PyQtB** and QtScript/QtJambi typesystems will be -highlighted whenever they appear. Things to be aware of when writing -a typesystem will be also mentioned. - -Describing **libfoo** for Python Audiences ------------------------------------------- - -All typesystem files start with the root ``typesystem`` tag, the -``package`` attribute carries the name of the package as it will be seen -from Python. - -Right after that, all the typesystem files providing information required for -the generation process are included in the same fashion as header files in C. - -**foobinding/data/typesystem_test.xml** -:: - - <?xml version="1.0"?> - <typesystem package="foo"> - <load-typesystem name="typesystem_core.xml" generate="no"/> - <object-type name="Math"/> - </typesystem> - - -The inclusion of the other typesystem files is achieved with the -``load-typesystem`` tag. The ``generate`` attribute must be set to ``"no"`` -or else the generator will try to create more source code for the already -existing bindings included for reference. - -The C++ classes derived from **QObject** intended to be exposed in the target -language are described with ``object-type`` tags. - - -For this example binding just specifying the name of the class does the trick, -since the generator system will automatically catch the methods with arguments -and return value of types known. These types can be described in the same -typesystem file or in the ones referenced with the ``load-typesystem`` tag. - -In more complex situations method signatures can be changed or rejected with -other tags that can be checked out in the typesystem reference. - - -Other Common Cases and Differences ----------------------------------- - -What follows now is some common uses of the typesystem capabilities. All of them -can be seen in the Qt4 typesystem files. They are not used for this binding -tutorial example, so if you just want to have things working ASAP, -move along. - -Templates -~~~~~~~~~ - -To ease the process of writing custom code for the binding, recurring pieces of -code can be turned generic with the Typesystem template mechanism. -They are declared in a way similar to this snippet: - -:: - - <template name="only_bool*_fix"> - bool ok; - %RETURN_TYPE retval = self.%FUNCTION_NAME(&ok); - </template> - -And is used as in this example: - -:: - - <inject-code class="native" position="beginning"> - <insert-template name="only_bool*_fix"/> - </inject-code> - - -The ``typesystem_template.xml`` file from the Qt4 bindings can be used as a -good resource for examples of this. Check also the QtJambi documentation on -typesystem templates. [#]_ - -Non-QObject Derived Classes -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Even in a Qt4 based library it is common to find classes that doesn't -pertain to the QObject hierarchy, these must be declared as ``value-type``: - -:: - - <value-type name="RectOrSomethingLikeThat"/> - - -Unused Tags -~~~~~~~~~~~ - -Some tags defined in the QtScript/QtJambi typesystem has no effect in **PyQtB** -typesystem, they are: - - + conversion-rule - + argument-map - -Changes to ``"inject-code"`` Tag -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can pass a file name to the **inject-code** tag, the file contents will -be injected in the generated code. - -The ``class`` attribute value ``java`` was changed to ``target``, while -``native`` remained the same. - -Global Functions -~~~~~~~~~~~~~~~~ - -The **BoostGenerator** supports global functions, you can also reject these -functions using the **rejection** tag like is done to reject classes, just -pass an empty string to the class attribute. - -:: - - <rejection class="" function-name="qt_noop"/> - - -.. [#] http://doc.trolltech.com/qtjambi-4.4/html/com/trolltech/qt/qtjambi-typesystem.html -.. [#] http://doc.trolltech.com/qtjambi-4.4/html/com/trolltech/qt/qtjambi-typesystem.html#using-code-templates |