README (14200B)
1 This 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 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://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 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 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 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 204 APPENDIX 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 +---------+---------+---------+---------+---------+ 339 PBGetFCBInfoSync() | o | 7.1- | 7.1- | 1.0- | o | 340 FSMakeFSSpec() | o | 7.1- | 7.1- | 1.0- | o | 341 FSGetForkCBInfo() | o | (**) | 9.0- | 1.0- | o | 342 FSpMakeFSRef() | o | (**) | 9.0- | 1.0- | o | 343 FSGetCatalogInfo() | o | (**) | 9.0- | 1.0- | -10.3 | 344 FSPathMakeRef() | x | x | x | 1.1- | -10.3 | 345 +---------+---------+---------+---------+---------+ 346 347 +---------+---------+---------+---------+---------+ 348 | ?(*) |Font |Font |CarbonLib|Mac OS X | 349 | |Manager |Manager | | | 350 * Fonts.h +---------+---------+---------+---------+---------+ 351 FMCreateFontFamilyIterator() | x | x | 9.0- | 1.0- | -10.3 | 352 FMDisposeFontFamilyIterator() | x | x | 9.0- | 1.0- | -10.3 | 353 FMGetNextFontFamily() | x | x | 9.0- | 1.0- | -10.3 | 354 FMGetFontFamilyName() | x | x | 9.0- | 1.0- | -10.3 | 355 FMCreateFontFamilyInstanceIterator() | x | x | 9.0- | 1.0- | -10.3 | 356 FMDisposeFontFamilyInstanceIterator() | x | x | 9.0- | 1.0- | -10.3 | 357 FMGetNextFontFamilyInstance() | x | x | 9.0- | 1.0- | -10.3 | 358 +---------+---------+---------+---------+---------+ 359 360 +---------+---------+---------+---------+---------+ 361 | - | - | - |CarbonLib|Mac OS X | 362 * ATSFont.h (***) +---------+---------+---------+---------+---------+ 363 ATSFontFindFromName() | x | x | x | x | o | 364 ATSFontGetFileSpecification() | 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 ------------------------------------------------------------ 387 Last update: 2013-Nov-03. 388 389 Currently maintained by 390 suzuki toshiya, <mpsuzuki@hiroshima-u.ac.jp> 391 Originally prepared by 392 Leonard Rosenthol, <leonardr@lazerware.com> 393 Just van Rossum, <just@letterror.com>