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 PHP5
  51 ----
  52
  53 Debian wheezy::
  54
  55 apt-get install php5-dev php5-cli
  56
  57 PHP7
  58 ----
  59
  60 Debian stretch::
  61
  62 apt-get install php7.0-cli php7.0-dev
  63
  64 Python
  65 ------
  66
  67 Debian wheezy::
  68
  69 apt-get install python-dev
  70
  71 Ruby
  72 ----
  73
  74 Debian wheezy::
  75
  76 apt-get install ruby-dev
  77
  78 Tcl
  79 ---
  80
  81 Debian wheezy::
  82
  83 apt-get install tcl-dev
  84
  85 Adding support for other programming languages
  86 ==============================================
  87
  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!)
  94
  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...
 100
 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
 105 anyone else).
 106
 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.
 111
 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
 119 bindings.
 120
 121 These are languages which SWIG supports and which people have done some work
 122 on producing Xapian bindings for:
 123
 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
 128                 using SWIG.
 129
 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
 132                 died.
 133
 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.
 137
 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.
 141
 142 Implementing Deprecation Warnings for the Bindings
 143 =================================================
 144
 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:
 148
 149   * PHP 5.3 added an E_USER_DEPRECATED error level, and we now require at
 150     least 5.5.
 151
 152     And then in a deprecated method we do:
 153
 154       trigger_error('World::hi() is deprecated, use World::hello() instead', XAPIAN_DEPRECATED);
 155
 156   * Python has DeprecationWarning, which we were using in 1.2.x a bit::
 157
 158       warnings.warn('World::hi() is deprecated, use World::hello() instead', DeprecationWarning)
 159
 160   * Ruby - there are external libraries to handle deprecation warnings, but the
 161     simplest option without external dependencies seems to be::
 162
 163       warn '[DEPRECATION] 'World::hi() is deprecated, use World::hello() instead')
 164
 165   * Perl::
 166
 167      use warnings;
 168      warnings::warnif('deprecated', 'World::hi() is deprecated, use World::hello() instead');
 169
 170   * Java has @Deprecated, but I think that's a documentation thing only.
 171
 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
 174 simpler?
 175
 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.