forked from KolibriOS/kolibrios
124 lines
2.7 KiB
Plaintext
124 lines
2.7 KiB
Plaintext
|
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 requires an iconv()
|
||
|
|
implementation. If you don't have an implementation of iconv(),
|
||
|
|
this requirement may be disabled: see the "Disabling 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=<target-platform>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
Disabling iconv() support
|
||
|
|
-------------------------
|
||
|
|
|
||
|
|
Without iconv() support enabled, libparserutils only supports the
|
||
|
|
following character sets:
|
||
|
|
|
||
|
|
+ UTF-16 (platform-native endian)
|
||
|
|
+ UTF-8
|
||
|
|
+ ISO-8859-n
|
||
|
|
+ Windows-125n
|
||
|
|
+ US-ASCII
|
||
|
|
|
||
|
|
To disable iconv() support in libparserutils, do the following:
|
||
|
|
|
||
|
|
$ echo "CFLAGS += -DWITHOUT_ICONV_FILTER" \
|
||
|
|
>Makefile.config.override
|
||
|
|
|
||
|
|
Then build libparserutils as normal.
|
||
|
|
|