Merge branch 'upstream' into tizen

[platform/upstream/harfbuzz.git] / CONFIG.md

diff --git a/CONFIG.md b/CONFIG.md
index 8aa9b1b..f0fc065 100644 (file)
--- a/CONFIG.md
+++ b/CONFIG.md
@@ -1,9 +1,9 @@
 # Configuring HarfBuzz
 
 Most of the time you will not need any custom configuration.  The configuration
-options provided by `configure` or `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.
+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
@@ -18,9 +18,9 @@ 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` either to `configure`
-(sticky) or to `make` (non-sticky).  On clang there is an even more extreme flag,
-`-Oz`.
+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,
@@ -32,8 +32,7 @@ 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, with `gcc` or `clang`, add `-flto` to both `CXXFLAGS`
-and `LDFLAGS`, either on `configure` invocation (sticky) or on `make` (non-sticky).
+'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
@@ -101,15 +100,16 @@ 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.
+(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 configuring (more below) disables thread-safety.
+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
+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`.
 
@@ -136,16 +136,23 @@ The pre-defined configurations are:
 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.  But one can add a header file called
-`config-override.h` to undefine certain `HB_NO_*` symbols as desired.  Then
-define `HAVE_CONFIG_OVERRIDE_H` to make `hb-config.hh` include your configuration
-overrides at the end.
+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.
+`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 exntents
-for CFF fonts.
+This option disables (among other things) the code to calculate glyph extents
+for CFF fonts, which many clients might not need.