summaryrefslogtreecommitdiff
path: root/README
blob: 1c8c4439e51a197a8233eb54a457251ce93d6beb (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
130
131
132
133
134
135
136
137
138
139
140
Hubbub -- an HTML parser
========================

Overview
--------

  Hubbub is a flexible HTML parser. It aims to comply with the HTML5
  specification.

Requirements
------------

  Hubbub requires the following tools:

    + A C99 capable C compiler
    + GNU make or compatible
    + Perl (for the testcases)
    + Pkg-config (for the testcases)
    + xsltproc (for the entity fetcher)
    + wget (for the entity fetcher)
    + doxygen (for the API documentation)

  Hubbub also requires the following libraries to be installed:

    + An iconv implementation (e.g. libiconv)
    + LibParserUtils -- see below for further information
    + JSON-C (for the testcases) -- see below for further information

  Hubbub can make use of the following, for debugging and testing purposes:

    + gcov and lcov, for test coverage data

LibParserUtils
--------------

  To compile Hubbub, you will need LibParserUtils.  This can be
  obtained from SVN:
  		$ svn co svn://svn.netsurf-browser.org/trunk/libparserutils/

  Follow the instructions in LibParserUtils' README file to build and 
  install it.

  Note: By default, libparserutils only supports a few character sets. It may, 
        however, be configured to use iconv() to provide charset conversion.
        See LibParserUtils' README for further information.

JSON-C
------

  To run tests, you will need JSON-C.  You can obtain the version
  that Hubbub needs from SVN:
  		$ svn co svn://svn.netsurf-browser.org/trunk/json-c/json-c/

  Build and install JSON-C as follows:

		$ sh autogen.sh
		$ make install

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 "examples" directory contains commented examples of how to use Hubbub.
  The test driver code in test/ may also provide some useful pointers.

A note on character set aliases
-------------------------------

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