aboutsummaryrefslogtreecommitdiff
path: root/freetype/builds/mac/README
blob: f58e47d4ad28520b8da0a820e8e2349869b9e7c0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
This folder contains

  * Makefile skeletons for Apple MPW (Macintosh's Programmer's Workshop)

  * Python script to generate MPW makefile from skeleton

  * Metrowerks CodeWarrior 9.0 project file in XML format

------------------------------------------------------------

1. What is this
---------------

Files in this directory are designed to build FreeType
running on classic MacOS. To build FreeType running on
Mac OS X, build as the system is UNIX.

However, Mac OS X is most useful to manipulate files in
vanilla FreeType to fit classic MacOS.

The information about MacOS specific API is written in
appendix of this document.

2. Requirement
--------------

You can use MPW: a free-charged developer environment
by Apple, or CodeWarrior: a commercial developer
environment by Metrowerks. GCC for MPW and Symantec
"Think C" are not tested at present.


  2-1. Apple MPW
  --------------

  Following C compilers are tested:

      m68k target:	Apple SC  8.9.0d3e1
      ppc  target:	Apple MrC 5.0.0d3c1

  The final MPW-GM (official release on 1999/Dec) is too
  old and cannot compile FreeType, because bundled C
  compilers cannot search header files in sub directories.
  Updating by the final MPW-PR (pre-release on 2001/Feb)
  is required.

  Required files are downloadable from:

      http://developer.apple.com/tools/mpw-tools/index.html

  Also you can find documents how to update by MPW-PR.

  Python is required to restore MPW makefiles from the
  skeletons. Python bundled to Mac OS X is enough. For
  classic MacOS, MacPython is available:

      http://homepages.cwi.nl/~jack/macpython/

  MPW requires all files are typed by resource fork.
  ResEdit bundled to MPW is enough. In Mac OS X,
  /Developer/Tools/SetFile of DevTool is useful to
  manipulate from commandline.

  2-2. Metrowerks CodeWarrior
  ---------------------------

  XML project file is generated and tested by
  CodeWarrior 9.0.  Older versions are not tested
  at all. At present, static library for ppc target
  is available in the project file.


3. How to build
---------------

  3-1. Apple MPW
  --------------
  Detailed building procedure by Apple MPW is
  described in following.

    3-1-1. Generate MPW makefiles from the skeletons
    ------------------------------------------------

    Here are 4 skeletons for following targets are
    included.

    - FreeType.m68k_far.make.txt
      Ancient 32bit binary executable format for
      m68k MacOS: System 6, with 32bit addressing
      mode (far-pointer-model) So-called "Toolbox"
      API is used.

    - FreeType.m68k_cfm.make.txt
      CFM binary executable format for m68k MacOS:
      System 7. So-called "Toolbox" API is used.

    - FreeType.ppc_classic.make.txt
      CFM binary executable format for ppc MacOS:
      System 7, MacOS 8, MacOS 9. So-called "Toolbox"
      API is used.

    - FreeType.ppc_carbon.make.txt
      CFM binary executable format for ppc MacOS:
      MacOS 9. Carbon API is used.

    At present, static library is only supported,
    although targets except of m68k_far are capable
    to use shared library.

    MPW makefile syntax uses 8bit characters. To keep
    from violating them during version control, here
    we store skeletons in pure ASCII format. You must
    generate MPW makefile by Python script ascii2mpw.py.

    In Mac OS X terminal, you can convert as:

	python builds/mac/ascii2mpw.py \
		< builds/mac/FreeType.m68k_far.make.txt \
		> FreeType.m68k_far.make

    The skeletons are designed to use in the top
    directory where there are builds, include, src etc.
    You must name the generated MPW makefile by removing
    ".txt" from source skeleton name.

    3-1-2. Add resource forks to related files
    ------------------------------------------

    MPW's Make and C compilers cannot recognize files
    without resource fork. You have to add resource
    fork to the files that MPW uses. In Mac OS X
    terminal of the system, you can do as:

	find . -name '*.[ch]' -exec \
		/Developer/Tools/SetFile -a l -c "MPS " -t TEXT \{\} \;

	find . -name '*.make' -exec \
		/Developer/Tools/SetFile -a l -c "MPS " -t TEXT \{\} \;


    3-1-3. Open MPW shell and build
    -------------------------------

    Open MPW shell and go to the top directory that
    FreeType sources are extracted (MPW makefile must
    be located in there), from "Set Directory" in
    "Directory" menu.

    Choose "Build" from "Build" menu, and type the
    name of project by removing ".make" from MPW
    makefile, as: FreeType.m68k_far

    If building is successfully finished, you can find
    built library in objs/ directory.


  3-2. Metrowerks CodeWarrior
  ---------------------------

  Detailed building procedure by Metrowerks
  CodeWarrior (CW) 9.0 is described in following.

    3-2-1. Import XML project file
    ------------------------------

    CW XML project file is not ready for double-
    click. Start CodeWarrior IDE, and choose
    "Import project" in "File" menu. Choose XML
    project file: builds/mac/ftlib.prj.xml.
    In next, you will be asked where to save CW
    native project file: you must choose
    "builds/mac/ftlib.prj". The project file is
    designed with relative path from there. After
    CW native project file is generated, it is
    automatically loaded, small project window
    titled "ftlib.prj" is displayed.

    3-2-2. Building
    ---------------
    Choose "Make" from "Project" menu. If building
    is successfully finished, you can find built
    library at objs/FreeTypeLib.

