This folder contains



  * Makefile skeltons for Apple MPW (Macintosh's Programmers Workshop)



  * Python script to generate MPW makefile from skelton



  * Metrowerks CodeWarrior 9.0 project file in XML format



------------------------------------------------------------



1. What is this

---------------



Files in this directory are designed to build FreeType

running on classic MacOS. To build FreeType running on

Mac OS X, build as the system is UNIX.



However, Mac OS X is most useful to manipulate files in

vanilla FreeType to fit classic MacOS.



The information about MacOS specific API is written in

appendix of this document.



2. Requirement

--------------



You can use MPW: a free-charged developer environment

by Apple, or CodeWarrior: a commercial developer

environment by Metrowerks. GCC for MPW and Symantec

"Think C" are not tested at present.





  2-1. Apple MPW

  --------------



  Following C compilers are tested:



      m68k target:	Apple SC  8.9.0d3e1

      ppc  target:	Apple MrC 5.0.0d3c1



  The final MPW-GM (official release on 1999/Dec) is too

  old and cannot compile FreeType, because bundled C

  compilers cannot search header files in sub directories.

  Updating by the final MPW-PR (pre-release on 2001/Feb)

  is required.



  Required files are downloadable from:



      http://developer.apple.com/tools/mpw-tools/index.html



  Also you can find documents how to update by MPW-PR.



  Python is required to restore MPW makefiles from the

  skeltons. Python bundled to Mac OS X is enough. For

  classic MacOS, MacPython is available:



      http://homepages.cwi.nl/~jack/macpython/



  MPW requires all files are typed by resource fork.

  ResEdit bundled to MPW is enough. In Mac OS X,

  /Developer/Tools/SetFile of DevTool is useful to

  manipulate from commandline.



  2-2. Metrowerks CodeWarrior

  ---------------------------



  XML project file is generated and tested by

  CodeWarrior 9.0.  Older versions are not tested

  at all. At present, static library for ppc target

  is available in the project file.





3. How to build

---------------



  3-1. Apple MPW

  --------------

  Detailed building procedure by Apple MPW is

  described in following.



    3-1-1. Generate MPW makefiles from the skeltons

    ------------------------------------------------



    Here are 4 skeltons for following targets are

    included.



    - FreeType.m68k_far.make.txt

      Ancient 32bit binary executable format for

      m68k MacOS: System 6, with 32bit addressing

      mode (far-pointer-model) So-called "Toolbox"

      API is used.



    - FreeType.m68k_cfm.make.txt

      CFM binary executable format for m68k MacOS:

      System 7. So-called "Toolbox" API is used.



    - FreeType.ppc_classic.make.txt

      CFM binary executable format for ppc MacOS:

      System 7, MacOS 8, MacOS 9. So-called "Toolbox"

      API is used.



    - FreeType.ppc_carbon.make.txt

      CFM binary executable format for ppc MacOS:

      MacOS 9. Carbon API is used.



    At present, static library is only supported,

    although targets except of m68k_far are capable

    to use shared library.



    MPW makefile syntax uses 8bit characters. To keep

    from violating them during version control, here

    we store skeltons in pure ASCII format. You must

    generate MPW makefile by Python script ascii2mpw.py.



    In Mac OS X terminal, you can convert as:



	python builds/mac/ascii2mpw.py \

		< builds/mac/FreeType.m68k_far.make.txt \

		> FreeType.m68k_far.make



    The skeltons are designed to use in the top

    directory where there are builds, include, src etc.

    You must name the generated MPW makefile by removing

    ".txt" from source skelton name.



    3-1-2. Add resource forks to related files

    ------------------------------------------



    MPW's Make and C compilers cannot recognize files

    without resource fork. You have to add resource

    fork to the files that MPW uses. In Mac OS X

    terminal of the system, you can do as:



	find . -name '*.[ch]' -exec \

		/Developer/Tools/SetFile -a l -c "MPS " -t TEXT \{\} \;



	find . -name '*.make' -exec \

		/Developer/Tools/SetFile -a l -c "MPS " -t TEXT \{\} \;





    3-1-3. Open MPW shell and build

    -------------------------------



    Open MPW shell and go to the top directory that

    FreeType sources are extracted (MPW makefile must

    be located in there), from "Set Directory" in

    "Directory" menu.



    Choose "Build" from "Build" menu, and type the

    name of project by removing ".make" from MPW

    makefile, as: FreeType.m68k_far



    If building is successfully finished, you can find

    built library in objs/ directory.





  3-2. Metrowerks CodeWarrior

  ---------------------------



  Detailed building procedure by Metrowerks

  CodeWarrior (CW) 9.0 is described in following.



    3-2-1. Import XML project file

    ------------------------------



    CW XML project file is not ready for double-

    click. Start CodeWarrior IDE, and choose

    "Import project" in "File" menu. Choose XML

    project file: builds/mac/ftlib.prj.xml.

    In next, you will be asked where to save CW

    native project file: you must choose

    "builds/mac/ftlib.prj". The project file is

    designed with relative path from there. After

    CW native project file is generated, it is

    automatically loaded, small project window

    titled "ftlib.prj" is displayed.



    3-2-2. Building

    ---------------

    Choose "Make" from "Project" menu. If building

    is successfully finished, you can find built

    library at objs/FreeTypeLib.



4. TODO

-------



  4-1. All modules should be included

  -----------------------------------



  At present, MPW makefiles and CW project file are

  just updated versions of these by Leonard. Some

  modules are added after the last maintenance, they

  are not included.



  4-2. Working test with ftdemos

  ------------------------------



  At present, MPW makefiles and CW project file can

  build FreeType for classic MacOS. But their working

  behaviours are not tested at all. Building ftdemos

  for classic MacOS and working test is required.



  4-3. Porting Jam onto MPW

  -------------------------



  FreeType uses Jam (and FT-Jam) for unified cross-

  platform building tool. At present, Jam is not ported

  to MPW. To update classic MacOS support easily,

  building by Jam is expected on MPW.





APPENDIX I

----------



  A-1. Framework dependencies

  ---------------------------



  src/base/ftmac.c adds two Mac-specific features to

  FreeType. These features are based on MacOS libraries.



  * accessing resource-fork font

  The fonts for classic MacOS store their graphical data

  in resource forks which cannot be accessed via ANSI C

  functions. FreeType2 provides functions to handle such

  resource fork fonts, they are based on File Manager

  framework of MacOS. In addition, HFS and HFS+ file

  system driver of Linux is supported. Following

  functions are for this purpose.



    FT_New_Face_From_Resource()

    FT_New_Face_From_FSSpec()

    FT_New_Face_From_FSRef()



  * resolving font name to font file

  The font menu of MacOS application prefers font name

  written in FOND resource than sfnt resource. FreeType2

  provides functions to find font file by name in MacOS

  application, they are based on QuickDraw Font Manager

  and Apple Type Service framework of MacOS.



    FT_GetFile_From_Mac_Name()

    FT_GetFile_From_Mac_ATS_Name()



  Working functions for each MacOS are summarized as

  following.



  upto MacOS 6:

    not tested (you have to obtain MPW 2.x)



  MacOS 7.x, 8.x, 9.x (without CarbonLib):

    FT_GetFile_From_Mac_Name()

    FT_New_Face_From_Resource()

    FT_New_Face_From_FSSpec()



  MacOS 9.x (with CarbonLib):

    FT_GetFile_From_Mac_Name()

    FT_New_Face_From_Resource()

    FT_New_Face_From_FSSpec()

    FT_New_Face_From_FSRef()



  Mac OS X upto 10.4.x:

    FT_GetFile_From_Mac_Name()     deprecated

    FT_New_Face_From_FSSpec()      deprecated

    FT_GetFile_From_Mac_ATS_Name() deprecated?

    FT_New_Face_From_FSRef()



  A-2. Deprecated Functions

  -------------------------



    A-2-1. FileManager

    ------------------



    For convenience to write MacOS application, ftmac.c

    provides functions to specify a file by FSSpec and FSRef,

    because the file identification pathname had ever been

    unrecommended method in MacOS programming.



    Toward to MacOS X 10.4 & 5, Carbon functions using FSSpec

    datatype is noticed as deprecated, and recommended to

    migrate to FSRef datatype. The big differences of FSRef

    against FSSpec are explained in Apple TechNotes 2078.



    http://developer.apple.com/technotes/tn2002/tn2078.html



    - filename length: the max length of file

    name of FSRef is 255 chars (it is limit of HFS+),

    that of FSSpec is 31 chars (it is limit of HFS).



    - filename encoding: FSSpec is localized by

    legacy encoding for each language system,

    FSRef is Unicode enabled.



    A-2-2. FontManager

    ------------------



    Following functions receive QuickDraw fontname:



      FT_GetFile_From_Mac_Name()



    QuickDraw is deprecated and replaced by Quartz

    since Mac OS X 10.4. They are still kept for

    backward compatibility. By undefinition of

    HAVE_QUICKDRAW in building, you can change these

    functions to return FT_Err_Unimplemented always.



    Replacement functions are added for migration.



      FT_GetFile_From_Mac_ATS_Name()



    They are usable on Mac OS X only. On older systems,

    these functions return FT_Err_Unimplemented always.



    The detailed incompatibilities and possibility

    of FontManager emulation without QuickDraw is

    explained in



      http://www.gyve.org/~mpsuzuki/ats_benchmark.html



  A-3. Framework Availabilities

  -----------------------------



  The framework of MacOS are often revised, especially

  when new format of binary executable is introduced.

  Following table is the minimum version of frameworks

  to use functions used in FreeType2. The table is

  extracted from MPW header files for assembly language.



  *** NOTE ***

  The conditional definition of available data type

  in MPW compiler is insufficient. You can compile

  program using FSRef data type for older systems

  (MacOS 7, 8) that don't know FSRef data type.





                                      +-------------------+-----------------------------+

           CPU                        |      mc680x0      |           PowerPC           |

                                      +---------+---------+---------+---------+---------+

  Binary Executable Format            | Classic | 68K-CFM | CFM     | CFM     | Mach-O  |

                                      +---------+---------+---------+---------+---------+

       Framework API                  | Toolbox | Toolbox | Toolbox | Carbon  | Carbon  |

                                      +---------+---------+---------+---------+---------+



                                      +---------+---------+---------+---------+---------+

                                      |    ?(*) |Interface|Interface|CarbonLib|Mac OS X |

                                      |         |Lib      |Lib      |         |         |

* Files.h                             +---------+---------+---------+---------+---------+

PBGetFCBInfoSync()                    |    o    | 7.1-    | 7.1-    | 1.0-    |    o    |

FSMakeFSSpec()                        |    o    | 7.1-    | 7.1-    | 1.0-    |    o    |

FSGetForkCBInfo()                     |    o    |   (**)  | 9.0-    | 1.0-    |    o    |

FSpMakeFSRef()                        |    o    |   (**)  | 9.0-    | 1.0-    |    o    |

FSGetCatalogInfo()                    |    o    |   (**)  | 9.0-    | 1.0-    |   -10.3 |

FSPathMakeRef()                       |    x    |    x    |    x    | 1.1-    |   -10.3 |

                                      +---------+---------+---------+---------+---------+



                                      +---------+---------+---------+---------+---------+

                                      |    ?(*) |Font     |Font     |CarbonLib|Mac OS X |

                                      |         |Manager  |Manager  |         |         |

* Fonts.h                             +---------+---------+---------+---------+---------+

FMCreateFontFamilyIterator()          |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |

FMDisposeFontFamilyIterator()         |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |

FMGetNextFontFamily()                 |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |

FMGetFontFamilyName()                 |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |

FMCreateFontFamilyInstanceIterator()  |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |

FMDisposeFontFamilyInstanceIterator() |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |

FMGetNextFontFamilyInstance()         |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |

                                      +---------+---------+---------+---------+---------+



                                      +---------+---------+---------+---------+---------+

                                      |    -    |    -    |    -    |CarbonLib|Mac OS X |

* ATSFont.h (***)                     +---------+---------+---------+---------+---------+

ATSFontFindFromName()                 |    x    |    x    |    x    |    x    |    o    |

ATSFontGetFileSpecification()         |    x    |    x    |    x    |    x    |    o    |

                                      +---------+---------+---------+---------+---------+



    (*)

    In the "Classic": the original binary executable

    format, these framework functions are directly

    transformed to MacOS system call. Therefore, the

    exact availability should be checked by running

    system.



    (**)

    InterfaceLib is bundled to MacOS and its version

    is usually equal to MacOS. There's no separate

    update for InterfaceLib. It is supposed that

    there's no InterfaceLib 9.x for m68k platforms.

    In fact, these functions are FSRef dependent.



    (***)

    ATSUI framework is available on ATSUnicode 8.5 on

    ppc Toolbox CFM, CarbonLib 1.0 too. But its base:

    ATS font manager is not published in these versions.



------------------------------------------------------------

Last update: 2009-Jul-25.



Currently maintained by

	suzuki toshiya, <mpsuzuki@hiroshima-u.ac.jp>

Originally prepared by

	Leonard Rosenthol, <leonardr@lazerware.com>

	Just van Rossum, <just@letterror.com>



This directory is now actively maintained as part of the FreeType Project.

