kc3-lang/harfbuzz/CONFIG.md
Branch
-
Show log
Commit
-
Hash : 49c8493f
Author :
Date : 2024-06-20T11:16:40
[test] Build with HB_MINI Also add CONFIG.md instructions for building configs with meson. Fixes https://github.com/harfbuzz/harfbuzz/issues/4760
Configuring HarfBuzz
Most of the time you will not need any custom configuration. The configuration
options provided by meson should be enough. In particular, if you just want
HarfBuzz library plus hb-shape / hb-view utilities, make sure FreeType and Cairo
are available and found during configuration.
If you are building for distribution, you should more carefully consider whether you need Glib, ICU, Graphite2, as well as CoreText / Uniscribe / DWrite. Make sure the relevant ones are enabled.
If you are building for custom environment (embedded, downloadable app, etc)
where you mostly just want to call hb_shape() and the binary size of the
resulting library is very important to you, the rest of this file guides you
through your options to disable features you may not need, in exchange for
binary size savings.
Compiler Options
Make sure you build with your compiler’s “optimize for size” option. On gcc
this is -Os, and can be enabled by passing CXXFLAGS=-Os. On clang there
is an even more extreme flag, -Oz. Meson also provides --buildtype=minsize
for more convenience.
HarfBuzz heavily uses inline functions and the optimize-size flag can make the
library smaller by 20% or more. Moreover, sometimes, based on the target CPU,
the optimize-size builds perform faster as well, thanks to lower code
footprint and caching effects. So, definitely try that even if size is not
extremely tight but you have a huge application. For example, Chrome does
that. Note that this configuration also automatically enables certain internal
optimizations. Search for HB_OPTIMIZE_SIZE for details, if you are using
other compilers, or continue reading.
Another compiler option to consider is “link-time optimization”, also known as
‘lto’. To enable that, feel free to use -Db_lto=true of meson.
This, also, can have a huge impact on the final size, 20% or more.
Finally, if you are making a static library build or otherwise linking the library into your app, make sure your linker removes unused functions. This can be tricky and differ from environment to environment, but you definitely want to make sure this happens. Otherwise, every unused public function will be adding unneeded bytes to your binary. The following pointers might come handy:
- https://lwn.net/Articles/741494/ (all of the four-part series)
- https://elinux.org/images/2/2d/ELC2010-gc-sections_Denys_Vlasenko.pdf
Combining the above three build options should already shrink your library a lot.
The rest of this file shows you ways to shrink the library even further at the
expense of removing functionality (that may not be needed). The remaining
options are all enabled by defining pre-processor macros, which can be done
via CXXFLAGS or CPPFLAGS similarly.
Unicode-functions
Access to Unicode data can be configured at compile time as well as run-time.
By default, HarfBuzz ships with its own compact subset of properties from
Unicode Character Database that it needs. This is a highly-optimized
implementation that depending on compile settings (optimize-size or not)
takes around ~40kb or ~60kb. Using this implementation (default) is highly
recommended, as HarfBuzz always ships with data from latest version of Unicode.
This implementation can be disabled by defining HB_NO_UCD.
For example, if you are enabling ICU as a built-in option, or GLib, those
can provide Unicode data as well, so defining HB_NO_UCD might save you
space without reducing functionality (to the extent that the Unicode version
of those implementations is recent.)
If, however, you provide your own Unicode data to HarfBuzz at run-time by
calling hb_buffer_set_unicode_funcs on every buffer you create, and you do
not rely on hb_unicode_funcs_get_default() results, you can disable the
internal implementation by defining both HB_NO_UCD and HB_NO_UNICODE_FUNCS.
The latter is needed to guard against accidentally building a library without
any default Unicode implementations.
Font-functions
Access to certain font functionalities can also be configured at run-time. By
default, HarfBuzz uses an efficient internal implementation of OpenType
functionality for this. This internal implementation is called hb-ot-font.
All newly-created hb_font_t objects by default use hb-ot-font. Using this
is highly recommended, and is what fonts use by default when they are created.
Most embedded uses will probably use HarfBuzz with FreeType using hb-ft.h.
In that case, or if you otherwise provide those functions by calling
hb_font_set_funcs() on every font you create, you can disable hb-ot-font
without loss of functionality by defining HB_NO_OT_FONT.
Shapers
Most HarfBuzz clients use it for the main shaper, called “ot”. However, it
is legitimate to want to compile HarfBuzz with only another backend, eg.
CoreText, for example for an iOS app. For that, you want HB_NO_OT_SHAPE.
If you are going down that route, check if you want HB_NO_OT.
This is very rarely what you need. Make sure you understand exactly what you are doing.
Defining HB_NO_FALLBACK_SHAPE however is pretty harmless. That removes the
(unused) “fallback” shaper. This is defined by the HB_TINY profile already
(more below).
Thread-safety
By default HarfBuzz builds as a thread-safe library. The exception is that
the HB_TINY predefined configuration (more below) disables thread-safety.
If you do not need thread-safety in the library (eg. you always call into
HarfBuzz from the same thread), you can disable thread-safety by defining
HB_NO_MT. As noted already, this is enabled by HB_TINY.
Pre-defined configurations
The hb-config.hh internal header supports three
pre-defined configurations as well grouping of various configuration options.
The pre-defined configurations are:
-
HB_MINI: Disables shaping of AAT as well as legacy fonts. Ie. it produces a capable OpenType shaper only. -
HB_LEAN: Disables various non-shaping functionality in the library, as well as esoteric or rarely-used shaping features. See the definition for details. -
HB_TINY: Enables bothHB_MINIandHB_LEANconfigurations, as well as disabling thread-safety and debugging, and use even more size-optimized data tables.
To setup the build with these options use something like:
$ meson setup build -Dcpp_args=-DHB_MINI -Dc_args=-DHB_MINITailoring configuration
Most of the time, one of the pre-defined configuration is exactly what one needs. Sometimes, however, the pre-defined configuration cuts out features that might be desired in the library. Unfortunately there is no quick way to undo those configurations from the command-line.
However, configuration can still be overridden from a file. To do that, add your
override instructions (mostly undef instructions) to a header file and define
the macro HB_CONFIG_OVERRIDE_H to the string containing to that header file’s
name. HarfBuzz will then include that file at the appropriate place during
configuration.
Up until HarfBuzz 3.1.2, the configuration override header file’s name was
fixed and called config-override.h, and was activated by defining the macro
HAVE_CONFIG_OVERRIDE_H. That still works.
Notes
Note that the config option HB_NO_CFF, which is enabled by HB_LEAN and
HB_TINY does not mean that the resulting library won’t work with CFF fonts.
The library can shape valid CFF fonts just fine, with or without this option.
This option disables (among other things) the code to calculate glyph extents
for CFF fonts or draw them, which many clients might not need.
Source
-
CONFIG.md
-
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 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162
# Configuring HarfBuzz Most of the time you will not need any custom configuration. The configuration options provided by `meson` should be enough. In particular, if you just want HarfBuzz library plus hb-shape / hb-view utilities, make sure FreeType and Cairo are available and found during configuration. If you are building for distribution, you should more carefully consider whether you need Glib, ICU, Graphite2, as well as CoreText / Uniscribe / DWrite. Make sure the relevant ones are enabled. If you are building for custom environment (embedded, downloadable app, etc) where you mostly just want to call `hb_shape()` and the binary size of the resulting library is very important to you, the rest of this file guides you through your options to disable features you may not need, in exchange for binary size savings. ## Compiler Options Make sure you build with your compiler's "optimize for size" option. On `gcc` this is `-Os`, and can be enabled by passing `CXXFLAGS=-Os`. On clang there is an even more extreme flag, `-Oz`. Meson also provides `--buildtype=minsize` for more convenience. HarfBuzz heavily uses inline functions and the optimize-size flag can make the library smaller by 20% or more. Moreover, sometimes, based on the target CPU, the optimize-size builds perform *faster* as well, thanks to lower code footprint and caching effects. So, definitely try that even if size is not extremely tight but you have a huge application. For example, Chrome does that. Note that this configuration also automatically enables certain internal optimizations. Search for `HB_OPTIMIZE_SIZE` for details, if you are using other compilers, or continue reading. Another compiler option to consider is "link-time optimization", also known as 'lto'. To enable that, feel free to use `-Db_lto=true` of meson. This, also, can have a huge impact on the final size, 20% or more. Finally, if you are making a static library build or otherwise linking the library into your app, make sure your linker removes unused functions. This can be tricky and differ from environment to environment, but you definitely want to make sure this happens. Otherwise, every unused public function will be adding unneeded bytes to your binary. The following pointers might come handy: * https://lwn.net/Articles/741494/ (all of the four-part series) * https://elinux.org/images/2/2d/ELC2010-gc-sections_Denys_Vlasenko.pdf Combining the above three build options should already shrink your library a lot. The rest of this file shows you ways to shrink the library even further at the expense of removing functionality (that may not be needed). The remaining options are all enabled by defining pre-processor macros, which can be done via `CXXFLAGS` or `CPPFLAGS` similarly. ## Unicode-functions Access to Unicode data can be configured at compile time as well as run-time. By default, HarfBuzz ships with its own compact subset of properties from Unicode Character Database that it needs. This is a highly-optimized implementation that depending on compile settings (optimize-size or not) takes around ~40kb or ~60kb. Using this implementation (default) is highly recommended, as HarfBuzz always ships with data from latest version of Unicode. This implementation can be disabled by defining `HB_NO_UCD`. For example, if you are enabling ICU as a built-in option, or GLib, those can provide Unicode data as well, so defining `HB_NO_UCD` might save you space without reducing functionality (to the extent that the Unicode version of those implementations is recent.) If, however, you provide your own Unicode data to HarfBuzz at run-time by calling `hb_buffer_set_unicode_funcs` on every buffer you create, and you do not rely on `hb_unicode_funcs_get_default()` results, you can disable the internal implementation by defining both `HB_NO_UCD` and `HB_NO_UNICODE_FUNCS`. The latter is needed to guard against accidentally building a library without any default Unicode implementations. ## Font-functions Access to certain font functionalities can also be configured at run-time. By default, HarfBuzz uses an efficient internal implementation of OpenType functionality for this. This internal implementation is called `hb-ot-font`. All newly-created `hb_font_t` objects by default use `hb-ot-font`. Using this is highly recommended, and is what fonts use by default when they are created. Most embedded uses will probably use HarfBuzz with FreeType using `hb-ft.h`. In that case, or if you otherwise provide those functions by calling `hb_font_set_funcs()` on every font you create, you can disable `hb-ot-font` without loss of functionality by defining `HB_NO_OT_FONT`. ## Shapers Most HarfBuzz clients use it for the main shaper, called "ot". However, it is legitimate to want to compile HarfBuzz with only another backend, eg. CoreText, for example for an iOS app. For that, you want `HB_NO_OT_SHAPE`. If you are going down that route, check if you want `HB_NO_OT`. This is very rarely what you need. Make sure you understand exactly what you are doing. Defining `HB_NO_FALLBACK_SHAPE` however is pretty harmless. That removes the (unused) "fallback" shaper. This is defined by the `HB_TINY` profile already (more below). ## Thread-safety By default HarfBuzz builds as a thread-safe library. The exception is that the `HB_TINY` predefined configuration (more below) disables thread-safety. If you do *not* need thread-safety in the library (eg. you always call into HarfBuzz from the same thread), you can disable thread-safety by defining `HB_NO_MT`. As noted already, this is enabled by `HB_TINY`. ## Pre-defined configurations The [`hb-config.hh`](src/hb-config.hh) internal header supports three pre-defined configurations as well grouping of various configuration options. The pre-defined configurations are: * `HB_MINI`: Disables shaping of AAT as well as legacy fonts. Ie. it produces a capable OpenType shaper only. * `HB_LEAN`: Disables various non-shaping functionality in the library, as well as esoteric or rarely-used shaping features. See the definition for details. * `HB_TINY`: Enables both `HB_MINI` and `HB_LEAN` configurations, as well as disabling thread-safety and debugging, and use even more size-optimized data tables. To setup the build with these options use something like: ``` $ meson setup build -Dcpp_args=-DHB_MINI -Dc_args=-DHB_MINI ``` ## Tailoring configuration Most of the time, one of the pre-defined configuration is exactly what one needs. Sometimes, however, the pre-defined configuration cuts out features that might be desired in the library. Unfortunately there is no quick way to undo those configurations from the command-line. However, configuration can still be overridden from a file. To do that, add your override instructions (mostly `undef` instructions) to a header file and define the macro `HB_CONFIG_OVERRIDE_H` to the string containing to that header file's name. HarfBuzz will then include that file at the appropriate place during configuration. Up until HarfBuzz 3.1.2, the configuration override header file's name was fixed and called `config-override.h`, and was activated by defining the macro `HAVE_CONFIG_OVERRIDE_H`. That still works. ## Notes Note that the config option `HB_NO_CFF`, which is enabled by `HB_LEAN` and `HB_TINY` does *not* mean that the resulting library won't work with CFF fonts. The library can shape valid CFF fonts just fine, with or without this option. This option disables (among other things) the code to calculate glyph extents for CFF fonts or draw them, which many clients might not need.