4. TODO
-------

  4-1. All modules should be included
  -----------------------------------

  At present, MPW makefiles and CW project file are
  just updated versions of these by Leonard. Some
  modules are added after the last maintenance, they
  are not included.

  4-2. Working test with ftdemos
  ------------------------------

  At present, MPW makefiles and CW project file can
  build FreeType for classic MacOS. But their working
  behaviours are not tested at all. Building ftdemos
  for classic MacOS and working test is required.

  4-3. Porting Jam onto MPW
  -------------------------

  FreeType uses Jam (and FT-Jam) for unified cross-
  platform building tool. At present, Jam is not ported
  to MPW. To update classic MacOS support easily,
  building by Jam is expected on MPW.


APPENDIX I
----------

  A-1. Framework dependencies
  ---------------------------

  src/base/ftmac.c adds two Mac-specific features to
  FreeType. These features are based on MacOS libraries.

  * accessing resource-fork font
  The fonts for classic MacOS store their graphical data
  in resource forks which cannot be accessed via ANSI C
  functions. FreeType2 provides functions to handle such
  resource fork fonts, they are based on File Manager
  framework of MacOS. In addition, HFS and HFS+ file
  system driver of Linux is supported. Following
  functions are for this purpose.

    FT_New_Face_From_Resource()
    FT_New_Face_From_FSSpec()
    FT_New_Face_From_FSRef()

  * resolving font name to font file
  The font menu of MacOS application prefers font name
  written in FOND resource than sfnt resource. FreeType2
  provides functions to find font file by name in MacOS
  application, they are based on QuickDraw Font Manager
  and Apple Type Service framework of MacOS.

    FT_GetFile_From_Mac_Name()
    FT_GetFile_From_Mac_ATS_Name()

  Working functions for each MacOS are summarized as
  following.

  upto MacOS 6:
    not tested (you have to obtain MPW 2.x)

  MacOS 7.x, 8.x, 9.x (without CarbonLib):
    FT_GetFile_From_Mac_Name()
    FT_New_Face_From_Resource()
    FT_New_Face_From_FSSpec()

  MacOS 9.x (with CarbonLib):
    FT_GetFile_From_Mac_Name()
    FT_New_Face_From_Resource()
    FT_New_Face_From_FSSpec()
    FT_New_Face_From_FSRef()

  Mac OS X upto 10.4.x:
    FT_GetFile_From_Mac_Name()     deprecated
    FT_New_Face_From_FSSpec()      deprecated
    FT_GetFile_From_Mac_ATS_Name() deprecated?
    FT_New_Face_From_FSRef()

  A-2. Deprecated Functions
  -------------------------

    A-2-1. FileManager
    ------------------

    For convenience to write MacOS application, ftmac.c
    provides functions to specify a file by FSSpec and FSRef,
    because the file identification pathname had ever been
    unrecommended method in MacOS programming.

    Toward to MacOS X 10.4 & 5, Carbon functions using FSSpec
    datatype is noticed as deprecated, and recommended to
    migrate to FSRef datatype. The big differences of FSRef
    against FSSpec are explained in Apple TechNotes 2078.

    http://developer.apple.com/technotes/tn2002/tn2078.html

    - filename length: the max length of file
    name of FSRef is 255 chars (it is limit of HFS+),
    that of FSSpec is 31 chars (it is limit of HFS).

    - filename encoding: FSSpec is localized by
    legacy encoding for each language system,
    FSRef is Unicode enabled.

    A-2-2. FontManager
    ------------------

    Following functions receive QuickDraw fontname:

      FT_GetFile_From_Mac_Name()

    QuickDraw is deprecated and replaced by Quartz
    since Mac OS X 10.4. They are still kept for
    backward compatibility. By undefinition of
    HAVE_QUICKDRAW in building, you can change these
    functions to return FT_Err_Unimplemented always.

    Replacement functions are added for migration.

      FT_GetFile_From_Mac_ATS_Name()

    They are usable on Mac OS X only. On older systems,
    these functions return FT_Err_Unimplemented always.

    The detailed incompatibilities and possibility
    of FontManager emulation without QuickDraw is
    explained in

      http://www.gyve.org/~mpsuzuki/ats_benchmark.html

  A-3. Framework Availabilities
  -----------------------------

  The framework of MacOS are often revised, especially
  when new format of binary executable is introduced.
  Following table is the minimum version of frameworks
  to use functions used in FreeType2. The table is
  extracted from MPW header files for assembly language.

  *** NOTE ***
  The conditional definition of available data type
  in MPW compiler is insufficient. You can compile
  program using FSRef data type for older systems
  (MacOS 7, 8) that don't know FSRef data type.


                                      +-------------------+-----------------------------+
           CPU                        |      mc680x0      |           PowerPC           |
                                      +---------+---------+---------+---------+---------+
  Binary Executable Format            | Classic | 68K-CFM | CFM     | CFM     | Mach-O  |
                                      +---------+---------+---------+---------+---------+
       Framework API                  | Toolbox | Toolbox | Toolbox | Carbon  | Carbon  |
                                      +---------+---------+---------+---------+---------+

                                      +---------+---------+---------+---------+---------+
                                      |    ?(*) |Interface|Interface|CarbonLib|Mac OS X |
                                      |         |Lib      |Lib      |         |         |
