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://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 skeletons. 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
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 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 +---------+---------+---------+---------+---------+
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