1 GNUstep makefile package installation *************************************** 1.1 Introduction ================ If you are installing this package as part of the GNUstep core libraries, read the file GNUstep-HOWTO for more complete instructions on how to install the entire GNUstep package (including this package). GNUstep-HOWTO comes with this distribution. This should be the first GNUstep package you install. Before installing this package, install ffcall or libffi and any other libraries that GNUstep may need (see the GNUstep-HOWTO). Read and follow the instructions on setting up the GNUstep environement below. Then install gnustep-base. Make sure you've read the machine-specific instructions for your particular operating system and CPU. These instructions come with the GNUstep-HOWTO and are also located at the GNUstep web site at . 1.1.1 Quick Installation Instructions --------------------- To build and install the GNUstep Makefiles, run the following commands: ./configure make make install This will use the default 'FHS' filesystem layout rooted in /usr/local (in other words, all of GNUstep will end up installed into /usr/local in a Unix fashion). Another popular option is ./configure --with-layout=gnustep make make install which will use the GNUstep filesystem (in other words, all of GNUstep will end up installed into /usr/GNUstep using a GNUstep-tailored filesystem layout). To make and install the documentation: cd Documentation make make install 1.1.2 Enabling Modern Objective-C Features --------------------- GNUstep supports the legacy GCC runtime, and the modern libobjc2 runtime with Objective-C 2.0 Features such as ARC, Blocks (closures), Synthesised property accessors, Efficient support for @synchronized() and more. libobjc2 requires building with clang. If you've installed both clang and libobjc2 you can configure GNUstep Make to use the newer runtime and features. Here is an example with the runtime version set to 2.2. (Set it to the last libobjc2 version to benefit from possible changes in Clang CodeGen). Please note that we explicitly enable some features such as objc-arc that might be infered from the runtime version. ./configure \ --enable-native-objc-exceptions \ --enable-objc-arc \ --with-runtime-abi=gnustep-2.2 \ --with-library-combo=ng-gnu-gnu \ CC="clang" CXX="clang++" CPP="clang -E" LDFLAGS="-fuse-ld=lld" 1.2 Configuration ================= The GNUstep packages uses the Autoconf mechanism for configuration; it checks some host capabilties which are used by all GNUstep software. To configure just type: ./configure The GNUstep makefile package needs to know which filesystem layout to use when installing; this determines the way that various directories in the GNUstep domains (SYSTEM, NETWORK, LOCAL, USER) are mapped to local directories on disk. In the FilesystemLayouts/README file you can find detailed information on filesystem layouts. To specify a filesystem layout, use the -with-layout=xxx option. The default is ./configure --with-layout=fhs which installs GNUstep in /usr/local using the FHS layout (that is, /usr/local/bin, /usr/local/lib, etc). Another popular option is '-with-layout=gnustep' which installs gnustep-make into a GNUstep layout based on /usr/GNUstep (inside /usr/GNUstep/System, /usr/GNUstep/Local). Check the FilesystemLayouts for more options. If you want to install the same layout but in a different location (for example, /opt/gnustep), you can use -prefix=xxx, ./configure --prefix=/opt/gnustep If you're confused and want to see exactly what directories will be used for a certain choice of ./configure flags, you can check the output of ./configure or even have a look at the GNUstep.conf file that is generated by ./configure. It will list the full paths to all the relevant GNUstep directories that would be used if you install the software with that configuration. To see more options you can use with configure, type ./configure --help Look particularly at the end of the list that configure gives, as these options are specific to GNUstep. Some of these are described below. With the GNUstep packages you can use various switches, such as shared and debug, to control compilation. for example, "make shared=no debug=yes" compiles using static libraries with debugging information. (Make sure you use the same switches for every package you compile, and also when you install). 1.2.1 Backend Bundles --------------------- By default, the gnustep-make package specifies that GUI backends are built as a bundle and loaded in at runtime. This allows one to switch backends by simply redefining a user default. If you do not want this behavior (for instance, if bundles do not work on your platform), it can be disabled using --disable-backend-bundle in the arguments to configure. 1.2.2 Alternate Library Setup ----------------------------- You can specify compilation of alternate libraries by using the with-library-combo option. ./configure --with-library-combo=apple-gnu-gnu to compile with Apple's runtime on Darwin, for example. See the DESIGN document for more examples of the variety of library combos. 1.2.3 Alternate Thread Library ------------------------------ You can specify compilation of an alternate thread library from the one that is normally used (or if GNUstep does not know what your normal library is) with the with-thread-lib option. ./configure --with-thread-lib="-L/usr/local/lib -lgthread -lglib" to use libgthread as your threading library. Note that the Objective-C runtime (libobjc) must have a compatible threading backend in order to use this threading library and you must set the appropriate threading backend by hand in the GNUmakefile if you are using gnustep-objc. If you also need to set compiler flags, use the CPPFLAGS variable when calling configure: CPPFLAGS="-I/usr/local/include" ./configure --with-thread-lib="-L/usr/local/lib -lgthread -lglib" 1.2.4 Configuring for a non-flattened structure ----------------------------------------------- GNUstep is normally configured to support a single target/combo. If you are interested in supporting more than one target and/or combo, it's possible to configure GNUstep to use a non-'flattened' directory structure. You do this by supplying the '--disable-flattened' argument to configure. You might also want to supply the '--enable-multi-platform' option. In a flattened structure, files are stored at the top-level rather than in a '$(GNUSTEP_CPU)/$(GNUSTEP_OS)/$(LIBRARY_COMBO)' subdirectory. 1.2.5 Configuring for a cross-compile target -------------------------------------------- By default when you run configure, it assumes that you want to create executables for the same host that you are compiling on; however, the GNUstep makefile package has been designed to support cross-compiling just as easily as normal compiling. In order to add a cross-compile target to the GNUstep makefile package, you must rerun configure for that target and reinstall the makefile package. By rerunning configure, the appropriate target settings are determined, and reinstalling the makefile package installs the appropriate files for that target. The target parameter is used to specify the target platform for cross-compiling: ./configure --target=i386-mingw32 make install GNUstep normally is configured to work with only one target. To work with multiple targets, you'll need to add '--disable-flattened' and '--enable-multi-platform' to the configure flags. Files for the different targets will not be overwritten when you configure and install the make package several times. ./configure --disable-flattened --enable-multi-platform --target=i386-mingw32 make install ./configure --disable-flattened --enable-multi-platform --target=sparc-solaris2.5 make install ./configure --disable-flattened --enable-multi-platform --target=alpha-linux-gnu make install 1.3 Installation ================ After you configure the GNUstep makefile package, you can go straight into installation (there is nothing to compile): make install After you have installed the GNUstep makefile package, there might still be some minor administration to be performed, depending on your configuration. 1.4 Setting up the GNUstep environment ====================================== GNUstep-make will install all programs and libraries in the directories specified by the filesystem layout that you choose. In here we explain how to set up your environment so that the operating system can find the programs and libraries in these directories. The procedure depends on the type of layout (flattened or non-flattened), and on the amount of advanced options that you want to use. 1.4.1 Flattened (default) Setup ------------------------------- In a flattened setup (the default unless you use the -disable-flattened configure argument), you can use a simple setup where you just need to make sure that the few program and library directories are found by the shell/linker. Check the description of your filesystem in FilesystemLayouts to find precise simplified instructions for your layout. In general, you need to your GNUSTEP_SYSTEM_TOOLS, GNUSTEP_NETWORK_TOOLS and GNUSTEP_LOCAL_TOOLS to your PATH, and add your GNUSTEP_SYSTEM_LIBRARIES, GNUSTEP_NETWORK_LIBRARIES and GNUSTEP_LOCAL_LIBRARIES to your linker paths (which is /etc/ld.so.conf on GNU/Linux). To build software, you also need to set GNUSTEP_MAKEFILES. (PS: This requirement is likely to go away soon) 1.4.2 Non-Flattend (fat binary) Setup ------------------------------------- (Advanced configuration) If the setup is non-flattened (ie, fat binary support is enabled) programs and libraries will be installed in appropriate subdirectories so that binaries for different machines/library-combos can coexist. This is the case only if you configure gnustep-make with the option -disable-flattened. It is recommended that this option is used with the GNUstep filesystem layout; and that the GNUstep environment is set up by sourcing the GNUstep.sh file. . /usr/GNUstep/System/Library/Makefiles/GNUstep.sh (change the path to be the path to your GNUstep.sh file on disk. Common cases include /usr/GNUstep/System/Library/Libraries/Makefiles and /usr/local/share/GNUstep/Makefiles) You can run this command in your shell every time, or you may want to add the command to your shell startup scripts - either the ones for your own user (for example, '.bash_profile' for Bash) or the ones for the whole system (for example, '/etc/profile' on GNU/Linux). Please note that you need to execute this command both to build software using gnustep-make and to run software installed by gnustep-make. 1.5 Setting up your GNUstep User domain ======================================= (Advanced configuration) The USER domain is generally expected to be in your home directory; you can use the USER domain to install programs or libraries in your home directory without affecting other users. If you want to access programs or libraries installed in your USER domain, then you really need to source GNUstep.sh in all cases (both flattened and non-flattened), as explained in the Non-Flattened section. If you want to change the filesystem layout of your USER domain (without reinstalling gnustep-make or affecting other people's USER domains), you can do so at runtime by creating a file called ~/.GNUstep.conf (this might have a different name if your filesystem layout specifies otherwise). In that file, you can set all the GNUSTEP_USER_* variables set in GNUstep.conf. Check your GNUstep.conf for a full description. Here is an example in which all the GNUstep domain is moved into ~/Test/GNUstep instead of ~/GNUstep: GNUSTEP_USER_DIR=Test/GNUstep 1.6 Having multiple gnustep-makes installed at the same time ============================================================ (Advanced configuration) You can install gnustep-make multiple times in different directories by using a different config file for each. But if you do, then you must make sure that you can easily switch the operating system paths from one installation to the other. An easy way to do this is to configure your GNUstep by using GNUstep.sh as explained in the non-flattened instructions. Your default gnustep-make installation is the one described in the default GNUstep.conf file for the system; on GNU/Linux this is '/etc/GNUstep/GNUstep.conf'. You can create a second one that uses a different config file; for example: ./configure --prefix=/opt/mytest --with-config-file=/etc/GNUstep-mytest.conf --with-layout=gnustep When you install, this second instance of gnustep-make will reside in '/opt/mytest', and have '/etc/GNUstep-mytest.conf' as config file. To use this second installation instead of the first one, you only need to set the GNUSTEP_CONFIG_FILE variable to point to the next config file and source GNUstep.sh: export GNUSTEP_CONFIG_FILE=/etc/GNUstep-mytest.conf . /opt/mytest/System/Library/Makefies/GNUstep.sh To stop using a GNUstep installation, reset your GNUstep environment with the GNUstep-reset.sh script and destroy the variable GNUSTEP_CONFIG_FILE - . /opt/mytest/System/Library/Makefies/GNUstep-reset.sh unset GNUSTEP_CONFIG_FILE After this, you are ready to start using a new one (by setting a new GNUSTEP_CONFIG_FILE and then sourcing the GNUstep.sh of the new one).