README
1LibParserUtils -- a utility library for parser building
2=======================================================
3
4Overview
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
16Requirements
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
32Compilation
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
54Verification
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
94API 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
105Disabling 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