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