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