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 bullseye and bookworm::
  28
  29 apt-get install mono-devel
  30
  31 Java
  32 ----
  33
  34 Debian bullseye and bookworm::
  35
  36 apt-get install openjdk-17-jdk
  37
  38 Lua
  39 ---
  40
  41 Debian bullseye and bookworm::
  42
  43 apt-get install lua5.4 liblua5.4-dev
  44
  45 Perl
  46 ----
  47
  48 Debian bullseye and bookworm: all required are packages installed by default.
  49
  50 PHP
  51 ---
  52
  53 Debian bookworm::
  54
  55 apt-get install php-cli php-dev
  56
  57 Python3
  58 -------
  59
  60 Debian bullseye and bookworm::
  61
  62 apt-get install python3-dev
  63
  64 Ruby
  65 ----
  66
  67 Debian bullseye and bookworm::
  68
  69 apt-get install ruby-dev
  70
  71 Tcl
  72 ---
  73
  74 Debian bullseye and bookworm::
  75
  76 apt-get install tcl-dev
  77
  78 Running tests in-tree on macOS
  79 ==============================
  80
  81 On macOS 10.11 and later there's a new feature called System Integrity
  82 Protection (SIP) which locks down "system binaries" to an extent which is
  83 actively unhelpful when doing development work.  This breaks running tests
  84 in-tree for language interpreters which are system binaries because environment
  85 variables such as ``DYLD_LIBRARY_PATH`` are stripped from the environment and
  86 as a result the in-tree libxapian from xapian-core can't be found.
  87
  88 The workaround is to ``make install`` for xapian-core before running ``make
  89 check`` for xapian-bindings, and we're aiming to at least keep this working.
  90
  91 If you find having to do this too annoying, it's possible to disable SIP:
  92 https://developer.apple.com/documentation/security/disabling_and_enabling_system_integrity_protection
  93
  94 Adding support for other programming languages
  95 ==============================================
  96
  97 Many languages can be done using SWIG, and it's probably easier to do so
  98 even though some languages may have better tools available just because it's
  99 less overall work.  SWIG makes it particularly easy to wrap a new method for
 100 all the supported languages at once - in many cases just adding the method
 101 to the C++ API is enough, since SWIG parses the C++ API headers.
 102
 103 What's really needed is someone interested in bindings for a particular
 104 language who knows that language well and will be using them actively.
 105 We can help with the Xapian and SWIG side, but without somebody who knows
 106 the language well it's hard to produce a solid, well tested set of bindings
 107 rather than just a token implementation...
 108
 109 To be worth shipping in the xapian-bindings tarball, bindings for an additional
 110 language really need a version of the smoketest (so we can be confident that
 111 they actually work!), and also documentation and examples along the lines of
 112 the existing bindings (without these the bindings aren't likely to be useful to
 113 anyone else).
 114
 115 To give an idea of how much work a set of bindings might be, the author of the
 116 Ruby bindings estimated they took about 25 hours, starting from not knowing
 117 SWIG.  However, the time taken could vary substantially depending on the
 118 language, how well you know it, and how well SWIG supports it.
 119
 120 XS bindings for Perl have been contributed for Perl, and these are available
 121 on CPAN as `Search::Xapian`.  We also have SWIG-based Perl bindings which are
 122 in the ``perl`` subdirectory here, as a `Xapian` module.  These are replacing
 123 the XS-based `Search::Xapian`, and will eventually be on CPAN.
 124
 125 These are languages which SWIG supports and which people have done some work
 126 on producing Xapian bindings for:
 127
 128 Go              There are some basic Go bindings written by Marius Tibeica in
 129                 the "golang" branch, which is currently based on the
 130                 RELEASE/1.4 branch.
 131
 132 Ocaml           Dan Colish did some initial work on Ocaml support -
 133                 see: https://trac.xapian.org/ticket/588
 134
 135 Pike            Bill Welliver has written some Pike bindings for Xapian
 136                 covering some of the API, which are available from here:
 137                 http://modules.gotpike.org/module/Public.Xapian?selected=1.10
 138                 These bindings appear to be hand-coded rather than generated
 139                 using SWIG.  SWIG 4.0.0 has disabled Pike support due to
 140                 lack of recent maintenance, so SWIG is probably not a good
 141                 option here.
 142
 143 There are a number of other languages which SWIG supports, but which nobody has
 144 yet (to our knowledge!) worked on producing Xapian bindings for - see
 145 https://www.swig.org/compare.html for a list of supported languages.
 146
 147 It may be possible to support a language which isn't listed above, but it's
 148 likely to be harder unless you're already familiar with the tools available
 149 for wrapping a C++ library for use with that language.
 150
 151 Implementing Deprecation Warnings for the Bindings
 152 ==================================================
 153
 154 Currently we don't have an equivalent of the C++ ``XAPIAN_DEPRECATED()`` macro
 155 for the bindings, but it would be good to have.  Here are some notes on how
 156 this could be achieved for various languages we support:
 157
 158   * PHP now has an ``E_USER_DEPRECATED`` error level - in a deprecated method
 159     we could do::
 160
 161       trigger_error('World::hi() is deprecated, use World::hello() instead', E_USER_DEPRECATED);
 162
 163   * Python has DeprecationWarning, which we were using in 1.2.x a bit::
 164
 165       warnings.warn('World::hi() is deprecated, use World::hello() instead', DeprecationWarning)
 166
 167   * Ruby - there are external libraries to handle deprecation warnings, but the
 168     simplest option without external dependencies seems to be::
 169
 170       warn '[DEPRECATION] World::hi() is deprecated, use World::hello() instead'
 171
 172   * Perl::
 173
 174      use warnings;
 175      warnings::warnif('deprecated', 'World::hi() is deprecated, use World::hello() instead');
 176
 177   * Java has @Deprecated, but I think that's a documentation thing only.
 178
 179 It would be great (but probably hard) to reuse the XAPIAN_DEPRECATION()
 180 markers.  Perhaps parsing the doxygen XML for @deprecated markers would be
 181 simpler?
 182
 183 Also, it would be good if the warnings could be turned off easily, as runtime
 184 deprecation warnings can be annoying for end users.