* Files.h                             +---------+---------+---------+---------+---------+
PBGetFCBInfoSync()                    |    o    | 7.1-    | 7.1-    | 1.0-    |    o    |
FSMakeFSSpec()                        |    o    | 7.1-    | 7.1-    | 1.0-    |    o    |
FSGetForkCBInfo()                     |    o    |   (**)  | 9.0-    | 1.0-    |    o    |
FSpMakeFSRef()                        |    o    |   (**)  | 9.0-    | 1.0-    |    o    |
FSGetCatalogInfo()                    |    o    |   (**)  | 9.0-    | 1.0-    |   -10.3 |
FSPathMakeRef()                       |    x    |    x    |    x    | 1.1-    |   -10.3 |
                                      +---------+---------+---------+---------+---------+

                                      +---------+---------+---------+---------+---------+
                                      |    ?(*) |Font     |Font     |CarbonLib|Mac OS X |
                                      |         |Manager  |Manager  |         |         |
* Fonts.h                             +---------+---------+---------+---------+---------+
FMCreateFontFamilyIterator()          |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |
FMDisposeFontFamilyIterator()         |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |
FMGetNextFontFamily()                 |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |
FMGetFontFamilyName()                 |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |
FMCreateFontFamilyInstanceIterator()  |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |
FMDisposeFontFamilyInstanceIterator() |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |
FMGetNextFontFamilyInstance()         |    x    |    x    | 9.0-    | 1.0-    |   -10.3 |
                                      +---------+---------+---------+---------+---------+

                                      +---------+---------+---------+---------+---------+
                                      |    -    |    -    |    -    |CarbonLib|Mac OS X |
* ATSFont.h (***)                     +---------+---------+---------+---------+---------+
ATSFontFindFromName()                 |    x    |    x    |    x    |    x    |    o    |
ATSFontGetFileSpecification()         |    x    |    x    |    x    |    x    |    o    |
                                      +---------+---------+---------+---------+---------+

    (*)
    In the "Classic": the original binary executable
    format, these framework functions are directly
    transformed to MacOS system call. Therefore, the
    exact availability should be checked by running
    system.

    (**)
    InterfaceLib is bundled to MacOS and its version
    is usually equal to MacOS. There's no separate
    update for InterfaceLib. It is supposed that
    there's no InterfaceLib 9.x for m68k platforms.
    In fact, these functions are FSRef dependent.

    (***)
    ATSUI framework is available on ATSUnicode 8.5 on
    ppc Toolbox CFM, CarbonLib 1.0 too. But its base:
    ATS font manager is not published in these versions.

------------------------------------------------------------
Last update: 2013-Nov-03.

Currently maintained by
	suzuki toshiya, <mpsuzuki@hiroshima-u.ac.jp>
Originally prepared by
	Leonard Rosenthol, <leonardr@lazerware.com>
	Just van Rossum, <just@letterror.com>