LibParserUtils -- a utility library for parser building ======================================================= Overview -------- LibParserUtils provides various pieces of functionality that are useful when writing parsers. These are: + A number of character set convertors + Mapping of character set names to/from MIB enum values + UTF-8 and UTF-16 (host endian) support functions + Various simple data structures (resizeable buffer, stack, vector) + A UTF-8 input stream Requirements ------------ LibParserUtils requires the following tools: + A C99 capable C compiler + GNU make or compatible + Perl (for the testcases) + Pkg-config (for the testcases) + doxygen (for the API documentation) For enhanced charset support, LibParserUtils may also be configured to use an iconv() implementation, see the "Enabling iconv() support" section, below. Compilation ----------- The exact type of build may be configured by passing parameters to make. Common usage is described below. For a static library: $ make For a shared library: $ make COMPONENT_TYPE=lib-shared For a static library with debug enabled: $ make BUILD=debug To cross-compile a static library: $ make TARGET= Verification ------------ The library's functionality may be verified, thus: $ make test If you wish to see test coverage statistics, run: $ make coverage Then open build/coverage/index.html in a web browser. In both cases, ensure that the same parameters to make are passed as when building the library. (Un)installation ---------------- To install the library: $ make install Ensure that the same parameters to make are passed as when building the library. To specify the installation prefix: $ make install PREFIX=/path/to/prefix To specify a staging directory for packaging: $ make install DESTDIR=/path/to/directory Items will be installed to $(DESTDIR)$(PREFIX)/ To uninstall: $ make uninstall API documentation ----------------- Use doxygen to auto-generate API documentation, thus: $ make docs Then open build/docs/html/index.html in a web browser. The test driver code in test/ may also provide some useful pointers. Enabling iconv() support ------------------------ By default, libparserutils only supports the following character sets: + UTF-16 (platform-native endian) + UTF-8 + ISO-8859-n + Windows-125n + US-ASCII Support for more character sets may be enabled through the use of iconv(). To enable iconv() support in libparserutils, do the following: $ echo "CFLAGS += -DWITH_ICONV_FILTER" \ >build/Makefile.config.override Then build libparserutils as normal. A note on character set aliases ------------------------------- Libparserutils uses an external mapping file to encode relationships between character set names. This is the "Aliases" file. A copy may be found at test/data/Aliases. The path to this file is required when calling parserutils_initialise().