1 How to customize the compilation of the library 2 =============================================== 3 4 FreeType is highly customizable to fit various needs, and this 5 document describes how it is possible to select options and 6 components at compilation time. 7 8 9 I. Configuration macros 10 11 The file `include/freetype/config/ftoption.h' contains a list of 12 commented configuration macros that can be toggled by developers to 13 indicate which features should be active while building the library. 14 15 These options range from debug level to availability of certain 16 features, like native TrueType hinting through a bytecode 17 interpreter. 18 19 We invite you to read this file for more information. You can 20 change the file's content to suit your needs, or override it with 21 one of the techniques described below. 22 23 24 II. Modules list 25 26 If you use GNU make please edit the top-level file `modules.cfg'. 27 It contains a list of available FreeType modules and extensions to 28 be compiled. Change it to suit your own preferences. Be aware that 29 certain modules depend on others, as described in the file. GNU 30 make uses `modules.cfg' to generate `ftmodule.h' (in the object 31 directory). 32 33 If you build FreeType in a directory separate from the source files, 34 put your customized `modules.cfg' in that directory; that way you 35 can keep the source files `clean'. 36 37 If you don't use GNU make you have to manually edit the file 38 `include/freetype/config/ftmodule.h' (which is *not* used with if 39 compiled with GNU make) to add or remove the drivers and components 40 you want to compile into the library. See `INSTALL.ANY' for more 41 information. 42 43 44 III. System interface 45 46 FreeType's default interface to the system (i.e., the parts that 47 deal with memory management and i/o streams) is located in 48 `src/base/ftsystem.c'. 49 50 The current implementation uses standard C library calls to manage 51 memory and to read font files. It is however possible to write 52 custom implementations to suit specific systems. 53 54 To tell the GNU Make-based build system to use a custom system 55 interface, you have to define the environment variable FTSYS_SRC to 56 point to the relevant implementation: 57 58 on Unix: 59 60 ./configure <your options> 61 export FTSYS_SRC=foo/my_ftsystem.c 62 make 63 make install 64 65 on Windows: 66 67 make setup <compiler> 68 set FTSYS_SRC=foo/my_ftsystem.c 69 make 70 71 72 IV. Overriding default configuration and module headers 73 74 It is possible to override the default configuration and module 75 headers without changing the original files. There are three ways 76 to do that: 77 78 79 1. With GNU make 80 81 [This is actually a combination of method 2 and 3.] 82 83 Just put your custom `ftoption.h' file into the objects directory 84 (normally `<topdir>/objs' if you build in the source tree, or the 85 directory where you invoke configure if you build in a separate 86 directory), which GNU make prefers over the standard location. No 87 action is needed for `ftmodule.h' because it is generated 88 automatically in the objects directory. 89 90 2. Using the C include path 91 92 Use the C include path to ensure that your own versions of the 93 files are used at compile time when the lines 94 95 #include FT_CONFIG_OPTIONS_H 96 #include FT_CONFIG_MODULES_H 97 98 are compiled. Their default values being 99 <freetype/config/ftoption.h> and <freetype/config/ftmodule.h>, you 100 can do something like: 101 102 custom/ 103 config/ 104 ftoption.h => custom options header 105 ftmodule.h => custom modules list 106 107 include/ => normal FreeType 2 include 108 ... 109 110 then change the C include path to always give the path to `custom' 111 before the FreeType 2 `include'. 112 113 114 3. Redefining FT_CONFIG_OPTIONS_H and FT_CONFIG_MODULES_H 115 116 Another way to do the same thing is to redefine the macros used to 117 name the configuration headers. To do so, you need a custom 118 `ft2build.h' whose content can be as simple as: 119 120 #ifndef FT2_BUILD_MY_PLATFORM_H_ 121 #define FT2_BUILD_MY_PLATFORM_H_ 122 123 #define FT_CONFIG_OPTIONS_H <custom/my-ftoption.h> 124 #define FT_CONFIG_MODULES_H <custom/my-ftmodule.h> 125 126 #include <freetype/config/ftheader.h> 127 128 #endif /* FT2_BUILD_MY_PLATFORM_H_ */ 129 130 Place those files in a separate directory, e.g., 131 132 custom/ 133 ft2build.h => custom version described above 134 my-ftoption.h => custom options header 135 my-ftmodule.h => custom modules list header 136 137 and change the C include path to ensure that `custom' is always 138 placed before the FT2 `include' during compilation. 139 140 ---------------------------------------------------------------------- 141 142 Copyright 2003-2018 by 143 David Turner, Robert Wilhelm, and Werner Lemberg. 144 145 This file is part of the FreeType project, and may only be used, 146 modified, and distributed under the terms of the FreeType project 147 license, LICENSE.TXT. By continuing to use, modify, or distribute 148 this file you indicate that you have read the license and understand 149 and accept it fully. 150 151 152 --- end of CUSTOMIZE --- 153
