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 php7.0-cli php7.0-dev
69 apt-get install python-dev
76 apt-get install ruby-dev
83 apt-get install tcl-dev
85 Adding support for other programming languages
86 ==============================================
88 Many languages can be done using SWIG, and it's probably easier to do so
89 even though some languages may have better tools available just because it's
90 less overall work. SWIG makes it particularly easy to wrap a new method for
91 all the supported languages at once, often by just copying the new method
92 prototype into xapian.i (and for some headers we parse the Xapian header
93 directly so no work is needed!)
95 What's really needed is someone interested in bindings for a particular
96 language who knows that language well and will be using them actively.
97 We can help with the Xapian and SWIG side, but without somebody who knows
98 the language well it's hard to produce a solid, well tested set of bindings
99 rather than just a token implementation...
101 To be worth shipping in the xapian-bindings tarball, bindings for an additional
102 language really need a version of the smoketest (so we can be confident that
103 they actually work!), and also documentation and examples along the lines of
104 the existing bindings (without these the bindings aren't likely to be useful to
107 To give an idea of how much work a set of bindings might be, the author of the
108 Ruby bindings estimated they took about 25 hours, starting from not knowing
109 SWIG. However, the time taken could vary substantially depending on the
110 language, how well you know it, and how well SWIG supports it.
112 XS bindings for Perl have been contributed for Perl, and these are available
113 on CPAN as `Search::Xapian`. We also have SWIG-based Perl bindings which are
114 in the ``perl`` subdirectory here, as a `Xapian` module. These are replacing
115 the XS-based `Search::Xapian`, and will eventually be on CPAN (certainly once
116 1.4.0 is out, and probably before). Currently SWIG's Perl backend doesn't
117 support directors, so doesn't give us an easy mechanism for callbacks (e.g. for
118 Xapian::MatchDecider) but perhaps we can do these by hand as they are in the XS
121 These are languages which SWIG supports and which people have done some work
122 on producing Xapian bindings for:
124 Pike Bill Welliver has written some Pike bindings for Xapian
125 covering some of the API, which are available from here:
126 http://modules.gotpike.org/module_info.html?module_id=42
127 These bindings appear to be hand-coded rather than generated
130 Guile rm@fabula.de did some work on getting Guile bindings working,
131 but sadly most of this was lost when his laptop's hard disk
134 There are a number of other languages which SWIG supports, but which nobody has
135 yet (to our knowledge!) worked on producing Xapian bindings for - see
136 http://www.swig.org/compare.html for a list of supported languages.
138 It may be possible to support a language which isn't listed above, but it's
139 likely to be harder unless you're already familiar with the tools available
140 for wrapping a C++ library for use with that language.
142 Implementing Deprecation Warnings for the Bindings
143 =================================================
145 Currently we don't have an equivalent of the C++ ``XAPIAN_DEPRECATED()`` macro
146 for the bindings, but it would be good to have. Here are some notes on how
147 this could be achieved for various languages we support:
149 * PHP 5.3 added an E_USER_DEPRECATED error level, and we now require at
152 And then in a deprecated method we do:
154 trigger_error('World::hi() is deprecated, use World::hello() instead', XAPIAN_DEPRECATED);
156 * Python has DeprecationWarning, which we were using in 1.2.x a bit::
158 warnings.warn('World::hi() is deprecated, use World::hello() instead', DeprecationWarning)
160 * Ruby - there are external libraries to handle deprecation warnings, but the
161 simplest option without external dependencies seems to be::
163 warn '[DEPRECATION] 'World::hi() is deprecated, use World::hello() instead')
168 warnings::warnif('deprecated', 'World::hi() is deprecated, use World::hello() instead');
170 * Java has @Deprecated, but I think that's a documentation thing only.
172 It would be great (but probably hard) to reuse the XAPIAN_DEPRECATION()
173 markers. Perhaps parsing the doxygen XML for @deprecated markers would be
176 Also, it would be good if the warnings could be turned off easily, as runtime
177 deprecation warnings can be annoying for end users.