1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/modules/freetype2/docs/CUSTOMIZE Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,151 @@
1.4 +How to customize the compilation of the library
1.5 +===============================================
1.6 +
1.7 + FreeType is highly customizable to fit various needs, and this
1.8 + document describes how it is possible to select options and
1.9 + components at compilation time.
1.10 +
1.11 +
1.12 +I. Configuration macros
1.13 +
1.14 + The file found in `include/config/ftoption.h' contains a list of
1.15 + commented configuration macros that can be toggled by developers to
1.16 + indicate which features should be active while building the library.
1.17 +
1.18 + These options range from debug level to availability of certain
1.19 + features, like native TrueType hinting through a bytecode
1.20 + interpreter.
1.21 +
1.22 + We invite you to read this file for more information. You can
1.23 + change the file's content to suit your needs, or override it with
1.24 + one of the techniques described below.
1.25 +
1.26 +
1.27 +II. Modules list
1.28 +
1.29 + If you use GNU make please edit the top-level file `modules.cfg'.
1.30 + It contains a list of available FreeType modules and extensions to
1.31 + be compiled. Change it to suit your own preferences. Be aware that
1.32 + certain modules depend on others, as described in the file. GNU
1.33 + make uses `modules.cfg' to generate `ftmodule.h' (in the object
1.34 + directory).
1.35 +
1.36 + If you build FreeType in a directory separate from the source files,
1.37 + put your customized `modules.cfg' in that directory; that way you
1.38 + can keep the source files `clean'.
1.39 +
1.40 + If you don't use GNU make you have to manually edit the file
1.41 + `include/config/ftmodule.h' (which is *not* used with if compiled
1.42 + with GNU make) to add or remove the drivers and components you want
1.43 + to compile into the library. See `INSTALL.ANY' for more
1.44 + information.
1.45 +
1.46 +
1.47 +III. System interface
1.48 +
1.49 + FreeType's default interface to the system (i.e., the parts that
1.50 + deal with memory management and i/o streams) is located in
1.51 + `src/base/ftsystem.c'.
1.52 +
1.53 + The current implementation uses standard C library calls to manage
1.54 + memory and to read font files. It is however possible to write
1.55 + custom implementations to suit specific systems.
1.56 +
1.57 + To tell the GNU Make-based build system to use a custom system
1.58 + interface, you have to define the environment variable FTSYS_SRC to
1.59 + point to the relevant implementation:
1.60 +
1.61 + on Unix:
1.62 +
1.63 + ./configure <your options>
1.64 + export FTSYS_SRC=foo/my_ftsystem.c
1.65 + make
1.66 + make install
1.67 +
1.68 + on Windows:
1.69 +
1.70 + make setup <compiler>
1.71 + set FTSYS_SRC=foo/my_ftsystem.c
1.72 + make
1.73 +
1.74 +
1.75 +IV. Overriding default configuration and module headers
1.76 +
1.77 + It is possible to override the default configuration and module
1.78 + headers without changing the original files. There are three ways
1.79 + to do that:
1.80 +
1.81 +
1.82 + 1. With GNU make
1.83 +
1.84 + [This is actually a combination of method 2 and 3.]
1.85 +
1.86 + Just put your custom `ftoption.h' file into the objects directory
1.87 + (normally `<topdir>/objs' if you build in the source tree, or the
1.88 + directory where you invoke configure if you build in a separate
1.89 + directory), which GNU make prefers over the standard location. No
1.90 + action is needed for `ftmodule.h' because it is generated
1.91 + automatically in the objects directory.
1.92 +
1.93 + 2. Using the C include path
1.94 +
1.95 + Use the C include path to ensure that your own versions of the
1.96 + files are used at compile time when the lines
1.97 +
1.98 + #include FT_CONFIG_OPTIONS_H
1.99 + #include FT_CONFIG_MODULES_H
1.100 +
1.101 + are compiled. Their default values being <config/ftoption.h> and
1.102 + <config/ftmodule.h>, you can do something like:
1.103 +
1.104 + custom/
1.105 + config/
1.106 + ftoption.h => custom options header
1.107 + ftmodule.h => custom modules list
1.108 +
1.109 + include/ => normal FreeType 2 include
1.110 + ...
1.111 +
1.112 + then change the C include path to always give the path to `custom'
1.113 + before the FreeType 2 `include'.
1.114 +
1.115 +
1.116 + 3. Redefining FT_CONFIG_OPTIONS_H and FT_CONFIG_MODULES_H
1.117 +
1.118 + Another way to do the same thing is to redefine the macros used to
1.119 + name the configuration headers. To do so, you need a custom
1.120 + `ft2build.h' whose content can be as simple as:
1.121 +
1.122 + #ifndef __FT2_BUILD_MY_PLATFORM_H__
1.123 + #define __FT2_BUILD_MY_PLATFORM_H__
1.124 +
1.125 + #define FT_CONFIG_OPTIONS_H <custom/my-ftoption.h>
1.126 + #define FT_CONFIG_MODULES_H <custom/my-ftmodule.h>
1.127 +
1.128 + #include <config/ftheader.h>
1.129 +
1.130 + #endif /* __FT2_BUILD_MY_PLATFORM_H__ */
1.131 +
1.132 + Place those files in a separate directory, e.g.,
1.133 +
1.134 + custom/
1.135 + ft2build.h => custom version described above
1.136 + my-ftoption.h => custom options header
1.137 + my-ftmodule.h => custom modules list header
1.138 +
1.139 + and change the C include path to ensure that `custom' is always
1.140 + placed before the FT2 `include' during compilation.
1.141 +
1.142 +----------------------------------------------------------------------
1.143 +
1.144 +Copyright 2003, 2005, 2006, 2012, 2013 by
1.145 +David Turner, Robert Wilhelm, and Werner Lemberg.
1.146 +
1.147 +This file is part of the FreeType project, and may only be used,
1.148 +modified, and distributed under the terms of the FreeType project
1.149 +license, LICENSE.TXT. By continuing to use, modify, or distribute
1.150 +this file you indicate that you have read the license and understand
1.151 +and accept it fully.
1.152 +
1.153 +
1.154 +--- end of CUSTOMIZE ---
