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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><head><title>
Allegro MacOS X-specific information
</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="stylesheet" title="Default" type="text/css" href="../allegro.css"></head><body bgcolor=white text=black link="#0000ee" alink="#ff0000" vlink="#551a8b">
<pre>
______ ___ ___
/\ _ \ /\_ \ /\_ \
\ \ \L\ \\//\ \ \//\ \ __ __ _ __ ___
\ \ __ \ \ \ \ \ \ \ /'__`\ /'_ <tt>`\/\`'</tt>__\/ __`\
\ \ \/\ \ \_\ \_ \_\ \_/\ __//\ \L\ \ \ \//\ \L\ \
\ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
\/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
/\____/
\_/__/
MacOS X-specific information.
See <a href="../readme.html">readme.txt</a> for a more general overview.
</pre>
<p><br>
<h1><a name="MacOS X notes">MacOS X notes</a></h1>
<p>
This is a full featured native MacOS X port.
<p><br>
<h1><a name="Required software">Required software</a></h1>
<p>
To build Allegro under MacOS X, you need:
<p>
<ul><li>MacOS X 10.2.x or newer
<li>Apple Developer Tools (December 2002 or newer edition)</ul>
<p>
If you don't have the Developer Tools installed, you can get the
latest release at:
<blockquote>
<p>
<a href="http://developer.apple.com/tools/download">http://developer.apple.com/tools/download</a>
</blockquote>
<p>
On the same page you will also find instructions on how to install them.
Note that system version 10.2.x is required to compile Allegro, but
the library will still work on 10.1.x. (At least that was true once; we
haven't gone back and checked it!)
<p><br>
<h1><a name="Installing Allegro">Installing Allegro</a></h1>
<p>
Allegro ships in source code form; this means you need to compile it
before you can use it. You do this easily from a terminal window.
See the generic documentation in docs/build/cmake.txt.
<p>
You may build either Unix-style shared library, or Mac OS X frameworks,
or both.
<p>
XXX information about universal binaries
<p><br>
<h1><a name="Using Allegro from the command line">Using Allegro from the command line</a></h1>
<p>
The options for linking with Allegro are quite long, expecially for
static versions of the library as you need to pull in several different
frameworks (Cocoa, QuickTime, etc.) other than Allegro itself. When
linking against the shared library version, things are also different.
To avoid you having to work out the right linker commands for yourself,
the installation creates a script, <tt>allegro-config</tt>, that will print out a
suitable commandline. You can use this inside a backtick command
substitution, for example:
<blockquote class="text"><pre>
gcc myfile.c -o myprogram `allegro-config --libs`
</pre></blockquote>
Or if you want to build a debug version of your program, assuming that
you have installed the debug version of Allegro:
<blockquote class="text"><pre>
gcc myfile.c -o myprogram `allegro-config --libs debug`
</pre></blockquote>
You can also link against the Allegro framework, providing you previously
installed it:
<blockquote class="text"><pre>
gcc myfile.c -o myprogram `allegro-config --frameworks`
</pre></blockquote>
Unix newbies, take note that these are ` backticks, not normal ' quotes!
<p>
There are also switches for printing out the Allegro version number,
overriding the install paths, and selecting between shared and static
libraries, in case you installed both. Run <tt>allegro-config</tt> without any
arguments for a full list of options.
<p>
If you get an error like '<tt>allegro-config: program not found</tt>', and
you're sure you have built and installed the library as described above, it
probably means that <tt>/usr/local/bin</tt> is not on your path. The method
to add it depends on the shell you're using. If you have tcsh, add the
following line to the end of the <tt>.cshrc</tt> in your home directory.
<blockquote class="text"><pre>
set path=($path /usr/local/bin)
</pre></blockquote>
If you have bash, add the following line to the end of the <tt>.bash_profile</tt>
file in your home directory:
<blockquote class="text"><pre>
PATH=${PATH}:/usr/local/bin
</pre></blockquote>
If you don't know which, just type <tt>echo $SHELL</tt> on the command
line, which will print either <tt>/bin/bash</tt> or <tt>/bin/tcsh</tt>.
Newer versions of OSX use bash, older ones use tcsh.
You will have to close the Terminal window and open a new one once
you have made the changes, so it will have an effect.
<p><br>
<h1><a name="Allegro and application bundles">Allegro and application bundles</a></h1>
<p>
When you build applications from the command line, you're actually just
creating the executable, so you can run it from the command line only,
and not also from the finder like a common MacOS X application. In other
words, compiling from the command line does not create application
bundles.
<p>
Allegro ships with a little tool, named fixbundle, which allows to build
an application bundle out of an executable.
The utility works from the command line and it accepts a variety of
options to customize your bundle; the easiest way to use it is:
<blockquote class="text"><pre>
fixbundle executable_name
</pre></blockquote>
This will create an application bundle named "<tt>executable_name.app</tt>" that
contains your program executable and will appear in the finder with the
default application icon. A more complex usage example follows:
<blockquote class="text"><pre>
fixbundle executable_name -m -o bundle_name -v "1.2" icon.bmp
</pre></blockquote>
This creates a bundle named "<tt>bundle_name.app</tt>". The executable will be
moved instead of copied into the bundle; the application will be marked
as version "1.2" and icon.bmp will be converted to an icon for the
bundle. You can specify more options and up to 4 differently sized
icons (16x16, 32x32, 48x48 and 128x128) to be read from any Allegro
supported image files or from datafile objects.
Run fixbundle without arguments for the full list of known options.
<p>
A special note is required for the "<tt>-e</tt>" switch; this lets you embed
the Allegro framework inside the built application bundle, so your
app will not require Allegro to be installed into the target machine
in order to work. This flag assumes you previously installed the
embeddable version of the Allegro framework, and that your executable
has been linked to it, either via Project Builder or XCode, either
via the allegro-config script.
If one of these conditions is not met, the created app may not
work on target machines.
<p>
Bundles created by fixbundle have this default layout:
<blockquote class="text"><pre>
bundle.app --- Contents --+--- MacOS --- executable
|
+--- Resources --+--- (bundle.icns)
| |
| +--- (executable/...)
|
|
+--- (Frameworks) --- (Allegro.framework/...)
|
+--- Info.plist
|
+--- PkgInfo
</pre></blockquote>
If you are using Project Builder to compile your programs, there is no
need to use fixbundle, as the IDE will do the work of generating an
application bundle for you.
<p>
When an Allegro program starts, it automatically detects if the
executable lives inside a bundle or not. The working directory is
always set up to be the directory where the standalone executable
or application bundle is located, but there is an exception: if the
application is a bundle and Allegro finds a directory under the bundle
Contents/Resources path with the same name of the executable (note that
here we mean the real executable name, not the bundle name), that
directory is set to be the working one. This allows to easily package
all the application data inside the bundle, and still have a working
program without the need to tell your code about the changed location
of your files.
<p><br>
<h1><a name="Notes on drivers">Notes on drivers</a></h1>
<p>
This section contains MacOS X-specific notes on the drivers available.
<blockquote><dl>
<p>
<dt><b>System:</b></dt><dd>
When the system driver is about to be initialized, we already
have a working NSApplication object connected to the Window Server.
At driver startup, the working directory is changed if inside a
bundle with a proper data directory under the Contents/Resources
path (see above).
<p>
Display switching is possible, but only the </tt>SWITCH_BACKGROUND</tt>
mode is supported, so your application will have to deal with it.</dd>
<p>
<dt><b>Graphics:</b></dt><dd>
The MacOS X windowed graphics mode uses a Cocoa window with a
Quartz QuickDraw view as its content view. All combinations of
window/desktop color depths are supported; if needed, color
conversion will automatically be done transparently to the user.
<p>
Fullscreen mode uses the CoreGraphics DirectDisplay API; only
8, 15 and 32 bit color depths are supported.</dd>
<p>
<dt><b>Sound:</b></dt><dd>
The CoreAudio digital/MIDI drivers use V2 AudioUnits, and thus
they require MacOS X 10.2.x (Jaguar) or newer to work. If this is
not the case, you can fall back to the Carbon Sound Manager and
Quicktime MIDI drivers.</dd>
<p>
<dt><b>Keyboard:</b></dt><dd>
MacOS X Allegro uses the current system keyboard mapping table
to map scancodes to characters: the keyboard user settings in
allegro.cfg have no effect.</dd>
<p>
<dt><b>Mouse:</b></dt><dd>
On MacOS X 10.2.x (Jaguar) or newer, Allegro will automatically
detect the number of buttons of your mouse at driver initialization.
If the 1-button Apple mouse is found, the library will activate an
emulation mode that mimics the way MacOS X itself deals with
1-button mice: depending on which key is pressed when the button is
clicked, Allegro will report a different mouse button click.
(Control + button) emulates a right click and (Option + button)
emulates a middle click.
<p>
On MacOS X 10.1.x, mouse autodetection is not possible, and Allegro
will assume an 1-button mouse to always be present, activating
buttons emulation accordingly.</dd>
</dl></blockquote>
<p><br>
<h1><a name="Notes on Threading and Cocoa GUIs">Notes on Threading and Cocoa GUIs</a></h1>
<p>
It is possible to include a Cocoa GUI in an Allegro application. If you
do this you should be aware that Allegro will run your application's
<code>main()</code> function in a different thread from the thread that
the main OS X event loop runs in. See
<a href="http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Multithreading/Introduction/Introduction.html">http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Multithreading/Introduction/Introduction.html</a>
for more information about threading on Mac OS X.
<p><br>
<h1><a name="Final notes">Final notes</a></h1>
<p>
There is a known compatibility problem when using gcc 4 on MacOS X 10.4
that prevents binaries from working on older versions of MacOS X. While it
is anticipated that a future update from Apple will fix this problem, you
can use gcc 3 to work around it.
<p>
As a final note, when coding Allegro programs don't forget that you
need to use the <code>END_OF_MAIN()</code> macro right after your <code>main()</code> function!
</body>
</html>
|
