michael@0: How to customize the compilation of the library michael@0: =============================================== michael@0: michael@0: FreeType is highly customizable to fit various needs, and this michael@0: document describes how it is possible to select options and michael@0: components at compilation time. michael@0: michael@0: michael@0: I. Configuration macros michael@0: michael@0: The file found in `include/config/ftoption.h' contains a list of michael@0: commented configuration macros that can be toggled by developers to michael@0: indicate which features should be active while building the library. michael@0: michael@0: These options range from debug level to availability of certain michael@0: features, like native TrueType hinting through a bytecode michael@0: interpreter. michael@0: michael@0: We invite you to read this file for more information. You can michael@0: change the file's content to suit your needs, or override it with michael@0: one of the techniques described below. michael@0: michael@0: michael@0: II. Modules list michael@0: michael@0: If you use GNU make please edit the top-level file `modules.cfg'. michael@0: It contains a list of available FreeType modules and extensions to michael@0: be compiled. Change it to suit your own preferences. Be aware that michael@0: certain modules depend on others, as described in the file. GNU michael@0: make uses `modules.cfg' to generate `ftmodule.h' (in the object michael@0: directory). michael@0: michael@0: If you build FreeType in a directory separate from the source files, michael@0: put your customized `modules.cfg' in that directory; that way you michael@0: can keep the source files `clean'. michael@0: michael@0: If you don't use GNU make you have to manually edit the file michael@0: `include/config/ftmodule.h' (which is *not* used with if compiled michael@0: with GNU make) to add or remove the drivers and components you want michael@0: to compile into the library. See `INSTALL.ANY' for more michael@0: information. michael@0: michael@0: michael@0: III. System interface michael@0: michael@0: FreeType's default interface to the system (i.e., the parts that michael@0: deal with memory management and i/o streams) is located in michael@0: `src/base/ftsystem.c'. michael@0: michael@0: The current implementation uses standard C library calls to manage michael@0: memory and to read font files. It is however possible to write michael@0: custom implementations to suit specific systems. michael@0: michael@0: To tell the GNU Make-based build system to use a custom system michael@0: interface, you have to define the environment variable FTSYS_SRC to michael@0: point to the relevant implementation: michael@0: michael@0: on Unix: michael@0: michael@0: ./configure michael@0: export FTSYS_SRC=foo/my_ftsystem.c michael@0: make michael@0: make install michael@0: michael@0: on Windows: michael@0: michael@0: make setup michael@0: set FTSYS_SRC=foo/my_ftsystem.c michael@0: make michael@0: michael@0: michael@0: IV. Overriding default configuration and module headers michael@0: michael@0: It is possible to override the default configuration and module michael@0: headers without changing the original files. There are three ways michael@0: to do that: michael@0: michael@0: michael@0: 1. With GNU make michael@0: michael@0: [This is actually a combination of method 2 and 3.] michael@0: michael@0: Just put your custom `ftoption.h' file into the objects directory michael@0: (normally `/objs' if you build in the source tree, or the michael@0: directory where you invoke configure if you build in a separate michael@0: directory), which GNU make prefers over the standard location. No michael@0: action is needed for `ftmodule.h' because it is generated michael@0: automatically in the objects directory. michael@0: michael@0: 2. Using the C include path michael@0: michael@0: Use the C include path to ensure that your own versions of the michael@0: files are used at compile time when the lines michael@0: michael@0: #include FT_CONFIG_OPTIONS_H michael@0: #include FT_CONFIG_MODULES_H michael@0: michael@0: are compiled. Their default values being and michael@0: , you can do something like: michael@0: michael@0: custom/ michael@0: config/ michael@0: ftoption.h => custom options header michael@0: ftmodule.h => custom modules list michael@0: michael@0: include/ => normal FreeType 2 include michael@0: ... michael@0: michael@0: then change the C include path to always give the path to `custom' michael@0: before the FreeType 2 `include'. michael@0: michael@0: michael@0: 3. Redefining FT_CONFIG_OPTIONS_H and FT_CONFIG_MODULES_H michael@0: michael@0: Another way to do the same thing is to redefine the macros used to michael@0: name the configuration headers. To do so, you need a custom michael@0: `ft2build.h' whose content can be as simple as: michael@0: michael@0: #ifndef __FT2_BUILD_MY_PLATFORM_H__ michael@0: #define __FT2_BUILD_MY_PLATFORM_H__ michael@0: michael@0: #define FT_CONFIG_OPTIONS_H michael@0: #define FT_CONFIG_MODULES_H michael@0: michael@0: #include michael@0: michael@0: #endif /* __FT2_BUILD_MY_PLATFORM_H__ */ michael@0: michael@0: Place those files in a separate directory, e.g., michael@0: michael@0: custom/ michael@0: ft2build.h => custom version described above michael@0: my-ftoption.h => custom options header michael@0: my-ftmodule.h => custom modules list header michael@0: michael@0: and change the C include path to ensure that `custom' is always michael@0: placed before the FT2 `include' during compilation. michael@0: michael@0: ---------------------------------------------------------------------- michael@0: michael@0: Copyright 2003, 2005, 2006, 2012, 2013 by michael@0: David Turner, Robert Wilhelm, and Werner Lemberg. michael@0: michael@0: This file is part of the FreeType project, and may only be used, michael@0: modified, and distributed under the terms of the FreeType project michael@0: license, LICENSE.TXT. By continuing to use, modify, or distribute michael@0: this file you indicate that you have read the license and understand michael@0: and accept it fully. michael@0: michael@0: michael@0: --- end of CUSTOMIZE ---