1# Configuring HarfBuzz
2
3Most of the time you will not need any custom configuration.  The configuration
4options provided by `configure` or `meson` should be enough.  In particular,
5if you just want HarfBuzz library plus hb-shape / hb-view utilities, make sure
6FreeType and Cairo are available and found during configuration.
7
8If you are building for distribution, you should more carefully consider whether
9you need Glib, ICU, Graphite2, as well as CoreText / Uniscribe / DWrite.  Make
10sure the relevant ones are enabled.
11
12If you are building for custom environment (embedded, downloadable app, etc)
13where you mostly just want to call `hb_shape()` and the binary size of the
14resulting library is very important to you, the rest of this file guides you
15through your options to disable features you may not need, in exchange for
16binary size savings.
17
18## Compiler Options
19
20Make sure you build with your compiler's "optimize for size" option.  On `gcc`
21this is `-Os`, and can be enabled by passing `CXXFLAGS=-Os` either to `configure`
22(sticky) or to `make` (non-sticky).  On clang there is an even more extreme flag,
23`-Oz`.
24
25HarfBuzz heavily uses inline functions and the optimize-size flag can make the
26library smaller by 20% or more.  Moreover, sometimes, based on the target CPU,
27the optimize-size builds perform *faster* as well, thanks to lower code
28footprint and caching effects.  So, definitely try that even if size is not
29extremely tight but you have a huge application.  For example, Chrome does
30that.  Note that this configuration also automatically enables certain internal
31optimizations.  Search for `HB_OPTIMIZE_SIZE` for details, if you are using
32other compilers, or continue reading.
33
34Another compiler option to consider is "link-time optimization", also known as
35'lto'.  To enable that, with `gcc` or `clang`, add `-flto` to both `CXXFLAGS`
36and `LDFLAGS`, either on `configure` invocation (sticky) or on `make` (non-sticky).
37This, also, can have a huge impact on the final size, 20% or more.
38
39Finally, if you are making a static library build or otherwise linking the
40library into your app, make sure your linker removes unused functions.  This
41can be tricky and differ from environment to environment, but you definitely
42want to make sure this happens.  Otherwise, every unused public function will
43be adding unneeded bytes to your binary.  The following pointers might come
44handy:
45
46 * https://lwn.net/Articles/741494/ (all of the four-part series)
47 * https://elinux.org/images/2/2d/ELC2010-gc-sections_Denys_Vlasenko.pdf
48
49Combining the above three build options should already shrink your library a lot.
50The rest of this file shows you ways to shrink the library even further at the
51expense of removing functionality (that may not be needed).  The remaining
52options are all enabled by defining pre-processor macros, which can be done
53via `CXXFLAGS` or `CPPFLAGS` similarly.
54
55
56## Unicode-functions
57
58Access to Unicode data can be configured at compile time as well as run-time.
59By default, HarfBuzz ships with its own compact subset of properties from
60Unicode Character Database that it needs.  This is a highly-optimized
61implementation that depending on compile settings (optimize-size or not)
62takes around ~40kb or ~60kb.  Using this implementation (default) is highly
63recommended, as HarfBuzz always ships with data from latest version of Unicode.
64This implementation can be disabled by defining `HB_NO_UCD`.
65
66For example, if you are enabling ICU as a built-in option, or GLib, those
67can provide Unicode data as well, so defining `HB_NO_UCD` might save you
68space without reducing functionality (to the extent that the Unicode version
69of those implementations is recent.)
70
71If, however, you provide your own Unicode data to HarfBuzz at run-time by
72calling `hb_buffer_set_unicode_funcs` on every buffer you create, and you do
73not rely on `hb_unicode_funcs_get_default()` results, you can disable the
74internal implementation by defining both `HB_NO_UCD` and `HB_NO_UNICODE_FUNCS`.
75The latter is needed to guard against accidentally building a library without
76any default Unicode implementations.
77
78
79## Font-functions
80
81Access to certain font functionalities can also be configured at run-time.  By
82default, HarfBuzz uses an efficient internal implementation of OpenType
83functionality for this.  This internal implementation is called `hb-ot-font`.
84All newly-created `hb_font_t` objects by default use `hb-ot-font`.  Using this
85is highly recommended, and is what fonts use by default when they are created.
86
87Most embedded uses will probably use HarfBuzz with FreeType using `hb-ft.h`.
88In that case, or if you otherwise provide those functions by calling
89`hb_font_set_funcs()` on every font you create, you can disable `hb-ot-font`
90without loss of functionality by defining `HB_NO_OT_FONT`.
91
92
93## Shapers
94
95Most HarfBuzz clients use it for the main shaper, called "ot".  However, it
96is legitimate to want to compile HarfBuzz with only another backend, eg.
97CoreText, for example for an iOS app.  For that, you want `HB_NO_OT_SHAPE`.
98If you are going down that route, check if you want `HB_NO_OT`.
99
100This is very rarely what you need.  Make sure you understand exactly what you
101are doing.
102
103Defining `HB_NO_FALLBACK_SHAPE` however is pretty harmless.  That removes the
104(unused) "fallback" shaper.
105
106
107## Thread-safety
108
109By default HarfBuzz builds as a thread-safe library.  The exception is that
110the `HB_TINY` predefined configuring (more below) disables thread-safety.
111
112If you do /not/ need thread-safety in the library (eg. you always call into
113HarfBuzz from the same thread), you can disable thread-safety by defining
114`HB_NO_MT`.  As noted already, this is enabled by `HB_TINY`.
115
116
117## Pre-defined configurations
118
119The [`hb-config.hh`](src/hb-config.hh) internal header supports three
120pre-defined configurations as well grouping of various configuration options.
121The pre-defined configurations are:
122
123  * `HB_MINI`: Disables shaping of AAT as well as legacy fonts.  Ie. it produces
124    a capable OpenType shaper only.
125
126  * `HB_LEAN`: Disables various non-shaping functionality in the library, as well
127    as esoteric or rarely-used shaping features.  See the definition for details.
128
129  * `HB_TINY`: Enables both `HB_MINI` and `HB_LEAN` configurations, as well as
130    disabling thread-safety and debugging, and use even more size-optimized data
131    tables.
132
133
134## Tailoring configuration
135
136Most of the time, one of the pre-defined configuration is exactly what one needs.
137Sometimes, however, the pre-defined configuration cuts out features that might
138be desired in the library.  Unfortunately there is no quick way to undo those
139configurations from the command-line.  But one can add a header file called
140`config-override.h` to undefine certain `HB_NO_*` symbols as desired.  Then
141define `HAVE_CONFIG_OVERRIDE_H` to make `hb-config.hh` include your configuration
142overrides at the end.
143
144
145## Notes
146
147Note that the config option `HB_NO_CFF`, which is enabled by `HB_LEAN` and
148`HB_TINY` does /not/ mean that the resulting library won't work with CFF fonts.
149The library can shape valid CFF fonts just fine, with or without this option.
150This option disables (among other things) the code to calculate glyph exntents
151for CFF fonts.
152