1 Instructions for hacking on Xapian's bindings
2 =============================================
4 This file is aimed to help developers get started with working on
5 Xapian's bindings. You should also read the HACKING file in the
6 xapian-core sources which gives information which isn't specific
9 Extra options to give to configure:
10 ===================================
12 Note: Non-developer configure options are described in INSTALL
14 --enable-maintainer-mode
15 This tells configure to enable make dependencies for regenerating build
16 system files (such as configure, Makefile.in, and Makefile), and also
17 enables rules to rebuild the bindings glue code by rerunning SWIG.
18 You'll need to specify this if you're going to modify configure.ac, any
19 Makefile.am, or any .i file.
21 Packages to install for each language
22 =====================================
29 apt-get install mono-devel
36 apt-get install openjdk-6-jdk
43 apt-get install lua5.2 liblua5.2-dev
48 Debian wheezy: all required are packages installed by default.
55 apt-get install php5-dev php5-cli
62 apt-get install python-dev
69 apt-get install ruby-dev
76 apt-get install tcl-dev
78 Adding support for other programming languages
79 ==============================================
81 Many languages can be done using SWIG, and it's probably easier to do so
82 even though some languages may have better tools available just because it's
83 less overall work. SWIG makes it particularly easy to wrap a new method for
84 all the supported languages at once, often by just copying the new method
85 prototype into xapian.i (and for some headers we parse the Xapian header
86 directly so no work is needed!)
88 What's really needed is someone interested in bindings for a particular
89 language who knows that language well and will be using them actively.
90 We can help with the Xapian and SWIG side, but without somebody who knows
91 the language well it's hard to produce a solid, well tested set of bindings
92 rather than just a token implementation...
94 To be worth shipping in the xapian-bindings tarball, bindings for an additional
95 language really need a version of the smoketest (so we can be confident that
96 they actually work!), and also documentation and examples along the lines of
97 the existing bindings (without these the bindings aren't likely to be useful to
100 To give an idea of how much work a set of bindings might be, the author of the
101 Ruby bindings estimated they took about 25 hours, starting from not knowing
102 SWIG. However, the time taken could vary substantially depending on the
103 language, how well you know it, and how well SWIG supports it.
105 XS bindings for Perl have been contributed for Perl, and these are available
106 on CPAN as `Search::Xapian`. We also have SWIG-based Perl bindings which are
107 in the ``perl`` subdirectory here, as a `Xapian` module. These are replacing
108 the XS-based `Search::Xapian`, and will eventually be on CPAN (certainly once
109 1.4.0 is out, and probably before). Currently SWIG's Perl backend doesn't
110 support directors, so doesn't give us an easy mechanism for callbacks (e.g. for
111 Xapian::MatchDecider) but perhaps we can do these by hand as they are in the XS
114 These are languages which SWIG supports and which people have done some work
115 on producing Xapian bindings for:
117 Pike Bill Welliver has written some Pike bindings for Xapian
118 covering some of the API, which are available from here:
119 http://modules.gotpike.org/module_info.html?module_id=42
120 These bindings appear to be hand-coded rather than generated
123 Guile rm@fabula.de did some work on getting Guile bindings working,
124 but sadly most of this was lost when his laptop's hard disk
127 There are a number of other languages which SWIG supports, but which nobody has
128 yet (to our knowledge!) worked on producing Xapian bindings for - see
129 http://www.swig.org/compare.html for a list of supported languages.
131 It may be possible to support a language which isn't listed above, but it's
132 likely to be harder unless you're already familiar with the tools available
133 for wrapping a C++ library for use with that language.
135 Implementing Deprecation Warnings for the Bindings
136 =================================================
138 Currently we don't have an equivalent of the C++ ``XAPIAN_DEPRECATED()`` macro
139 for the bindings, but it would be good to have. Here are some notes on how
140 this could be achieved for various languages we support:
142 * PHP 5.3 added an E_USER_DEPRECATED error level, and we now require at
143 least 5.5. If we wanted to backport this to 1.2, we could use
144 E_USER_NOTICE there instead, by putting this near the start of xapian.php::
146 define('XAPIAN_DEPRECATED',defined(E_USER_DEPRECATED)?E_USER_DEPRECATED:E_USER_NOTICE);
148 And then in a deprecated method we do:
150 trigger_error('World::hi() is deprecated, use World::hello() instead', XAPIAN_DEPRECATED);
152 * Python has DeprecationWarning, which we were using in 1.2.x a bit::
154 warnings.warn('World::hi() is deprecated, use World::hello() instead', DeprecationWarning)
156 * Ruby - there are external libraries to handle deprecation warnings, but the
157 simplest option without external dependencies seems to be::
159 warn '[DEPRECATION] 'World::hi() is deprecated, use World::hello() instead')
164 warnings::warnif('deprecated', 'World::hi() is deprecated, use World::hello() instead');
166 * Java has @Deprecated, but I think that's a documentation thing only.
168 It would be great (but probably hard) to reuse the XAPIAN_DEPRECATION()
169 markers. Perhaps parsing the doxygen XML for @deprecated markers would be
172 Also, it would be good if the warnings could be turned off easily, as runtime
173 deprecation warnings can be annoying for end users.