1This folder contains
2
3  * Makefile skeletons for Apple MPW (Macintosh's Programmer's Workshop)
4
5  * Python script to generate MPW makefile from skeleton
6
7  * Metrowerks CodeWarrior 9.0 project file in XML format
8
9------------------------------------------------------------
10
111. What is this
12---------------
13
14Files in this directory are designed to build FreeType
15running on classic MacOS. To build FreeType running on
16Mac OS X, build as the system is UNIX.
17
18However, Mac OS X is most useful to manipulate files in
19vanilla FreeType to fit classic MacOS.
20
21The information about MacOS specific API is written in
22appendix of this document.
23
242. Requirement
25--------------
26
27You can use MPW: a free-charged developer environment
28by Apple, or CodeWarrior: a commercial developer
29environment 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://macintoshgarden.org/apps/macintosh-programmers-workshop
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  skeletons. Python bundled to Mac OS X is enough. For
55  classic MacOS, MacPython is available:
56
57      https://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
733. 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 skeletons
82    ------------------------------------------------
83
84    Here are 4 skeletons 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 skeletons 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 skeletons 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 skeleton 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
1844. 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
212APPENDIX 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    https://developer.apple.com/library/archive/technotes/tn2078/
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://gyvern.ipc.hiroshima-u.ac.jp/~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                             +---------+---------+---------+---------+---------+
347PBGetFCBInfoSync()                    |    o    | 7.1-    | 7.1-    | 1.0-    |    o    |
348FSMakeFSSpec()                        |    o    | 7.1-    | 7.1-    | 1.0-    |    o    |
349FSGetForkCBInfo()                     |    o    |   (**)  | 9.0-    | 1.0-    |    o    |
350FSpMakeFSRef()                        |    o    |   (**)  | 9.0-    | 1.0-    |    o    |
351FSGetCatalogInfo()                    |    o    |   (**)  | 9.0-    | 1.0-    |   -10.3 |
352FSPathMakeRef()                       |    x    |    x    |    x    | 1.1-    |   -10.3 |
353                                      +---------+---------+---------+---------+---------+
354
355                                      +---------+---------+---------+---------+---------+
356                                      |    ?(*) |Font     |Font     |CarbonLib|Mac OS X |
357                                      |         |Manager  |Manager  |         |         |
358* Fonts.h                             +---------+---------+---------+---------+---------+
359FMCreateFontFamilyIterator()          |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |
360FMDisposeFontFamilyIterator()         |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |
361FMGetNextFontFamily()                 |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |
362FMGetFontFamilyName()                 |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |
363FMCreateFontFamilyInstanceIterator()  |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |
364FMDisposeFontFamilyInstanceIterator() |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |
365FMGetNextFontFamilyInstance()         |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |
366                                      +---------+---------+---------+---------+---------+
367
368                                      +---------+---------+---------+---------+---------+
369                                      |    -    |    -    |    -    |CarbonLib|Mac OS X |
370* ATSFont.h (***)                     +---------+---------+---------+---------+---------+
371ATSFontFindFromName()                 |    x    |    x    |    x    |    x    |    o    |
372ATSFontGetFileSpecification()         |    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------------------------------------------------------------
395Last update: 2013-Nov-03.
396
397Currently maintained by
398	suzuki toshiya, <mpsuzuki@hiroshima-u.ac.jp>
399Originally prepared by
400	Leonard Rosenthol, <leonardr@lazerware.com>
401	Just van Rossum, <just@letterror.com>
402