Subversion Repositories Kolibri OS

Rev

Go to most recent revision | Blame | Last modification | View Log | Download | RSS feed

  1. LibParserUtils -- a utility library for parser building
  2. =======================================================
  3.  
  4. Overview
  5. --------
  6.  
  7.   LibParserUtils provides various pieces of functionality that are useful
  8.   when writing parsers. These are:
  9.  
  10.   + A number of character set convertors
  11.   + Mapping of character set names to/from MIB enum values
  12.   + UTF-8 and UTF-16 (host endian) support functions
  13.   + Various simple data structures (resizeable buffer, stack, vector)
  14.   + A UTF-8 input stream
  15.  
  16. Requirements
  17. ------------
  18.  
  19.   LibParserUtils requires the following tools:
  20.  
  21.     + A C99 capable C compiler
  22.     + GNU make or compatible
  23.     + Perl (for the testcases)
  24.     + Pkg-config (for the testcases)
  25.     + doxygen (for the API documentation)
  26.  
  27.   For enhanced charset support, LibParserUtils requires an iconv()
  28.   implementation. If you don't have an implementation of iconv(),
  29.   this requirement may be disabled: see the "Disabling iconv()
  30.   support" section, below.
  31.  
  32. Compilation
  33. -----------
  34.  
  35.   The exact type of build may be configured by passing parameters to make.
  36.   Common usage is described below.
  37.  
  38.   For a static library:
  39.  
  40.                 $ make
  41.  
  42.   For a shared library:
  43.  
  44.                 $ make COMPONENT_TYPE=lib-shared
  45.  
  46.   For a static library with debug enabled:
  47.  
  48.                 $ make BUILD=debug
  49.  
  50.   To cross-compile a static library:
  51.  
  52.                 $ make TARGET=<target-platform>
  53.  
  54. Verification
  55. ------------
  56.  
  57.   The library's functionality may be verified, thus:
  58.  
  59.                 $ make test
  60.  
  61.   If you wish to see test coverage statistics, run:
  62.  
  63.                 $ make coverage
  64.  
  65.   Then open build/coverage/index.html in a web browser.
  66.  
  67.   In both cases, ensure that the same parameters to make are passed as when
  68.   building the library.
  69.  
  70. (Un)installation
  71. ----------------
  72.  
  73.   To install the library:
  74.  
  75.                 $ make install
  76.  
  77.   Ensure that the same parameters to make are passed as when building the
  78.   library.
  79.  
  80.   To specify the installation prefix:
  81.  
  82.                 $ make install PREFIX=/path/to/prefix
  83.  
  84.   To specify a staging directory for packaging:
  85.  
  86.                 $ make install DESTDIR=/path/to/directory
  87.  
  88.   Items will be installed to $(DESTDIR)$(PREFIX)/
  89.  
  90.   To uninstall:
  91.  
  92.                 $ make uninstall
  93.  
  94. API documentation
  95. -----------------
  96.  
  97.   Use doxygen to auto-generate API documentation, thus:
  98.  
  99.                 $ make docs
  100.  
  101.   Then open build/docs/html/index.html in a web browser.
  102.  
  103.   The test driver code in test/ may also provide some useful pointers.
  104.  
  105. Disabling iconv() support
  106. -------------------------
  107.  
  108.   Without iconv() support enabled, libparserutils only supports the
  109.   following character sets:
  110.  
  111.     + UTF-16 (platform-native endian)
  112.     + UTF-8
  113.     + ISO-8859-n
  114.     + Windows-125n
  115.     + US-ASCII
  116.  
  117.   To disable iconv() support in libparserutils, do the following:
  118.  
  119.                 $ echo "CFLAGS += -DWITHOUT_ICONV_FILTER" \
  120.                                 >Makefile.config.override
  121.  
  122.   Then build libparserutils as normal.
  123.  
  124.