1\input texinfo @c -*-texinfo-*- 2@c GNUstep installation instructions 3@c %**start of header 4@setfilename gnustep-howto.info 5@settitle GNUstep HOWTO 6@c %**end of header 7@set HOWTO 8@smallbook 9 10@titlepage 11@title GNUstep HOWTO 12@subtitle Installing the GNUstep developement system 13 14@vskip 0pt plus 1filll 15@emph{This document explains how to build the different components of 16the GNUstep core libraries.} 17 18Last Update: @today{} 19 20 21@page 22@vskip 0pt plus 1filll 23Copyright @copyright{} 1996 - 2007 Free Software Foundation, Inc. 24 25Permission is granted to copy, distribute and/or modify this document 26under the terms of the GNU Free Documentation License, Version 1.1 or 27any later version published by the Free Software Foundation. 28 29@end titlepage 30 31@contents 32 33@ifinfo 34@format 35 GNUstep HOWTO 36 ************* 37 38 Last Update: @today{} 39 40 This document explains how to build the different components of the 41 GNUstep core libraries and GNUstep Launchpad. 42 43 Copyright (C) 1996 - 2007 Free Software Foundation, Inc. 44 45 Permission is granted to copy, distribute and/or modify this document 46 under the terms of the GNU Public License, Version 1.0 or 47 any later version published by the Free Software Foundation. 48@end format 49 50@end ifinfo 51 52@include version.texi 53 54@node Top, Introduction, (dir), (dir) 55 56@menu 57* Introduction:: 58* Preliminaries:: 59* Compiling and Installing:: 60* Additional Installation:: 61* Tools and Applications:: 62* Machine Specific:: 63* Source via git:: 64@end menu 65 66@node Introduction, Preliminaries, Top, Top 67@chapter Introduction 68 69This document explains how to build the GNUstep core libraries. The 70core libraries, along with associated tools and other files provide 71everything necessary for a working GNUstep system. 72 73In order to easily compile and debug GNUstep projects, you will need the 74GNU Objective-C compiler @samp{GCC} as well as various other GNU packages. 75 76You will need at least 80Mb of hard disk space (150Mb prefered) in order 77to compile the GNUstep core libraries. 78 79@node Preliminaries, Compiling and Installing, Introduction, Top 80@chapter Summary 81 82In order to compile the libraries, you need to compile and install 83the following packages first (if you don't already have them): 84 85@itemize @bullet 86@item gcc (Version 2.95 or greater, 3.0.4 or greater recommended) 87@item GNU make (Version 3.75 or greater) 88@item gdb (Version 6.0 or greater recommended), if you plan to do any debugging 89@end itemize 90 91You may also need to install some of the following libraries and 92packages described below. Most of these packages are optional, but some 93are required. 94 95@table @samp 96@item ffcall libraries (HIGHLY RECOMMENDED) 97This is a library that provides stack-frame handling for NSInvocation 98and NSConnection. This library is highly recommended. The previous 99builtin method for stack frame handling is no longer supported and may 100be removed in the future. ffcall is under GNU GPL. As a special 101exception, if used in GNUstep or in derivate works of GNUstep, the 102included parts of ffcall are under GNU LGPL. 103 104@item libffi library (ALTERNATIVE RECOMMENDATION) 105This is a library that provides stack frame handling for NSInvocation 106and NSConnection similar to ffcall. 107Use this instead of ffcall. You don't need both. 108 109@item libxml2 (RECOMMENDED) 110The libxml library (Version 2) is used to translate some of the 111documentation for GNUstep and to provide suport for MacOS-X compatible 112XML-based property-lists. It is not required, but you have to explicitly 113disable use of XML when compiling GNUstep base if you do not have it. 114 115@item libxslt (OPTIONAL) 116Stylesheet support for use with XML. 117 118@item openssl (OPTIONAL) 119The openssl library is used to provide support for https connections by 120the NSURL and HSURLHandle classes. This functionality is 121compiled as a separate bundle since the OpenSSL license is not 122compatible with GPL, and in the hopes that if someone writes an openssl 123replacement, it can quickly be used by creating another bundle. 124 125@item libiconv (OPTIONAL) 126Note: Do not install this library unless you are sure you need it. 127You probably don't need it except perhaps on MinGW. 128Unicode support functions (iconv) come with glibc version 2.1 or greater. If 129you don't have glibc (try iconv --version), you can get the separate 130libiconv library from 131@url{http://clisp.cons.org/~haible/packages-libiconv.html}. However, 132neither one is required to use GNUstep. 133 134@item The TIFF library (libtiff) (Version 3.4beta36 or greater) (REQUIRED) 135The GUI library uses this to handle loading and saving TIFF images. 136 137@item The JPEG library (libjpeg) (RECOMMENDED) 138The GUI library uses this to handle loading JPEG images. 139 140@item The PNG library (libpng) (RECOMMENDED) 141The GUI library uses this to handle loading PNG images. 142 143@item gif or ungif (OPTIONAL) 144The GUI library uses either one of these libraries to load GIF images. 145 146@item aspell (OPTIONAL) 147The GUI library uses this to handle spell checking. 148 149@item cups (OPTIONAL) 150The GUI library uses this to handle interface to the CUPS print servers. 151 152@item audiofile (OPTIONAL) 153The GUI library uses this for playing sound files. 154 155@item portaudio (OPTIONAL) 156The GUI library uses this for the sound server. Use v19, which has 157several API changes since the previous version. v19 hasn't actually been 158formally released, but several distributions (SuSE, etc) use it anyway. 159 160@item freetype2 (RECOMMENDED, REQUIRED for art backend) 161This is used for font information. Freetype2 cache API is in flux. 162GNUstep tries to account for 163this, but if you get errors about undefined FTC_ symbols, you might be 164using an unsupported version of freetype. 165 166@item libart_lgpl2 (REQUIRED for art backend only) 167Drawing library for the art backend. 168 169@item WindowMaker (Version >= 0.62) (OPTIONAL) 170GNUstep and WindowMaker work together to provide a consistant interface. 171Although it is not required, GNUstep will work much better if you use it 172with the WindowMaker window manager. 173Get WindowMaker from @url{http://www.windowmaker.info}. 174 175@item gnustep-objc package (REQUIRED BUT ONLY for gcc version < 3.0 or MINGW/Cygwin) 176Note: Do not install this library unless you are sure you need it. 177You probably don't need it except on MinGW and Cygwin (regardless of the 178gcc version you have). 179This is a special version of the Objective-C runtime that is compiled 180as a shared library. 181It is available at @url{ftp://ftp.gnustep.org/pub/gnustep/libs} which 182compiles using the GNUstep Makefile package (so you don't have to get the 183entire gcc dist). Make sure to set the THREADING variable in the GNUmakefile. 184It's possible to compile the library static (make shared=no) and 185just copy to the place where the gcc libobjc library is (type gcc -v to 186get this location). Note you have to install gnustep-make (below) before 187installing this library. 188 189@item GDB (OPTIONAL) 190GDB can be obtained from @url{ftp://ftp.gnu.org/gnu/gdb}. As of release 1916.0, gdb has special support for debugging Objective-C programs. 192 193@item TeX (OPTIONAL) 194You need a TeX implementation, like tetex, to compile some of the 195documentation (although most of that is available on the web). 196@end table 197 198@node Compiling and Installing, Additional Installation, Preliminaries, Top 199@chapter Compiling and Installing the packages 200 201Get the following individual packages: 202 203@itemize @bullet 204@item gnustep-make 205@item gnustep-base 206@item gnustep-gui 207@item gnustep-back 208@end itemize 209 210See @url{http://www.gnustep.org} for information on where to get these 211packages. 212 213Make sure you install (if necessary) all the previously mentioned 214libraries first before configuring and building GNUstep. 215 216You should install these packages as root (read special note for the 217gnustep-base library, below, if you cannot do this). 218 219For installation on specific systems, read the machine specific 220instructions at the end of this document or appropriate README files in 221the gnustep-make Documentation directory (such as README.MingW for Windows). 222 223@menu 224* Core Package:: 225@end menu 226 227@node Core Package, , Compiling and Installing, Compiling and Installing 228@section Installing the Core Libraries 229 230The GNUstep packages uses the Autoconf mechanism for configuration; it 231checks some host capabilities which are used by all GNUstep software. 232The first package you will compile is gnustep-make. To configure 233gnustep-make just type: 234 235@example 236./configure 237@end example 238 239The GNUstep makefile package can be configured to use different types 240of filesystem layouts. By default, GNUstep is installed with a 241Unix-style filesystem layout into /usr/local/. That is a good, 242recommended default if you don't have an opinion on which filesystem 243layout to use. 244 245But you can also install it somewhere else by using the prefix 246parameter; the following command installs it in /opt/GNUstep: 247 248@example 249./configure --prefix=/opt/GNUstep 250@end example 251 252You can also install GNUstep using a GNUstep layout (or some other 253filesystem layout of your choice) by using the with-layout parameter; 254the following command configures GNUstep to use the traditional 255GNUstep layout: 256 257@example 258./configure --with-layout=gnustep 259@end example 260 261In this document we will always present examples that assume that you 262are using the default filesystem layout in /usr/local/. If you are 263using a different layout, you will need to make the obvious changes. 264 265@menu 266* Alternate Library Setup:: 267* Individual Packages:: 268@end menu 269 270@node Alternate Library Setup, Individual Packages, Core Package, Core Package 271@subsection Alternate Library Setup 272 273Read the installation instructions in the Makefile package (make) for more 274installation options. Make sure you use the same 275configuration options when configuring each GNUstep library. 276 277@node Individual Packages, , Alternate Library Setup, Core Package 278@subsection Building the Package 279 280To build the individual packages, use this familiar set of commands for 281each pacakge (add any additional options you decide upon): 282 283@example 284./configure 285make 286make install 287@end example 288 289Start with the Makefile Package (gnustep-make). After installing 290gnustep-make you need to execute GNUstep's shell configuration script, 291as follows: 292 293@example 294 . /usr/local/share/GNUstep/Makefiles/GNUstep.sh 295@end example 296 297before proceeding any further. 298 299NOTE for gcc 2.X or MinGW users: Now install gnustep-objc. Before building 300gnustep-objc, edit the @file{GNUmakefile} and set the @var{THREADING} 301variable to the thread library used on your system (usually its posix, 302but you can leave it at single if you don't need threads). At this point 303you should probably re-configure, make and install gnustep-make, so it 304can pick up on any threading information that gnustep-objc provides. 305 306Now install gnustep-base, gnustep-gui and finally gnustep-back. 307 308NOTE: If you are trying to install the packages without root permission, 309you may need to change one thing in the base library. Edit the file 310gnustep-base/Tools/gdomap.h to uncomment the last line and modify 311the specified port number to a port which you @emph{know} is not in use on 312your network. You should only do this if absolutely necessary since 313making this change will break communications with any systems where 314an identical change has not been made. Also, the standard gdomap port 315is the one officially registered with IANA and is reserved for use by 316gdomap - it should only be changed if you can't get your system 317administrator to start the gdomap server using it. 318 319@node Additional Installation, Tools and Applications, Compiling and Installing, Top 320@chapter Additional Installation 321 322@menu 323* Environment Setup:: 324* GNUstep Home:: 325* Time Zone:: 326* GNUstep deamons:: 327@end menu 328 329@node Environment Setup, GNUstep Home, Additional Installation, Additional Installation 330@section Environment Setup 331 332You need to make sure your environment is properly setup in order to 333compile and run GNUstep software. The steps to setup your environment 334differ slightly depending on your filesystem layout. 335 336There is a way of setting up your environment that always works: 337sourcing the @file{GNUstep.sh} shell script before using GNUstep. The 338shell script @file{GNUstep.sh} is located in the Makefile package; you 339may want to add it to your shell startup file (such as 340@file{.profile}). For instance, if you installed GNUstep with the 341default filesystem layout in @file{/usr/local}, then adding 342 343@example 344. /usr/local/share/GNUstep/Makefiles/GNUstep.sh 345@end example 346 347in your @file{.profile} file will work. Note the period at the 348beginning of the line, and the space between the period and the 349following path. If you installed GNUstep somewhere else, you need to 350replace @file{/usr/local/share/GNUstep/Makefiles/GNUstep.sh} with the 351path to your @file{GNUstep.sh} script. Another typical location is 352@file{/usr/GNUstep/System/Library/Makefiles}, which is the default 353location of your @file{GNUstep.sh} script when gnustep-make is 354configured with the GNUstep layout. The script defines environment 355variables that are needed to find GNUstep files and executables. 356 357Users of csh need to use the @file{GNUstep.csh} script. Read the make 358package @file{README} for more info. Some systems, like GNU/Linux have 359an @file{/etc/profile.d} directory where scripts can be executed 360automatically. If you want to set up GNUstep for every user on your 361system, you can try copying/linking the @file{GNUstep.sh} there. For 362csh or tcsh, try 363 364@example 365source /usr/local/share/GNUstep/Makefiles/GNUstep.csh 366@end example 367 368Finally, in most filesystem configuration it's also possible to 369manually set up your environment by setting PATH, the linker library 370paths and the @code{GNUSTEP_MAKEFILES} variable (instead of using 371@file{GNUstep.sh}). For example, on GNU/Linux (with a default GNUstep 372installation), instead of sourcing @file{GNUstep.sh} you could manually 373add the Tools directories to your PATH: 374 375@example 376PATH="/usr/local/bin:$PATH" 377@end example 378 379manually add @file{/usr/local/lib} to your @file{/etc/ld.so.conf} file 380(don't forget to run @code{ldconfig} every time you install a 381library), and set the environment variable @code{GNUSTEP_MAKEFILES} 382when you want to compile something: 383 384@example 385GNUSTEP_MAKEFILES=/usr/local/share/GNUstep/Makefiles 386@end example 387 388@node GNUstep Home, Time Zone, Environment Setup, Additional Installation 389@section GNUstep Home 390 391Your home GNUstep directory should be created automatically the first 392time you use a GNUstep tool or application. This is where user 393defaults are kept as well as other user configuration files. User 394installed apps, libraries, etc are also here (if the default user 395directory is used). By default this is the directory @file{GNUstep} 396under your home directory, but you can change this (see the 397gnustep-make installation documentation). 398 399@node Time Zone, GNUstep deamons, GNUstep Home, Additional Installation 400@section Time Zone 401 402In most cases, GNUstep should be able to determine your time zone, if 403you have already set it up correctly when setting up your 404computer. However, in some cases this might fail or the correct 405information may not be available. You can set it manually using the 406GNUstep defaults utility to set @kbd{Local Time Zone} to your local time 407zone. Type something like @kbd{defaults write NSGlobalDomain "Local 408Time Zone" GB}. Where @kbd{GB} is a time zone abbreviation. 409 410See 411@file{/usr/local/lib/GNUstep/Libraries/gnustep-base/Versions/1.21/Resources/NSTimeZones/zones/} 412(or equivalent on your system depending on your filesystem layout) for 413typical time zones. 414 415@node GNUstep deamons, , Time Zone, Additional Installation 416@section GNUstep deamons 417 418Set up your system to execute some GNUstep deamons. This is optional 419because if you don't do this, they will be started automatically when 420you run your first GNUstep app: 421 422@itemize @bullet 423@item gdomap - Put this in a system startup file, like @file{/etc/rc.local} or @file{/etc/rc.d/rc.local} (customize for your system) 424@example 425if [ -f /usr/local/bin/gdomap ]; then 426 /usr/local/bin/gdomap 427fi 428@end example 429@item gdnc - Start after sourcing @file{GNUstep.sh} (e.g. in .profile) 430@item gpbs - Same as with gdnc, make sure X-Windows is running. 431@item make_services - Not a deamon, but a tool that needs to be run everytime 432you install a new Application or service. This is NOT run automatically. 433@end itemize 434 435@example 436if [ `gdomap -L GDNCServer | grep -c Unable` == 1 ]; then 437 echo "Starting GNUstep services..." 438 gdnc 439 gpbs 440fi 441make_services 442@end example 443 444 445@node Tools and Applications, Machine Specific, Additional Installation, Top 446@chapter Test Tools and Applications 447 448Example applications are located in the gstep-examples package. To 449build these, just uncompress and untar this package, cd to the 450appropriate directory, and type make. You will need to install the 451GNUstep core libraries first before doing this. 452 453To run the examples. Use the openapp utility that is part of the 454GNUstep makefile package (and stored in @file{/usr/local/bin}). Usage 455is: 456 457@example 458openapp application_name [additional arguments to app] 459@end example 460 461Good Luck! 462 463@node Machine Specific, Source via git, Tools and Applications, Top 464@chapter Machine Specific Instructions 465 466A list of machines that GNUstep works on can be found on the GNUstep 467Wiki @url{http://wiki.gnustep.org/index.php/Platform_compatibility}. 468 469@node Source via git, , Machine Specific, Top 470@chapter Getting Libraries via git 471 472If you didn't get one of the snapshots, or if you want to be sure to 473stay on the bleeding edge, then you should get the libraries via git. Go 474to @url{http://www.gnustep.org/resources/sources.html} for information on how 475to get the sourcecode. 476 477To fetch all the GNUstep core libraries, you can clone the covenient @file{core} 478repository: 479@example 480git clone --recurse-submodules https://github.com/gnustep/core.git 481@end example 482 483After you have checked out the source you can compile it as 484usual. To update the source, go into the directory of the source tree 485you want to update, for example, go into 'base', and type: 486 487@example 488git pull 489@end example 490 491You don't have to re-checkout after you have the source, just pull! 492 493@bye 494\bye 495