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 stretch::
  28
  29 apt-get install mono-devel
  30
  31 Java
  32 ----
  33
  34 Debian stretch::
  35
  36 apt-get install openjdk-8-jdk
  37
  38 Lua
  39 ---
  40
  41 Debian stretch::
  42
  43 apt-get install lua5.3 liblua5.3-dev
  44
  45 Perl
  46 ----
  47
  48 Debian stretch: 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 php-cli php-dev
  63
  64 Python
  65 ------
  66
  67 Debian stretch::
  68
  69 apt-get install python-dev
  70
  71 Ruby
  72 ----
  73
  74 Debian stretch::
  75
  76 apt-get install ruby-dev
  77
  78 Tcl
  79 ---
  80
  81 Debian stretch::
  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 - in many cases just adding the method
  92 to the C++ API is enough, since SWIG parses the C++ API headers.
  93
  94 What's really needed is someone interested in bindings for a particular
  95 language who knows that language well and will be using them actively.
  96 We can help with the Xapian and SWIG side, but without somebody who knows
  97 the language well it's hard to produce a solid, well tested set of bindings
  98 rather than just a token implementation...
  99
 100 To be worth shipping in the xapian-bindings tarball, bindings for an additional
 101 language really need a version of the smoketest (so we can be confident that
 102 they actually work!), and also documentation and examples along the lines of
 103 the existing bindings (without these the bindings aren't likely to be useful to
 104 anyone else).
 105
 106 To give an idea of how much work a set of bindings might be, the author of the
 107 Ruby bindings estimated they took about 25 hours, starting from not knowing
 108 SWIG.  However, the time taken could vary substantially depending on the
 109 language, how well you know it, and how well SWIG supports it.
 110
 111 XS bindings for Perl have been contributed for Perl, and these are available
 112 on CPAN as `Search::Xapian`.  We also have SWIG-based Perl bindings which are
 113 in the ``perl`` subdirectory here, as a `Xapian` module.  These are replacing
 114 the XS-based `Search::Xapian`, and will eventually be on CPAN.
 115
 116 These are languages which SWIG supports and which people have done some work
 117 on producing Xapian bindings for:
 118
 119 Go              There are some basic Go bindings written by Marius Tibeica in
 120                 the "golang" branch, which is currently based on the
 121                 RELEASE/1.4 branch.
 122
 123 Ocaml           Dan Colish did some initial work on Ocaml support -
 124                 see: https://trac.xapian.org/ticket/588
 125
 126 Guile           rm@fabula.de did some work on getting Guile bindings working,
 127                 but sadly most of this was lost when his laptop's hard disk
 128                 died.
 129
 130 Pike            Bill Welliver has written some Pike bindings for Xapian
 131                 covering some of the API, which are available from here:
 132                 http://modules.gotpike.org/module_info.html?module_id=42
 133                 These bindings appear to be hand-coded rather than generated
 134                 using SWIG.  SWIG 4.0.0 has disabled Pike support due to
 135                 lack of recent maintenance, so SWIG is probably not a good
 136                 option here.
 137
 138 There are a number of other languages which SWIG supports, but which nobody has
 139 yet (to our knowledge!) worked on producing Xapian bindings for - see
 140 http://www.swig.org/compare.html for a list of supported languages.
 141
 142 It may be possible to support a language which isn't listed above, but it's
 143 likely to be harder unless you're already familiar with the tools available
 144 for wrapping a C++ library for use with that language.
 145
 146 Implementing Deprecation Warnings for the Bindings
 147 =================================================
 148
 149 Currently we don't have an equivalent of the C++ ``XAPIAN_DEPRECATED()`` macro
 150 for the bindings, but it would be good to have.  Here are some notes on how
 151 this could be achieved for various languages we support:
 152
 153   * PHP 5.3 added an E_USER_DEPRECATED error level, and we now require at
 154     least 5.5.
 155
 156     And then in a deprecated method we do:
 157
 158       trigger_error('World::hi() is deprecated, use World::hello() instead', XAPIAN_DEPRECATED);
 159
 160   * Python has DeprecationWarning, which we were using in 1.2.x a bit::
 161
 162       warnings.warn('World::hi() is deprecated, use World::hello() instead', DeprecationWarning)
 163
 164   * Ruby - there are external libraries to handle deprecation warnings, but the
 165     simplest option without external dependencies seems to be::
 166
 167       warn '[DEPRECATION] 'World::hi() is deprecated, use World::hello() instead')
 168
 169   * Perl::
 170
 171      use warnings;
 172      warnings::warnif('deprecated', 'World::hi() is deprecated, use World::hello() instead');
 173
 174   * Java has @Deprecated, but I think that's a documentation thing only.
 175
 176 It would be great (but probably hard) to reuse the XAPIAN_DEPRECATION()
 177 markers.  Perhaps parsing the doxygen XML for @deprecated markers would be
 178 simpler?
 179
 180 Also, it would be good if the warnings could be turned off easily, as runtime
 181 deprecation warnings can be annoying for end users.