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
204APPENDIX I
205----------
206
207 A-1. Framework dependencies
208 ---------------------------
209
210 src/base/ftmac.c adds two Mac-specific features to
211 FreeType. These features are based on MacOS libraries.
212
213 * accessing resource-fork font
214 The fonts for classic MacOS store their graphical data
215 in resource forks which cannot be accessed via ANSI C
216 functions. FreeType2 provides functions to handle such
217 resource fork fonts, they are based on File Manager
218 framework of MacOS. In addition, HFS and HFS+ file
219 system driver of Linux is supported. Following
220 functions are for this purpose.
221
222 FT_New_Face_From_Resource()
223 FT_New_Face_From_FSSpec()
224 FT_New_Face_From_FSRef()
225
226 * resolving font name to font file
227 The font menu of MacOS application prefers font name
228 written in FOND resource than sfnt resource. FreeType2
229 provides functions to find font file by name in MacOS
230 application, they are based on QuickDraw Font Manager
231 and Apple Type Service framework of MacOS.
232
233 FT_GetFile_From_Mac_Name()
234 FT_GetFile_From_Mac_ATS_Name()
235
236 Working functions for each MacOS are summarized as
237 following.
238
239 upto MacOS 6:
240 not tested (you have to obtain MPW 2.x)
241
242 MacOS 7.x, 8.x, 9.x (without CarbonLib):
243 FT_GetFile_From_Mac_Name()
244 FT_New_Face_From_Resource()
245 FT_New_Face_From_FSSpec()
246
247 MacOS 9.x (with CarbonLib):
248 FT_GetFile_From_Mac_Name()
249 FT_New_Face_From_Resource()
250 FT_New_Face_From_FSSpec()
251 FT_New_Face_From_FSRef()
252
253 Mac OS X upto 10.4.x:
254 FT_GetFile_From_Mac_Name() deprecated
255 FT_New_Face_From_FSSpec() deprecated
256 FT_GetFile_From_Mac_ATS_Name() deprecated?
257 FT_New_Face_From_FSRef()
258
259 A-2. Deprecated Functions
260 -------------------------
261
262 A-2-1. FileManager
263 ------------------
264
265 For convenience to write MacOS application, ftmac.c
266 provides functions to specify a file by FSSpec and FSRef,
267 because the file identification pathname had ever been
268 unrecommended method in MacOS programming.
269
270 Toward to MacOS X 10.4 & 5, Carbon functions using FSSpec
271 datatype is noticed as deprecated, and recommended to
272 migrate to FSRef datatype. The big differences of FSRef
273 against FSSpec are explained in Apple TechNotes 2078.
274
275 https://developer.apple.com/library/archive/technotes/tn2078/
276
277 - filename length: the max length of file
278 name of FSRef is 255 chars (it is limit of HFS+),
279 that of FSSpec is 31 chars (it is limit of HFS).
280
281 - filename encoding: FSSpec is localized by
282 legacy encoding for each language system,
283 FSRef is Unicode enabled.
284
285 A-2-2. FontManager
286 ------------------
287
288 Following functions receive QuickDraw fontname:
289
290 FT_GetFile_From_Mac_Name()
291
292 QuickDraw is deprecated and replaced by Quartz
293 since Mac OS X 10.4. They are still kept for
294 backward compatibility. By undefinition of
295 HAVE_QUICKDRAW in building, you can change these
296 functions to return FT_Err_Unimplemented always.
297
298 Replacement functions are added for migration.
299
300 FT_GetFile_From_Mac_ATS_Name()
301
302 They are usable on Mac OS X only. On older systems,
303 these functions return FT_Err_Unimplemented always.
304
305 The detailed incompatibilities and possibility
306 of FontManager emulation without QuickDraw is
307 explained in
308
309 http://gyvern.ipc.hiroshima-u.ac.jp/~mpsuzuki/ats_benchmark.html
310
311 A-3. Framework Availabilities
312 -----------------------------
313
314 The framework of MacOS are often revised, especially
315 when new format of binary executable is introduced.
316 Following table is the minimum version of frameworks
317 to use functions used in FreeType2. The table is
318 extracted from MPW header files for assembly language.
319
320 *** NOTE ***
321 The conditional definition of available data type
322 in MPW compiler is insufficient. You can compile
323 program using FSRef data type for older systems
324 (MacOS 7, 8) that don't know FSRef data type.
325
326
327 +-------------------+-----------------------------+
328 CPU | mc680x0 | PowerPC |
329 +---------+---------+---------+---------+---------+
330 Binary Executable Format | Classic | 68K-CFM | CFM | CFM | Mach-O |
331 +---------+---------+---------+---------+---------+
332 Framework API | Toolbox | Toolbox | Toolbox | Carbon | Carbon |
333 +---------+---------+---------+---------+---------+
334
335 +---------+---------+---------+---------+---------+
336 | ?(*) |Interface|Interface|CarbonLib|Mac OS X |
337 | |Lib |Lib | | |
338* Files.h +---------+---------+---------+---------+---------+
339PBGetFCBInfoSync() | o | 7.1- | 7.1- | 1.0- | o |
340FSMakeFSSpec() | o | 7.1- | 7.1- | 1.0- | o |
341FSGetForkCBInfo() | o | (**) | 9.0- | 1.0- | o |
342FSpMakeFSRef() | o | (**) | 9.0- | 1.0- | o |
343FSGetCatalogInfo() | o | (**) | 9.0- | 1.0- | -10.3 |
344FSPathMakeRef() | x | x | x | 1.1- | -10.3 |
345 +---------+---------+---------+---------+---------+
346
347 +---------+---------+---------+---------+---------+
348 | ?(*) |Font |Font |CarbonLib|Mac OS X |
349 | |Manager |Manager | | |
350* Fonts.h +---------+---------+---------+---------+---------+
351FMCreateFontFamilyIterator() | x | x | 9.0- | 1.0- | -10.3 |
352FMDisposeFontFamilyIterator() | x | x | 9.0- | 1.0- | -10.3 |
353FMGetNextFontFamily() | x | x | 9.0- | 1.0- | -10.3 |
354FMGetFontFamilyName() | x | x | 9.0- | 1.0- | -10.3 |
355FMCreateFontFamilyInstanceIterator() | x | x | 9.0- | 1.0- | -10.3 |
356FMDisposeFontFamilyInstanceIterator() | x | x | 9.0- | 1.0- | -10.3 |
357FMGetNextFontFamilyInstance() | x | x | 9.0- | 1.0- | -10.3 |
358 +---------+---------+---------+---------+---------+
359
360 +---------+---------+---------+---------+---------+
361 | - | - | - |CarbonLib|Mac OS X |
362* ATSFont.h (***) +---------+---------+---------+---------+---------+
363ATSFontFindFromName() | x | x | x | x | o |
364ATSFontGetFileSpecification() | x | x | x | x | o |
365 +---------+---------+---------+---------+---------+
366
367 (*)
368 In the "Classic": the original binary executable
369 format, these framework functions are directly
370 transformed to MacOS system call. Therefore, the
371 exact availability should be checked by running
372 system.
373
374 (**)
375 InterfaceLib is bundled to MacOS and its version
376 is usually equal to MacOS. There's no separate
377 update for InterfaceLib. It is supposed that
378 there's no InterfaceLib 9.x for m68k platforms.
379 In fact, these functions are FSRef dependent.
380
381 (***)
382 ATSUI framework is available on ATSUnicode 8.5 on
383 ppc Toolbox CFM, CarbonLib 1.0 too. But its base:
384 ATS font manager is not published in these versions.
385
386------------------------------------------------------------
387Last update: 2013-Nov-03.
388
389Currently maintained by
390 suzuki toshiya, <mpsuzuki@hiroshima-u.ac.jp>
391Originally prepared by
392 Leonard Rosenthol, <leonardr@lazerware.com>
393 Just van Rossum, <just@letterror.com>
394