1Date : 15-Jan-2004
2Last update: 20071229
3Authors: Adam Fedor <fedor@gnu.org>
4         Quentin Math� <qmathe@club-internet.fr>
5         Lars S.-Helldorf <lars.sonchocky-helldorf@hamburg.de>
6
7PURPOSE
8-------
9
10This document is intended to provide a step by step instruction on how to get
11the GNUstep installed on Mac OS X and Darwin.
12
13COMMONLY USED SYMBOLS
14---------------------
15
16<> denotes a variable depending on your preferences. To be replaced with the
17actual values from your system. For instance, if you installed GCC in /opt/local
18
19     ./configure CC=<gcc install dir>/bin/gcc
20
21will become:
22
23     ./configure CC=/opt/local/bin/gcc
24
25[] denotes an optional parameter. For instance:
26
27     ./configure [--enable-graphics=art]
28
29can be either:
30
31     ./configure
32
33or:
34
35     ./configure --enable-graphics=art
36
37PRELIMINAIRES
38-------------
39
40For all targets, get the following software. I'd recommend installing
41Fink (and FinkCommander on Mac OS X) or MacPorts to get all this
42software. Make sure that Fink or MacPorts is in your path; newer
43versions do a good job of doing this for you. It's quite possible for
44libraries installed via Fink/Macports to conflict with Apple
45libraries, which cause strange errors running GNUstep apps (like odd
46crashes and seg faults).  In that cause you might want to hand-compile
47the libraries you need (only the tiff and libffi libraries are REALLY needed,
48everything else is basically optional).
49
50Remember you usually need root access to install software. That means when you
51see an instruction like 'make install', you usually need to use sudo
52('sudo make install') or be logged in as root (not recommended).
53
54     libxml2  (Optional, highly recommended, already in
55               Mac OS X 10.3 / Darwin 7 and later)
56     libxslt  (Optional)
57     libtiff  (Required)
58     libjpeg  (Optional, highly recommended - don't get from fink!)
59     libpng   (Optional, highly recommended)
60
61     libffi   (Required, from ftp.gnustep.org/pub/gnustep/libs)
62     ffcall   (On Darwin x86 - use instead of libffi)
63
64     Xfree86  (Required, already in Mac OS X 10.3/Darwin 7 and later)
65
66     libart2   (Required for art backend)
67     freetype2 (Required for art backend)
68
69     dlcompat (Required, already in Mac OS X 10.3 or later)
70
71Obtaining GNUstep
72-----------------
73
74The main GNUstep project pages tell you how to get hold of this. You
75can get the latest release of the following libraries.  You need these
76gnustep packages:
77
78     GNUstep-make
79     GNUstep-base
80     GNUstep-gui
81     GNUstep-back
82
83Targets
84-------
85
86For GNUstep, there are several combinations of Objective-C runtime, Foundation
87library and Application Kit library possible, called library combos. The usual
88notation is:
89
90     objcruntime-foundation-applicationkit
91
92Theoretically possible are:
93
94     gnu-gnu-gnu       # gnu-objc runtime with gnustep-base and gnustep-gui.
95                       # Most widely tested.
96     apple-gnu-gnu     # apple-objc runtime with gnustep libraries. Does
97                       # not work.
98     apple-apple-gnu   # Apple Foundation with gnustep-gui on the top. Only of
99                       # academic interest.
100     apple-apple-apple # Cocoa with GNUstep additions. For porting GNUstep apps
101                       # to Cocoa.
102
103All gnu-*-apple library combos are purely theoretical and only available to the
104folks inside Apple since no mortal person ever saw the Cocoa source code. ;-)
105You can use either the Apple compiler or compile your own FSF compiler. This
106potentially gives two different targets:
107
108     Apple GCC, gnu-gnu-gnu
109     FSF   GCC, gnu-gnu-gnu
110
111In addition, if you are on Mac OS X, you can also use the Apple
112Foundation and AppKit frameworks to do GNUstep development with Cocoa,
113but this only works with the Apple compiler:
114
115     Apple GCC, apple-apple-apple
116
117GNUstep on Darwin x86
118---------------------
119
120For GNUstep on Darwin x86, Apple GCC compiles GNUstep-base, but causes strange
121problems when running programs (e.g. the program hangs while allocating memory
122or executes methods multiple times). So we have to use FSF GCC.  Additionally,
123libffi has not been ported to Darwin x86, so you will need to install ffcall
124instead. NOTE: Has not been tested in a long time...
125
126GNUstep on Darwin PowerPC
127-------------------------
128
129You can use either the Apple compiler of the FSF compiler. For the Apple
130compiler, you need at least Mac OS X 10.4 with XCode 2.5 release.
131
132Building FSF-GCC
133----------------
134
135The easiest way to get FSF GCC is through Fink or MacPorts. If you
136would like to compile by hand, follow these directions:
137
138Darwin x86:
139
140FSF GCC is difficult to compile here. The only way I could do it was like this:
141
142     ln -s /usr/bin/c++filt /usr/bin/c++filt3          # Missing on Darwin 7.0.1
143                                                       # x86 but not necessary
144                                                       # on OpenDarwin 7.2.1
145
146and then configure GCC with:
147
148     mkdir build                                       # Create a sibling to the
149                                                       # toplevel source dir
150     cd build
151     <dir>/gcc-X.X.X/configure \                       # Don't try to build c++
152      --enable-languages=c,objc
153
154     make bootstrap
155     make install
156     cd /usr/local/lib
157     ln -s libobjc.a libobjc.dylib                     # So the linker sees us
158
159(Replace X.X.X with the actual distribution you have).
160
161GCC on Darwin doesn't appear to support threads.
162
163Darwin PowerPC:
164
165Configure and build as follows (tested using gcc-3.3.2 on Mac OS X 10.2 and
16610.3):
167
168     mkdir build
169     cd build
170     <dir>/gcc-x.x.x/configure \                       # The first option
171     [--prefix=<gcc install dir>] \                    # permits to change the
172     [--enable-languages=c,objc]                       # fact GCC installs by
173                                                       # default in /usr/local
174                                                       # The second option
175                                                       # permits to speed the
176                                                       # GCC compilation in the
177                                                       # case you will not use
178                                                       # languages other than c
179                                                       # and objc
180
181     make bootstrap
182     make install
183     cd <gcc install dir>/lib
184     ln -s libobjc.a libobjc.dylib                     # So the linker sees us
185     # Note when using gcc 4 or greater, make sure this is libobjc-gnu.dylib
186
187Setting up the GNUstep make environment
188---------------------------------------
189
190In the GNUstep-make (core/make) package, do with bourne shell like bash
191(Mac OS X 10.3):
192
193     echo 'export CC=<gcc install dir>/bin/gcc' >> ~/.profile
194
195with c shell like tcsh (Mac OS X 10.2):
196
197     echo 'setenv CC <gcc install dir>/bin/gcc' >> ~/.tcshrc
198
199else use [CC=<gcc install dir>/bin/gcc] option when running configure.
200
201then:
202
203     ./configure --with-library-combo=gnu-gnu-gnu \
204     [--prefix=<GNUstep install dir>] [CC=<gcc install dir>/bin/gcc]
205
206(apple-apple-apple is the default if you don't specify
207gnu-gnu-gnu). If you want to be able to compile for different
208targets/platforms together. Do this:
209
210     ./configure --with-library-combo=gnu-gnu-gnu --disable-flattened \
211     --enable-multi-platform [--prefix=<GNUstep install dir>] \
212     [CC=<gcc install dir>/bin/gcc]
213
214Now:
215
216     make
217     make install
218
219Source GNUstep.sh
220-----------------
221
222If you are using bourne shell like bash, type:
223
224     . <GNUstep install dir>/System/Library/Makefiles/GNUstep.sh
225
226If you are using c shell like tcsh, type:
227
228     source <GNUstep install dir>/System/Library/Makefiles/GNUstep.csh
229
230Building and installing libobjc (target Apple GCC, gnu-gnu-gnu only !!!)
231-------------------------------
232
233Warning ! Don't compile libobjc if you are using FSF GCC.  Go to gnustep-objc
234(or from CVS, into dev-libs/libobjc), and type:
235
236     make install
237     cd $GNUSTEP_SYSTEM_ROOT/Library/Libraries
238     ln -s libobjc.dylib libobjc-gnu.dylib
239
240This should build and install the GNU Objective-C runtime and headers for you.
241
242Building and installing libffi (on Darwin PowerPC only !!!)
243------------------------------
244
245There's no official libffi release. Get the one from the GNUstep ftp site
246
247     ./configure --prefix=$GNUSTEP_SYSTEM_ROOT \
248     --libdir=$GNUSTEP_SYSTEM_ROOT/Library/Libraries \
249     --includedir=$GNUSTEP_SYSTEM_ROOT/Library/Headers
250     make
251     make install
252
253Building and installing ffcall (on Darwin x86 only (may work on PPC))
254------------------------------
255
256     ./configure --prefix=$GNUSTEP_SYSTEM_ROOT \
257     --libdir=$GNUSTEP_SYSTEM_ROOT/Library/Libraries \
258     --includedir=$GNUSTEP_SYSTEM_ROOT/Library/Headers
259     make
260     make install
261
262Building and installing GNUstep-base
263------------------------------------
264
265     ./configure [--with-xml-prefix=/usr] [--disable-xmltest] [--disable-do] \
266     [LDFLAGS=-L/sw/lib] [CPPFLAGS=-I/sw/include] [CC=<gcc install dir>/bin/gcc] \
267     [CPPFLAGS=-fnested-functions]
268
269To know which options you need to use with your environment:
270
271     --disable-xmltest is needed with Mac OS X 10.3 / Darwin 7
272     versions xml2-config tool and libxml2 headers reports differents versions,
273     because of this versions conflict the GNUstep xmltest fails.
274
275     --with-xml-prefix=/usr is needed with Mac OS X 10.3 / Darwin 7 when you
276     want to build the base library with xslt support and you have installed
277     libxslt with Fink (because Fink installs lixml2 without the headers when
278     you install lixslt, and by default the base library tries to link Fink
279     libxml2 first, then the configuration fails because configure looks for
280     the libxml2 headers).
281
282     --disable-do is needed when you decide to not build libffi or ffcall. You
283     probably do not want to do this.
284
285     LDFLAGS=-L/sw/lib is needed when you installed libxslt with Fink and you
286     want to compile the base library with libxslt support.
287
288     CPPFLAGS=-I/sw/include is needed when you installed libxslt with Fink and
289     you want to compile the base library with libxslt support.
290
291     CPPFLAGS=-fnested-functions is required when using Apple gcc
292
293followed by:
294
295     make
296     make install
297
298On the apple-apple-apple target, it will only build the GNUstep additions
299library that adds extra stuff to Foundation. If you are using the
300apple-apple-apple target, there currently is no reason to go on and compile
301GNUstep-gui.
302
303Building and installing GNUstep-gui
304-----------------------------------
305
306Go to GNUstep-gui (or from CVS into the core/gui directory).
307
308     ./configure --disable-gsnd
309
310followed by:
311
312     make
313     make install
314
315Note: The gsnd server hasn't been ported to Mac OS X / Darwin yet.
316
317Some other configure options:
318    --with-jpeg-library=<jpeg libdir>
319    --with-jpeg-include=<jpeg include dir>
320      to have the libjpeg detected.
321    --disable-jpeg
322
323Building and installing GNUstep-back
324------------------------------------
325
326Warning !  You must have installed X11User.pkg from the Panther
327install disc and also X11SDK.pkg from the xCode Tools install disc to
328be able to compile GNUstep-back under Mac OS X 10.3.
329
330If you aren't installing GNUstep under Mac OS X 10.3 / Darwin 7, you can use
331XDarwin (ftp://ftp.xfree86.org/pub/XFree86/4.3.0/binaries/Darwin-ppc-6.x/) for
332the X server, take a look at http://www.xdarwin.org
333
334In the back directory, type:
335
336     ./configure
337     make
338     make install
339
340In the case, you choose to use the art backend, you will need to have the
341freetype2 and libart2 libraries installed, first be sure to have libart2 in your
342path, for example, with Fink installation type:
343
344     export DYLD_LIBRARY_PATH=/sw/lib:$DYLD_LIBRARY_PATH
345
346NOTE: I found also that even though the X11SDK.pkg package has freetype2,
347it is missing a crucial include file and also has some undefined symbols. I
348had to install the freetype2-dev package from fink and add this to my path
349so that it could be found:
350PATH=/sw/lib/freetype/bin:$PATH
351make sure in config.make that -L/sw/lib/freetype2/lib is included before -L/usr/X11R6/lib (Adam Fedor <fedor@gnu.org>) Mac OS X 10.4 doesn't have this problem.
352
353You also need to have /sw/lib in your library path before running GNUstep apps
354with the art backend, as it needs to find libart2, so put the above export
355DYLD_LIBRARY_PATH somewhere in your .profile (or do the export before launching
356an application). The backend architecture which GNUstep-gui is built upon, has
357been written to be used within X Windows, then you need to start up an X Server
358(like Apple X11) to run the GNUstep-gui applications.
359
360Warning ! With the art backend, before to launch applications based on
361GNUstep-gui, in the shell, don't forget to edit the defaults (no need it to redo
362it later):
363
364     defaults write NSGlobalDomain XWindowBufferUseXShm NO
365
366because Apple X11 doesn't support well shared memory for buffering (which
367libart2 uses by default).
368
369POTENTIAL ERRORS WHEN RUNNING MAKE ESPECIALLY WITH BACK AND GUI
370---------------------------------------------------------------
371
372If you get errors like below, just do:
373
374     make clean
375     make
376
377The second or the third time, the errors should disappear. It's probably due to
378some potential issues between FSF GCC and the libtool/ld Mac OS X / Darwin
379versions.
380
381     Linking subproject x11 ...
382     /usr/bin/ld: shared_obj/xdnd.o bad magic number (not a Mach-O file)
383     collect2: ld returned 1 exit status
384     make[3]: *** [shared_obj/subproject.o] Error 1
385     make[2]: *** [x11.all.subproject.variables] Error 2
386     make[1]: *** [libgnustep-back.all.bundle.variables] Error 2
387     make: *** [internal-all] Error 2
388
389More informations on the art backend
390------------------------------------
391
392To have a working art backend... You will also need to download and install
393fonts, as it uses a specific font format. Use for example the file
394http://w1.423.telia.com/~u42308495/alex/backart/ArtResources-0.1.2.tar.bz2 and
395put the .nfont directories somewhere in $(GNUSTEP_SYSTEM_ROOT)/Library/Fonts
396
397Other fonts are available on http://www.knuddel.org/Downloads/Fonts/
398
399Window Maker
400------------
401
402Window Maker is the traditional window manager for GNUstep.
403
404In the case you choose to use it, don't forget to execute wmaker.inst else
405Window Maker will crash with signal 10.
406
407Example with Fink, do:
408
409     /sw/bin/wmaker.inst
410
411GNUstep daemons
412---------------
413
414Refer to GNUstep-HOWTO to know how to launch GNUstep daemons.
415
416Note: If you try to start GNUstep daemons by hand with 'sudo opentool dameon',
417it won't work, because when you become root on Mac OS X / Darwin with sudo or
418su, the DYLD_LIBRARY_PATH environment variable of your user isn't used, then to
419start them in the shell, do:
420
421     sudo opentool gdomap                              # gdomap doesn't rely on
422                                                       # the GNUstep libraries
423                                                       # or other special
424                                                       # librairies.
425     su root
426
427then with bourne shell like bash (Mac OS X 10.3):
428
429     . $GNUSTEP_SYSTEM_ROOT/Library/Makesfiles/GNUstep.sh
430
431or with c shell like tcsh (Mac OS X 10.2):
432
433     source $GNUSTEP_SYSTEM_ROOT/Library/Makesfiles/GNUstep.csh
434
435and just do:
436
437     opentool gdnc
438     opentool gpbs
439
440GNUstep applications
441--------------------
442
443Now you can install GNUstep applications like Gorm, ProjectCenter etc.
444Remember the fact that when you do 'sudo make install', the $DYLD_LIBRARY_PATH
445variable of your user is not used by root. In that case, GNUstep-make could
446complain for the undefined library path, the solution is identical to the one we
447used to launch the GNUstep daemons above:
448
449     su root
450
451then with bourne shell like bash (Mac OS X 10.3):
452
453     . $GNUSTEP_SYSTEM_ROOT/Library/MakeFiles/GNUstep.sh
454
455or with c shell like tcsh (Mac OS X 10.2):
456
457     . $GNUSTEP_SYSTEM_ROOT/Library/MakeFiles/GNUstep.sh
458
459and just do:
460
461     make install
462
463Note: upon launching applications like Project Center which links a framework,
464you will probably get an error message about the library
465<Framework name>.framework/<Framework name> which cannot be found, to fix that,
466just create a symbolic link to the actual library file, which is installed
467deeper in the hierarchy:
468
469     cd $GNUSTEP_SYSTEM_ROOT/Library/Frameworks/<Framework name>.framework
470     sudo ln -s Versions/<Current version>/lib<Framework name>.dylib <Framework name>
471
472Example with the ProjectCenter framework (0.4.0 version):
473
474     cd $GNUSTEP_SYSTEM_ROOT/Library/Frameworks/ProjectCenter.framework
475     sudo ln -s Versions/0.4.0/libProjectCenter.dylib.0.4.0 ProjectCenter
476
477---
478
479That's all.
480