summaryrefslogtreecommitdiff
path: root/README
blob: 15c0959b5d0adedfafa544ad72240fd0e63d61e9 (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
124
125
126
127
128
129
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=<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.

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().