README

   1 libstemmer_c
   2 ============
   3
   4 This document pertains to the C version of the libstemmer distribution,
   5 available for download from:
   6
   7 http://snowball.tartarus.org/dist/libstemmer_c.tgz
   8
   9
  10 Compiling the library
  11 =====================
  12
  13 A simple makefile is provided for Unix style systems.  On such systems, it
  14 should be possible simply to run "make", and the file "libstemmer.o"
  15 and the example program "stemwords" will be generated.
  16
  17 If this doesn't work on your system, you need to write your own build
  18 system (or call the compiler directly).  The files to compile are
  19 all contained in the "libstemmer", "runtime" and "src_c" directories,
  20 and the public header file is contained in the "include" directory.
  21
  22 The library comes in two flavours; UTF-8 only, and UTF-8 plus other character
  23 sets.  To use the utf-8 only flavour, compile "libstemmer_utf8.c" instead of
  24 "libstemmer.c".
  25
  26 For convenience "mkinc.mak" is a makefile fragment listing the source files and
  27 header files used to compile the standard version of the library.
  28 "mkinc_utf8.mak" is a comparable makefile fragment listing just the source
  29 files for the UTF-8 only version of the library.
  30
  31
  32 Using the library
  33 =================
  34
  35 The library provides a simple C API.  Essentially, a new stemmer can
  36 be obtained by using "sb_stemmer_new".  "sb_stemmer_stem" is then
  37 used to stem a word, "sb_stemmer_length" returns the stemmed
  38 length of the last word processed, and "sb_stemmer_delete" is
  39 used to delete a stemmer.
  40
  41 Creating a stemmer is a relatively expensive operation - the expected
  42 usage pattern is that a new stemmer is created when needed, used
  43 to stem many words, and deleted after some time.
  44
  45 Stemmers are re-entrant, but not threadsafe.  In other words, if
  46 you wish to access the same stemmer object from multiple threads,
  47 you must ensure that all access is protected by a mutex or similar
  48 device.
  49
  50 libstemmer does not currently incorporate any mechanism for caching the results
  51 of stemming operations.  Such caching can greatly increase the performance of a
  52 stemmer under certain situations, so suitable patches will be considered for
  53 inclusion.
  54
  55 The standard libstemmer sources contain an algorithm for each of the supported
  56 languages.  The algorithm may be selected using the english name of the
  57 language, or using the 2 or 3 letter ISO 639 language codes.  In addition,
  58 the traditional "Porter" stemming algorithm for english is included for
  59 backwards compatibility purposes, but we recommend use of the "English"
  60 stemmer in preference for new projects.
  61
  62 (Some minor algorithms which are included only as curiosities in the snowball
  63 website, such as the Lovins stemmer and the Kraaij Pohlmann stemmer, are not
  64 included in the standard libstemmer sources.  These are not really supported by
  65 the snowball project, but it would be possible to compile a modified libstemmer
  66 library containing these if desired.)
  67
  68
  69 The stemwords example
  70 =====================
  71
  72 The stemwords example program allows you to run any of the stemmers
  73 compiled into the libstemmer library on a sample vocabulary.  For
  74 details on how to use it, run it with the "-h" command line option.
  75
  76
  77 Using the library in a larger system
  78 ====================================
  79
  80 If you are incorporating the library into the build system of a larger
  81 program, I recommend copying the unpacked tarball without modification into
  82 a subdirectory of the sources of your program.  Future versions of the
  83 library are intended to keep the same structure, so this will keep the
  84 work required to move to a new version of the library to a minimum.
  85
  86 As an additional convenience, the list of source and header files used
  87 in the library is detailed in mkinc.mak - a file which is in a suitable
  88 format for inclusion by a Makefile.  By including this file in your build
  89 system, you can link the snowball system into your program with a few
  90 extra rules.
  91
  92 Using the library in a system using GNU autotools
  93 =================================================
  94
  95 The libstemmer_c library can be integrated into a larger system which uses the
  96 GNU autotool framework (and in particular, automake and autoconf) as follows:
  97
  98 1) Unpack libstemmer_c.tgz in the top level project directory so that there is
  99    a libstemmer_c subdirectory of the top level directory of the project.
 100
 101 2) Add a file "Makefile.am" to the unpacked libstemmer_c folder, containing:
 102
 103 noinst_LTLIBRARIES = libstemmer.la
 104 include $(srcdir)/mkinc.mak
 105 noinst_HEADERS = $(snowball_headers)
 106 libstemmer_la_SOURCES = $(snowball_sources)
 107
 108 (You may also need to add other lines to this, for example, if you are using
 109 compiler options which are not compatible with compiling the libstemmer
 110 library.)
 111
 112 3) Add libstemmer_c to the AC_CONFIG_FILES declaration in the project's
 113    configure.ac file.
 114
 115 4) Add to the top level makefile the following lines (or modify existing
 116    assignments to these variables appropriately):
 117
 118 AUTOMAKE_OPTIONS = subdir-objects
 119 AM_CPPFLAGS = -I$(top_srcdir)/libstemmer_c/include
 120 SUBDIRS=libstemmer_c
 121 <name>_LIBADD = libstemmer_c/libstemmer.la
 122
 123 (Where <name> is the name of the library or executable which links against
 124 libstemmer.)
 125