1 2@node Top, Introduction, (dir), (dir) 3@chapter GNUstep makefile package installation 4 5@menu 6* Introduction:: 7* Configuration:: 8* Installation:: 9* Setup:: 10@end menu 11 12@node Introduction, Configuration, Top, Top 13@section Introduction 14 15If you are installing this package as part of the GNUstep core 16libraries, read the file GNUstep-HOWTO for more complete instructions 17on how to install the entire GNUstep package (including this package). 18GNUstep-HOWTO comes with this distribution. 19 20This should be the first GNUstep package you install. Before 21installing this package, install ffcall or libffi and any other 22libraries that GNUstep may need (see the GNUstep-HOWTO). Read and 23follow the instructions on setting up the GNUstep environement below. 24Then install gnustep-base. 25 26Make sure you've read the machine-specific instructions for your 27particular operating system and CPU. These instructions come with the 28GNUstep-HOWTO and are also located at the GNUstep web site at 29@url{http://www.gnustep.org}. 30 31Quick installation instructions: 32 33@example 34./configure 35make 36make install 37@end example 38 39This will use the default 'FHS' filesystem layout rooted in /usr/local 40(in other words, all of GNUstep will end up installed into /usr/local 41in a Unix fashion). Another popular option is 42 43@example 44./configure --with-layout=gnustep 45make 46make install 47@end example 48 49which will use the GNUstep filesystem (in other words, all of GNUstep 50will end up installed into /usr/GNUstep using a GNUstep-tailored 51filesystem layout). 52 53To make and install the documentation: 54 55@example 56cd Documentation 57make 58make install 59@end example 60 61@node Configuration, Installation, Introduction, Top 62@section Configuration 63 64The GNUstep packages uses the Autoconf mechanism for configuration; it 65checks some host capabilties which are used by all GNUstep software. 66To configure just type: 67 68@example 69./configure 70@end example 71 72The GNUstep makefile package needs to know which filesystem layout to 73use when installing; this determines the way that various directories 74in the GNUstep domains (SYSTEM, NETWORK, LOCAL, USER) are mapped to 75local directories on disk. In the FilesystemLayouts/README file you 76can find detailed information on filesystem layouts. 77 78To specify a filesystem layout, use the --with-layout=xxx option. The 79default is 80 81@example 82./configure --with-layout=fhs 83@end example 84 85which installs GNUstep in /usr/local using the FHS layout (that is, 86/usr/local/bin, /usr/local/lib, etc). Another popular option is 87'--with-layout=gnustep' which installs gnustep-make into a GNUstep 88layout based on /usr/GNUstep (inside /usr/GNUstep/System, 89/usr/GNUstep/Local). Check the FilesystemLayouts for more options. 90 91If you want to install the same layout but in a different location 92(for example, /opt/gnustep), you can use --prefix=xxx, 93 94@example 95./configure --prefix=/opt/gnustep 96@end example 97 98If you're confused and want to see exactly what directories will be 99used for a certain choice of ./configure flags, you can check the 100output of ./configure or even have a look at the GNUstep.conf file 101that is generated by ./configure. It will list the full paths to all 102the relevant GNUstep directories that would be used if you install the 103software with that configuration. 104 105To see more options you can use with configure, type 106 107@example 108./configure --help 109@end example 110 111Look particularly at the end of the list that configure gives, as these 112options are specific to GNUstep. Some of these are described below. 113 114With the GNUstep packages you can use various switches, such as shared 115and debug, to control compilation. for example, ``make shared=no 116debug=yes'' compiles using static libraries with debugging 117information. (Make sure you use the same switches for every package you 118compile, and also when you install). 119 120@menu 121* Backend Bundles:: 122* Alternate Libraries:: 123* Alternate Thread Library:: 124* Flat Structure:: 125* Cross-Compiling:: 126@end menu 127 128@node Backend Bundles, Alternate Libraries, Configuration, Configuration 129@subsection Backend Bundles 130 131By default, the gnustep-make package specifies that GUI backends are built 132as a bundle and loaded in at runtime. This allows one to switch backends 133by simply redefining a user default. If you do not want this behavior (for 134instance, if bundles do not work on your platform), it can be disabled using 135 136@example 137--disable-backend-bundle 138@end example 139 140in the arguments to configure. 141 142@node Alternate Libraries, Alternate Thread Library, Backend Bundles, Configuration 143@subsection Alternate Library Setup 144 145You can specify compilation of alternate libraries by using the 146with-library-combo option. 147 148@example 149./configure --with-library-combo=apple-gnu-gnu 150@end example 151 152to compile with Apple's runtime on Darwin, for example. See the DESIGN 153document for more examples of the variety of library combos. 154 155@node Alternate Thread Library, Flat Structure, Alternate Libraries, Configuration 156@subsection Alternate Thread Library 157 158You can specify compilation of an alternate thread library from the one that 159is normally used (or if GNUstep does not know what your normal library is) 160with the with-thread-lib option. 161 162@example 163./configure --with-thread-lib="-L/usr/local/lib -lgthread -lglib" 164@end example 165 166to use libgthread as your threading library. Note that the Objective-C 167runtime (libobjc) must have a compatible threading backend in order to 168use this threading library and you must set the appropriate threading backend 169by hand in the GNUmakefile if you are using gnustep-objc. If you also need 170to set compiler flags, use the CPPFLAGS variable when calling configure: 171 172@example 173CPPFLAGS="-I/usr/local/include" ./configure --with-thread-lib="-L/usr/local/lib -lgthread -lglib" 174@end example 175 176@node Flat Structure, Cross-Compiling, Alternate Thread Library, Configuration 177@subsection Configuring for a non-flattened structure 178 179GNUstep is normally configured to support a single target/combo. If you are 180interested in supporting more than one target and/or combo, it's possible to 181configure GNUstep to use a non-'flattened' directory structure. 182You do this by supplying the @code{--disable-flattened} argument to configure. 183You might also want to supply the @code{--enable-multi-platform} option. 184 185In a flattened structure, files are stored at the top-level rather than 186in a @code{$(GNUSTEP_CPU)/$(GNUSTEP_OS)/$(LIBRARY_COMBO)} subdirectory. 187 188@node Cross-Compiling, , Flat Structure, Configuration 189@subsection Configuring for a cross-compile target 190 191By default when you run configure, it assumes that you want to create 192executables for the same host that you are compiling on; however, the 193GNUstep makefile package has been designed to support cross-compiling 194just as easily as normal compiling. In order to add a cross-compile 195target to the GNUstep makefile package, you must rerun configure for 196that target and reinstall the makefile package. By rerunning 197configure, the appropriate target settings are determined, and 198reinstalling the makefile package installs the appropriate files for 199that target. The target parameter is used to specify the target 200platform for cross-compiling: 201 202@example 203./configure --target=i386-mingw32 204make install 205@end example 206 207GNUstep normally is configured to work with only one target. To work 208with multiple targets, you'll need to add @code{--disable-flattened} 209and @code{--enable-multi-platform} to the configure flags. Files for 210the different targets will not be overwritten when you configure and install 211the make package several times. 212 213@example 214./configure --disable-flattened --enable-multi-platform --target=i386-mingw32 215make install 216./configure --disable-flattened --enable-multi-platform --target=sparc-solaris2.5 217make install 218./configure --disable-flattened --enable-multi-platform --target=alpha-linux-gnu 219make install 220@end example 221 222@node Installation, Setup, Configuration, Top 223@section Installation 224 225After you configure the GNUstep makefile package, you can go straight 226into installation (there is nothing to compile): 227 228@example 229make install 230@end example 231 232After you have installed the GNUstep makefile package, there might 233still be some minor administration to be performed, depending on your 234configuration. 235 236@node Setup, UserDomainSetup, Installation, Top 237@section Setting up the GNUstep environment 238 239GNUstep-make will install all programs and libraries in the 240directories specified by the filesystem layout that you choose. 241 242In here we explain how to set up your environment so that the 243operating system can find the programs and libraries in these 244directories. 245 246The procedure depends on the type of layout (flattened or 247non-flattened), and on the amount of advanced options that you want to 248use. 249 250@menu 251* Flattened:: 252* Non-Flattened:: 253* UserDomainSetup:: 254* MultipleInstallations:: 255@end menu 256 257@node Flattened, Non-Flattened, Setup, Setup 258@subsection Flattened (default) Setup 259 260In a flattened setup (the default unless you use the 261--disable-flattened configure argument), you can use a simple setup 262where you just need to make sure that the few program and library 263directories are found by the shell/linker. 264 265Check the description of your filesystem in FilesystemLayouts to find 266precise simplified instructions for your layout. 267 268In general, you need to your GNUSTEP_SYSTEM_TOOLS, 269GNUSTEP_NETWORK_TOOLS and GNUSTEP_LOCAL_TOOLS to your PATH, and add 270your GNUSTEP_SYSTEM_LIBRARIES, GNUSTEP_NETWORK_LIBRARIES and 271GNUSTEP_LOCAL_LIBRARIES to your linker paths (which is /etc/ld.so.conf 272on GNU/Linux). 273 274To build software, you also need to set GNUSTEP_MAKEFILES. (PS: This requirement 275is likely to go away soon) 276 277@node Non-Flattened, , Flattened, Setup 278@subsection Non-Flattend (fat binary) Setup 279 280(Advanced configuration) 281 282If the setup is non-flattened (ie, fat binary support is enabled) 283programs and libraries will be installed in appropriate subdirectories 284so that binaries for different machines/library-combos can coexist. 285This is the case only if you configure gnustep-make with the option 286--disable-flattened. 287 288It is recommended that this option is used with the GNUstep filesystem 289layout; and that the GNUstep environment is set up by sourcing the 290GNUstep.sh file. 291 292@example 293. /usr/GNUstep/System/Library/Makefiles/GNUstep.sh 294@end example 295 296(change the path to be the path to your GNUstep.sh file on disk. 297Common cases include /usr/GNUstep/System/Library/Libraries/Makefiles 298and /usr/local/share/GNUstep/Makefiles) 299 300You can run this command in your shell every time, or you may want to 301add the command to your shell startup scripts - either the ones for 302your own user (for example, @file{.bash_profile} for Bash) or the ones 303for the whole system (for example, @file{/etc/profile} on GNU/Linux). 304 305Please note that you need to execute this command both to build 306software using gnustep-make and to run software installed by 307gnustep-make. 308 309@node UserDomainSetup, MultipleInstallations, Setup, Setup 310@section Setting up your GNUstep User domain 311 312(Advanced configuration) 313 314The USER domain is generally expected to be in your home directory; 315you can use the USER domain to install programs or libraries in your 316home directory without affecting other users. 317 318If you want to access programs or libraries installed in your USER 319domain, then you really need to source GNUstep.sh in all cases (both 320flattened and non-flattened), as explained in the Non-Flattened 321section. 322 323If you want to change the filesystem layout of your USER domain 324(without reinstalling gnustep-make or affecting other people's USER 325domains), you can do so at runtime by creating a file called 326~/.GNUstep.conf (this might have a different name if your filesystem 327layout specifies otherwise). 328 329In that file, you can set all the GNUSTEP_USER_* variables set in 330GNUstep.conf. Check your GNUstep.conf for a full description. Here 331is an example in which all the GNUstep domain is moved into 332~/Test/GNUstep instead of ~/GNUstep: 333 334@example 335GNUSTEP_USER_DIR=Test/GNUstep 336@end example 337 338@node MultipleInstallations, , UserDomainSetup, Setup 339@section Having multiple gnustep-makes installed at the same time 340 341(Advanced configuration) 342 343You can install gnustep-make multiple times in different directories 344by using a different config file for each. But if you do, then you 345must make sure that you can easily switch the operating system paths 346from one installation to the other. An easy way to do this is to 347configure your GNUstep by using GNUstep.sh as explained in the 348non-flattened instructions. 349 350Your default gnustep-make installation is the one described in the 351default GNUstep.conf file for the system; on GNU/Linux this is 352@file{/etc/GNUstep/GNUstep.conf}. You can create a second one that 353uses a different config file; for example: 354 355@example 356./configure --prefix=/opt/mytest --with-config-file=/etc/GNUstep-mytest.conf --with-layout=gnustep 357@end example 358 359When you install, this second instance of gnustep-make will reside in 360@file{/opt/mytest}, and have @file{/etc/GNUstep-mytest.conf} as config 361file. 362 363To use this second installation instead of the first one, you only 364need to set the GNUSTEP_CONFIG_FILE variable to point to the next 365config file and source GNUstep.sh: 366 367@example 368export GNUSTEP_CONFIG_FILE=/etc/GNUstep-mytest.conf 369. /opt/mytest/System/Library/Makefies/GNUstep.sh 370@end example 371 372To stop using a GNUstep installation, reset your GNUstep environment 373with the GNUstep-reset.sh script and destroy the variable 374GNUSTEP_CONFIG_FILE -- 375 376@example 377. /opt/mytest/System/Library/Makefies/GNUstep-reset.sh 378unset GNUSTEP_CONFIG_FILE 379@end example 380 381After this, you are ready to start using a new one (by setting a new 382GNUSTEP_CONFIG_FILE and then sourcing the GNUstep.sh of the new one). 383 384@bye 385