thirdparty/freetype-2.3.12/builds/mac/README

   1 This folder contains
   2
   3   * Makefile skeltons for Apple MPW (Macintosh's Programmers Workshop)
   4
   5   * Python script to generate MPW makefile from skelton
   6
   7   * Metrowerks CodeWarrior 9.0 project file in XML format
   8
   9 ------------------------------------------------------------
  10
  11 1. What is this
  12 ---------------
  13
  14 Files in this directory are designed to build FreeType
  15 running on classic MacOS. To build FreeType running on
  16 Mac OS X, build as the system is UNIX.
  17
  18 However, Mac OS X is most useful to manipulate files in
  19 vanilla FreeType to fit classic MacOS.
  20
  21 The information about MacOS specific API is written in
  22 appendix of this document.
  23
  24 2. Requirement
  25 --------------
  26
  27 You can use MPW: a free-charged developer environment
  28 by Apple, or CodeWarrior: a commercial developer
  29 environment by Metrowerks. GCC for MPW and Symantec
  30 "Think C" are not tested at present.
  31
  32
  33   2-1. Apple MPW
  34   --------------
  35
  36   Following C compilers are tested:
  37
  38       m68k target:      Apple SC  8.9.0d3e1
  39       ppc  target:      Apple MrC 5.0.0d3c1
  40
  41   The final MPW-GM (official release on 1999/Dec) is too
  42   old and cannot compile FreeType, because bundled C
  43   compilers cannot search header files in sub directories.
  44   Updating by the final MPW-PR (pre-release on 2001/Feb)
  45   is required.
  46
  47   Required files are downloadable from:
  48
  49       http://developer.apple.com/tools/mpw-tools/index.html
  50
  51   Also you can find documents how to update by MPW-PR.
  52
  53   Python is required to restore MPW makefiles from the
  54   skeltons. Python bundled to Mac OS X is enough. For
  55   classic MacOS, MacPython is available:
  56
  57       http://homepages.cwi.nl/~jack/macpython/
  58
  59   MPW requires all files are typed by resource fork.
  60   ResEdit bundled to MPW is enough. In Mac OS X,
  61   /Developer/Tools/SetFile of DevTool is useful to
  62   manipulate from commandline.
  63
  64   2-2. Metrowerks CodeWarrior
  65   ---------------------------
  66
  67   XML project file is generated and tested by
  68   CodeWarrior 9.0.  Older versions are not tested
  69   at all. At present, static library for ppc target
  70   is available in the project file.
  71
  72
  73 3. How to build
  74 ---------------
  75
  76   3-1. Apple MPW
  77   --------------
  78   Detailed building procedure by Apple MPW is
  79   described in following.
  80
  81     3-1-1. Generate MPW makefiles from the skeltons
  82     ------------------------------------------------
  83
  84     Here are 4 skeltons for following targets are
  85     included.
  86
  87     - FreeType.m68k_far.make.txt
  88       Ancient 32bit binary executable format for
  89       m68k MacOS: System 6, with 32bit addressing
  90       mode (far-pointer-model) So-called "Toolbox"
  91       API is used.
  92
  93     - FreeType.m68k_cfm.make.txt
  94       CFM binary executable format for m68k MacOS:
  95       System 7. So-called "Toolbox" API is used.
  96
  97     - FreeType.ppc_classic.make.txt
  98       CFM binary executable format for ppc MacOS:
  99       System 7, MacOS 8, MacOS 9. So-called "Toolbox"
 100       API is used.
 101
 102     - FreeType.ppc_carbon.make.txt
 103       CFM binary executable format for ppc MacOS:
 104       MacOS 9. Carbon API is used.
 105
 106     At present, static library is only supported,
 107     although targets except of m68k_far are capable
 108     to use shared library.
 109
 110     MPW makefile syntax uses 8bit characters. To keep
 111     from violating them during version control, here
 112     we store skeltons in pure ASCII format. You must
 113     generate MPW makefile by Python script ascii2mpw.py.
 114
 115     In Mac OS X terminal, you can convert as:
 116
 117         python builds/mac/ascii2mpw.py \
 118                 < builds/mac/FreeType.m68k_far.make.txt \
 119                 > FreeType.m68k_far.make
 120
 121     The skeltons are designed to use in the top
 122     directory where there are builds, include, src etc.
 123     You must name the generated MPW makefile by removing
 124     ".txt" from source skelton name.
 125
 126     3-1-2. Add resource forks to related files
 127     ------------------------------------------
 128
 129     MPW's Make and C compilers cannot recognize files
 130     without resource fork. You have to add resource
 131     fork to the files that MPW uses. In Mac OS X
 132     terminal of the system, you can do as:
 133
 134         find . -name '*.[ch]' -exec \
 135                 /Developer/Tools/SetFile -a l -c "MPS " -t TEXT \{\} \;
 136
 137         find . -name '*.make' -exec \
 138                 /Developer/Tools/SetFile -a l -c "MPS " -t TEXT \{\} \;
 139
 140
 141     3-1-3. Open MPW shell and build
 142     -------------------------------
 143
 144     Open MPW shell and go to the top directory that
 145     FreeType sources are extracted (MPW makefile must
 146     be located in there), from "Set Directory" in
 147     "Directory" menu.
 148
 149     Choose "Build" from "Build" menu, and type the
 150     name of project by removing ".make" from MPW
 151     makefile, as: FreeType.m68k_far
 152
 153     If building is successfully finished, you can find
 154     built library in objs/ directory.
 155
 156
 157   3-2. Metrowerks CodeWarrior
 158   ---------------------------
 159
 160   Detailed building procedure by Metrowerks
 161   CodeWarrior (CW) 9.0 is described in following.
 162
 163     3-2-1. Import XML project file
 164     ------------------------------
 165
 166     CW XML project file is not ready for double-
 167     click. Start CodeWarrior IDE, and choose
 168     "Import project" in "File" menu. Choose XML
 169     project file: builds/mac/ftlib.prj.xml.
 170     In next, you will be asked where to save CW
 171     native project file: you must choose
 172     "builds/mac/ftlib.prj". The project file is
 173     designed with relative path from there. After
 174     CW native project file is generated, it is
 175     automatically loaded, small project window
 176     titled "ftlib.prj" is displayed.
 177
 178     3-2-2. Building
 179     ---------------
 180     Choose "Make" from "Project" menu. If building
 181     is successfully finished, you can find built
 182     library at objs/FreeTypeLib.
 183
 184 4. TODO
 185 -------
 186
 187   4-1. All modules should be included
 188   -----------------------------------
 189
 190   At present, MPW makefiles and CW project file are
 191   just updated versions of these by Leonard. Some
 192   modules are added after the last maintenance, they
 193   are not included.
 194
 195   4-2. Working test with ftdemos
 196   ------------------------------
 197
 198   At present, MPW makefiles and CW project file can
 199   build FreeType for classic MacOS. But their working
 200   behaviours are not tested at all. Building ftdemos
 201   for classic MacOS and working test is required.
 202
 203   4-3. Porting Jam onto MPW
 204   -------------------------
 205
 206   FreeType uses Jam (and FT-Jam) for unified cross-
 207   platform building tool. At present, Jam is not ported
 208   to MPW. To update classic MacOS support easily,
 209   building by Jam is expected on MPW.
 210
 211
 212 APPENDIX I
 213 ----------
 214
 215   A-1. Framework dependencies
 216   ---------------------------
 217
 218   src/base/ftmac.c adds two Mac-specific features to
 219   FreeType. These features are based on MacOS libraries.
 220
 221   * accessing resource-fork font
 222   The fonts for classic MacOS store their graphical data
 223   in resource forks which cannot be accessed via ANSI C
 224   functions. FreeType2 provides functions to handle such
 225   resource fork fonts, they are based on File Manager
 226   framework of MacOS. In addition, HFS and HFS+ file
 227   system driver of Linux is supported. Following
 228   functions are for this purpose.
 229
 230     FT_New_Face_From_Resource()
 231     FT_New_Face_From_FSSpec()
 232     FT_New_Face_From_FSRef()
 233
 234   * resolving font name to font file
 235   The font menu of MacOS application prefers font name
 236   written in FOND resource than sfnt resource. FreeType2
 237   provides functions to find font file by name in MacOS
 238   application, they are based on QuickDraw Font Manager
 239   and Apple Type Service framework of MacOS.
 240
 241     FT_GetFile_From_Mac_Name()
 242     FT_GetFile_From_Mac_ATS_Name()
 243
 244   Working functions for each MacOS are summarized as
 245   following.
 246
 247   upto MacOS 6:
 248     not tested (you have to obtain MPW 2.x)
 249
 250   MacOS 7.x, 8.x, 9.x (without CarbonLib):
 251     FT_GetFile_From_Mac_Name()
 252     FT_New_Face_From_Resource()
 253     FT_New_Face_From_FSSpec()
 254
 255   MacOS 9.x (with CarbonLib):
 256     FT_GetFile_From_Mac_Name()
 257     FT_New_Face_From_Resource()
 258     FT_New_Face_From_FSSpec()
 259     FT_New_Face_From_FSRef()
 260
 261   Mac OS X upto 10.4.x:
 262     FT_GetFile_From_Mac_Name()     deprecated
 263     FT_New_Face_From_FSSpec()      deprecated
 264     FT_GetFile_From_Mac_ATS_Name() deprecated?
 265     FT_New_Face_From_FSRef()
 266
 267   A-2. Deprecated Functions
 268   -------------------------
 269
 270     A-2-1. FileManager
 271     ------------------
 272
 273     For convenience to write MacOS application, ftmac.c
 274     provides functions to specify a file by FSSpec and FSRef,
 275     because the file identification pathname had ever been
 276     unrecommended method in MacOS programming.
 277
 278     Toward to MacOS X 10.4 & 5, Carbon functions using FSSpec
 279     datatype is noticed as deprecated, and recommended to
 280     migrate to FSRef datatype. The big differences of FSRef
 281     against FSSpec are explained in Apple TechNotes 2078.
 282
 283     http://developer.apple.com/technotes/tn2002/tn2078.html
 284
 285     - filename length: the max length of file
 286     name of FSRef is 255 chars (it is limit of HFS+),
 287     that of FSSpec is 31 chars (it is limit of HFS).
 288
 289     - filename encoding: FSSpec is localized by
 290     legacy encoding for each language system,
 291     FSRef is Unicode enabled.
 292
 293     A-2-2. FontManager
 294     ------------------
 295
 296     Following functions receive QuickDraw fontname:
 297
 298       FT_GetFile_From_Mac_Name()
 299
 300     QuickDraw is deprecated and replaced by Quartz
 301     since Mac OS X 10.4. They are still kept for
 302     backward compatibility. By undefinition of
 303     HAVE_QUICKDRAW in building, you can change these
 304     functions to return FT_Err_Unimplemented always.
 305
 306     Replacement functions are added for migration.
 307
 308       FT_GetFile_From_Mac_ATS_Name()
 309
 310     They are usable on Mac OS X only. On older systems,
 311     these functions return FT_Err_Unimplemented always.
 312
 313     The detailed incompatibilities and possibility
 314     of FontManager emulation without QuickDraw is
 315     explained in
 316
 317       http://www.gyve.org/~mpsuzuki/ats_benchmark.html
 318
 319   A-3. Framework Availabilities
 320   -----------------------------
 321
 322   The framework of MacOS are often revised, especially
 323   when new format of binary executable is introduced.
 324   Following table is the minimum version of frameworks
 325   to use functions used in FreeType2. The table is
 326   extracted from MPW header files for assembly language.
 327
 328   *** NOTE ***
 329   The conditional definition of available data type
 330   in MPW compiler is insufficient. You can compile
 331   program using FSRef data type for older systems
 332   (MacOS 7, 8) that don't know FSRef data type.
 333
 334
 335                                       +-------------------+-----------------------------+
 336            CPU                        |      mc680x0      |           PowerPC           |
 337                                       +---------+---------+---------+---------+---------+
 338   Binary Executable Format            | Classic | 68K-CFM | CFM     | CFM     | Mach-O  |
 339                                       +---------+---------+---------+---------+---------+
 340        Framework API                  | Toolbox | Toolbox | Toolbox | Carbon  | Carbon  |
 341                                       +---------+---------+---------+---------+---------+
 342
 343                                       +---------+---------+---------+---------+---------+
 344                                       |    ?(*) |Interface|Interface|CarbonLib|Mac OS X |
 345                                       |         |Lib      |Lib      |         |         |
 346 * Files.h                             +---------+---------+---------+---------+---------+
 347 PBGetFCBInfoSync()                    |    o    | 7.1-    | 7.1-    | 1.0-    |    o    |
 348 FSMakeFSSpec()                        |    o    | 7.1-    | 7.1-    | 1.0-    |    o    |
 349 FSGetForkCBInfo()                     |    o    |   (**)  | 9.0-    | 1.0-    |    o    |
 350 FSpMakeFSRef()                        |    o    |   (**)  | 9.0-    | 1.0-    |    o    |
 351 FSGetCatalogInfo()                    |    o    |   (**)  | 9.0-    | 1.0-    |   -10.3 |
 352 FSPathMakeRef()                       |    x    |    x    |    x    | 1.1-    |   -10.3 |
 353                                       +---------+---------+---------+---------+---------+
 354
 355                                       +---------+---------+---------+---------+---------+
 356                                       |    ?(*) |Font     |Font     |CarbonLib|Mac OS X |
 357                                       |         |Manager  |Manager  |         |         |
 358 * Fonts.h                             +---------+---------+---------+---------+---------+
 359 FMCreateFontFamilyIterator()          |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |
 360 FMDisposeFontFamilyIterator()         |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |
 361 FMGetNextFontFamily()                 |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |
 362 FMGetFontFamilyName()                 |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |
 363 FMCreateFontFamilyInstanceIterator()  |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |
 364 FMDisposeFontFamilyInstanceIterator() |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |
 365 FMGetNextFontFamilyInstance()         |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |
 366                                       +---------+---------+---------+---------+---------+
 367
 368                                       +---------+---------+---------+---------+---------+
 369                                       |    -    |    -    |    -    |CarbonLib|Mac OS X |
 370 * ATSFont.h (***)                     +---------+---------+---------+---------+---------+
 371 ATSFontFindFromName()                 |    x    |    x    |    x    |    x    |    o    |
 372 ATSFontGetFileSpecification()         |    x    |    x    |    x    |    x    |    o    |
 373                                       +---------+---------+---------+---------+---------+
 374
 375     (*)
 376     In the "Classic": the original binary executable
 377     format, these framework functions are directly
 378     transformed to MacOS system call. Therefore, the
 379     exact availability should be checked by running
 380     system.
 381
 382     (**)
 383     InterfaceLib is bundled to MacOS and its version
 384     is usually equal to MacOS. There's no separate
 385     update for InterfaceLib. It is supposed that
 386     there's no InterfaceLib 9.x for m68k platforms.
 387     In fact, these functions are FSRef dependent.
 388
 389     (***)
 390     ATSUI framework is available on ATSUnicode 8.5 on
 391     ppc Toolbox CFM, CarbonLib 1.0 too. But its base:
 392     ATS font manager is not published in these versions.
 393
 394 ------------------------------------------------------------
 395 Last update: 2009-Jul-25.
 396
 397 Currently maintained by
 398         suzuki toshiya, <mpsuzuki@hiroshima-u.ac.jp>
 399 Originally prepared by
 400         Leonard Rosenthol, <leonardr@lazerware.com>
 401         Just van Rossum, <just@letterror.com>
 402
 403 This directory is now actively maintained as part of the FreeType Project.