summaryrefslogtreecommitdiff
path: root/README
blob: a4189320e7a52ce9cd1fbcdcd46ded766071c7cc (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
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.