subversion/bindings/swig/NOTES

   1                                                                 -*-text-*-
   2
   3
   4 ==> For instructions on how to get swig bindings working, read the
   5      INSTALL file in this directory.
   6
   7
   8 SVN HEADER -> SWIG MODULE
   9 -------------------------
  10
  11 Subversion has a bunch of include files, some which are interesting for
  12 wrapping with language bindings, and others which are simple type
  13 declarations and constants. Below is the table which maps each header
  14 to its disposition:
  15
  16 INCLUDE           SWIG MODULE NAME
  17 svn_auth.h        _core (some symbols)
  18 svn_base64.h      (1)
  19 svn_client.h      _client
  20 svn_cmdline.h     (2)
  21 svn_config.h      _core (some symbols)
  22 svn_ctype.h       (1)
  23 svn_dav.h         (2)
  24 svn_delta.h       _delta
  25 svn_diff.h        _diff
  26 svn_error.h       (2)
  27 svn_error_codes.h _core
  28 svn_fs.h          _fs
  29 svn_hash.h        (1)
  30 svn_io.h          _core (only stream functions)
  31 svn_md5.h         (1)
  32 svn_opt.h         _core (some symbols)
  33 svn_path.h        _core (some symbols, 1)
  34 svn_pools.h       _core (only pool manipulation)
  35 svn_props.h       _core (some symbols)
  36 svn_quoprint.h    (1)
  37 svn_ra.h          _ra
  38 svn_ra_svn.h      (2)
  39 svn_repos.h       _repos
  40 svn_sorts.h       (1)
  41 svn_string.h      (3)
  42 svn_subst.h       (2)
  43 svn_test.h        (2)
  44 svn_time.h        _core (some symbols)
  45 svn_types.h       (3)
  46 svn_utf.h         (1)
  47 svn_version.h     _core (some symbols)
  48 svn_wc.h          _wc
  49 svn_xml.h         (1)
  50
  51 apr*.h            (3)
  52
  53 (1) It is assumed that the binding languages will provide this
  54     functionality separately.
  55     ### HELP: Java does not provide base-64 natively.  Should we wrap
  56     ### SVN's with SWIG, or include a stand-alone ASF implementation
  57     ### (such as from Jakarta Commons Codec)?
  58
  59 (2) No significant/interesting functionality to export.
  60
  61 (3) A SWIG interface file exists, but only to export types used by other
  62     modules.  No binding module is actually constructed from this
  63     header.
  64
  65
  66 SWIG MODULES
  67 ------------
  68
  69 We will produce a number of modules/classes, expecting the binding
  70 languages to organize these into a package, and present the Subversion
  71 libraries' API in a manner familiar to programmers of a given
  72 language.  For instance, the Python bindings are handled as follows:
  73
  74 svn.core
  75 svn.client
  76 svn.delta
  77 svn.fs
  78 svn.ra
  79 svn.repos
  80 svn.wc
  81
  82
  83
  84
  85 THUNK EDITORS
  86 -------------
  87
  88 "Thunk" is Windows programming term describing a "go between."  Our
  89 SWIG bindings generally implement editors in C which delegate to the
  90 language-specific extension API (e.g. its C API for Python, JNI for
  91 Java, etc.).  This transitional object implements a Subversion editor
  92 interface, allowing it to be passed between its native library code
  93 and the runtime of the language which the bindings were written for.
  94
  95
  96
  97
  98 SWIG INTERFACE FILE CODING NOTES
  99 --------------------------------
 100
 101 Always place %{ #include "foo.h" ... %} sections above any code which
 102 will actually cause SWIG to generate wrappers.  This is because those
 103 wrappers may need declarations from the headers to be valid C.
 104 Practically, this means that the %{ ... %} block should be above any
 105 "%include *.h" statements (%includes of *.i files are fine, since they
 106 should be self-sufficient).
 107