xapian-bindings/HACKING

   1 Instructions for hacking on Xapian's bindings
   2 =============================================
   3
   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
   7 to the bindings.
   8
   9 Extra options to give to configure:
  10 ===================================
  11
  12 Note: Non-developer configure options are described in INSTALL
  13
  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.
  20
  21 Packages to install for each language
  22 =====================================
  23
  24 C#
  25 --
  26
  27 Debian wheezy::
  28
  29 apt-get install mono-devel
  30
  31 Java
  32 ----
  33
  34 Debian wheezy::
  35
  36 apt-get install openjdk-6-jdk
  37
  38 Lua
  39 ---
  40
  41 Debian wheezy::
  42
  43 apt-get install lua5.2 liblua5.2-dev
  44
  45 Perl
  46 ----
  47
  48 Debian wheezy: all required are packages installed by default.
  49
  50 PHP
  51 ---
  52
  53 Debian wheezy::
  54
  55 apt-get install php5-dev php5-cli
  56
  57 Python
  58 ------
  59
  60 Debian wheezy::
  61
  62 apt-get install python-dev
  63
  64 Ruby
  65 ----
  66
  67 Debian wheezy::
  68
  69 apt-get install ruby-dev
  70
  71 Tcl
  72 ---
  73
  74 Debian wheezy::
  75
  76 apt-get install tcl-dev
  77
  78 Adding support for other programming languages
  79 ==============================================
  80
  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!)
  87
  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...
  93
  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
  98 anyone else).
  99
 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.
 104
 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
 112 bindings.
 113
 114 These are languages which SWIG supports and which people have done some work
 115 on producing Xapian bindings for:
 116
 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
 121                 using SWIG.
 122
 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
 125                 died.
 126
 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.
 130
 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.
 134
 135 Implementing Deprecation Warnings for the Bindings
 136 =================================================
 137
 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:
 141
 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::
 145
 146       define('XAPIAN_DEPRECATED',defined(E_USER_DEPRECATED)?E_USER_DEPRECATED:E_USER_NOTICE);
 147
 148     And then in a deprecated method we do:
 149
 150       trigger_error('World::hi() is deprecated, use World::hello() instead', XAPIAN_DEPRECATED);
 151
 152   * Python has DeprecationWarning, which we were using in 1.2.x a bit::
 153
 154       warnings.warn('World::hi() is deprecated, use World::hello() instead', DeprecationWarning)
 155
 156   * Ruby - there are external libraries to handle deprecation warnings, but the
 157     simplest option without external dependencies seems to be::
 158
 159       warn '[DEPRECATION] 'World::hi() is deprecated, use World::hello() instead')
 160
 161   * Perl::
 162
 163      use warnings;
 164      warnings::warnif('deprecated', 'World::hi() is deprecated, use World::hello() instead');
 165
 166   * Java has @Deprecated, but I think that's a documentation thing only.
 167
 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
 170 simpler?
 171
 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.