1Copyright (C) 2003,2007,2008 Free Software Foundation, Inc. 2This file is free documentation; the Free Software Foundation gives 3unlimited permission to copy, distribute and modify it. 4 5 6 Prerequisites 7 8You need gcc version 2.0 or later to compile gforth. 9 10For the (documented) libcc.fs C interface you need a C compiler and 11libtool at run-time. 12 13For the (undocumented ) lib.fs C interface you need to install either 14the ffcall libraries or the libffi library. Libffi comes with recent 15gccs, ffcall can be found on 16 17 ftp://ftp.santafe.edu/pub/gnu/ffcall-1.8.tar.gz (USA) 18 ftp://ftp.ilog.fr/pub/Users/haible/gnu/ffcall-1.8.tar.gz (Europe) 19 20On many architectures (exceptions: 386, PPC, MIPS, Alpha) you need gdb 21at run-time in order for the disassembler to work. 22 23 24 Building and Installing 25 26First, type 27 28./configure 29 30(see Section Configuration Options below for details). 31 32After configuration, type 33 34make 35 36This includes a check whether your shiny new Forth system works. If 37you like to invoke the check alone, do 38 39make check 40 41You can run some benchmarks with 42 43make bench 44 45and compare them with the results in Benchres and in the manual. 46 47If everything is all right, you may want to install gforth. Type 48 49make install 50 51For paper documentation, print gforth.ps (a Postscript file (300dpi 52fonts, i.e., it works, but does not produce best quality on better 53printers)), or say 54 55make gforth.dvi 56 57and print the resulting file gforth.dvi. You can also get the 58documentation in HTML format by typing 59 60make html 61 62If you prefer plain ASCII documentation, you can 63 64make doc/gforth.txt 65 66or just concatenate the files gforth.info-* ('cat gforth.info-*' under 67Unix); the result of the latter option is a little worse. 68 69You can find binary distributions, documentation in HTML and plain 70text format and information on known installation problems at 71http://www.complang.tuwien.ac.at/forth/gforth/. 72 73 74 Configuration Options 75 76If you use GNU make, you can build in a directory different from the 77source directory by changing to the build directory and invoking 78configure thus: 79 80$srcdir/configure 81 82where $srcdir is the source directory. (Note that we tested this only 83for installation; i.e., if you want to hack the Gforth sources, you 84should probably build in the source directory). 85 86configure has the following useful parameters: 87 --prefix=PREFIX install architecture-independent files in PREFIX 88 [default: /usr/local] 89 --exec-prefix=PREFIX install architecture-dependent files in PREFIX 90 [default: same as prefix] 91 --help: tells you about other parameters. 92 93The file Benchres shows the best gforth-fast performance that we 94achieved. 95 96If you don't like the defaults for the installation directories, you 97should override them already during configure. E.g., if you want to 98install in the /gnu hierarchy instead of in the default /usr/local 99hierarchy, say 100 101./configure --prefix=/gnu 102 103Moreover, if your GCC is not called gcc (but, e.g., gcc-2.7.1), you 104should say so during configuration. E.g.: 105 106./configure CC=gcc-2.7.1 107 108You can also pass additional options to gcc in this way, e.g., if you 109want to generate an a.out executable under Linux with gcc-2.7.0: 110 111./configure CC="gcc -b i486-linuxaout -V 2.7.0" 112 113You can change the sizes of the various areas used in the default 114image `gforth.fi' by passing the appropriate Gforth command line 115options in the FORTHSIZES environment variable: 116 117./configure "FORTHSIZES=--dictionary-size=1048576 --data-stack-size=16k --fp-stack-size=16K --return-stack-size=15k --locals-stack-size=14848b" 118 119The line above reaffirms the default sizes. Note that the locals 120stack area is also used as input buffer stack. 121 122If C's "long long" do not work properly on your machine (i.e., if the 123tests involving double-cell numbers fail), you can build Gforth such 124that it does not use "long long": 125 126./configure ac_cv_sizeof_long_long=0 127 128For MacOS X on Core 2 processors, you might want to use the 64-bit 129version for increased speed (more registers available); you have to 130ask for that on configuration, as follows: 131 132./configure CC='gcc-4.2 -arch x86_64' --build=x86_64-apple-darwin9.4.0 133 134 135 Cross-Installation 136 137There is currently no simple way to do cross-installation of Gforth 138(apart from Gforth EC). The current build process interleaves 139compiling and running heavily, so multiple transfers between build and 140target machine would be required. We don't have a testing environment 141for cross-compilation, so we cannot fix this at the moment. If you 142want to do cross-installation, please contact us. 143 144In any case, you might find the following useful: 145 146You need a cross-compilation toolchain for your target including gcc 147(2.0 or later). 148 149The first step in cross-installation is the cross-configuration. A 150few tests made by the configure script do not work in a 151cross-compilation situation. You have to provide the results of these 152tests by hand. E.g., if you compile for an ARM: 153 154env skipcode=".skip 16" ac_cv_sizeof_char_p=4 ac_cv_sizeof_void_p=4 \ 155ac_cv_sizeof_char=1 ac_cv_sizeof_short=2 ac_cv_sizeof_int=4 \ 156ac_cv_sizeof_long=4 ac_cv_sizeof_long_long=8 ac_cv_sizeof_intptr_t=4 \ 157ac_cv_sizeof_int128_t=0 ac_cv_sizeof_uint128_t=0 \ 158ac_cv_c_bigendian=no ./configure CC=arm-elf-gcc --host=arm-linux 159 160The ac_cv_sizeof_... variables give the sizes of various C types; 161ac_cv_sizeof_char_p is the same as "sizeof(char*)" in C code. The 162ac_cv_c_bigendian variable gives the byte order. The skipcode 163specifies how to skip 16 bytes in the code (use "skipcode=no" to 164disable skipping and dynamic native code generation). 165 166 167 Preloading installation-specific code 168 169If you want to have some installation-specific files loaded when 170Gforth starts (e.g., an assembler for your processor), put commands 171for loading them into /usr/local/share/gforth/site-forth/siteinit.fs 172(if the commands work for all architectures) or 173/usr/local/lib/gforth/site-forth/siteinit.fs (for 174architecture-specific commands); 175/usr/local/lib/gforth/site-forth/siteinit.fs takes precedence if both 176files are present (unless you change the search path). The file names 177given above are the defaults; if you have changed the prefix, you have 178to replace "/usr/local" in these names with your prefix. 179 180By default, the installation procedure creates an empty 181/usr/local/share/gforth/site-forth/siteinit.fs if there is no such 182file. 183 184If you change the siteinit.fs file, you should run "make install" 185again for the changes to take effect (Actually, the part of "make 186install" starting with "rm gforth.fi" is sufficient). 187 188 189 Multiple Versions and Deinstallation 190 191Several versions of Gforth can be installed and used at the same 192time. Version `foo' can be invoked with `gforth-foo'. We recommend to 193keep the old version for some time after a new one has been installed. 194 195You can deinstall this version of Gforth with 'make uninstall' and 196version foo with 'make uninstall VERSION=foo'. 'make uninstall' also 197tells you how to uninstall Gforth completely. 198 199 200 Installing Info Files 201 202Info is the GNU project on-line documentation format. You can read 203info files either from within Emacs (Ctrl-h i) or using the 204stand-alone Info reader, 'info'. 205 206If you use the default install root of '/usr/local' then the info 207files will be installed in '/usr/local/info'. 208 209Many GNU/Linux distributions are set up to put all of their 210documentation in '/usr/info', in which case you might have to do a 211couple of things to get your environment set up to accommodate files 212in both areas: 213 2141. Add an INFOPATH environment variable. The easiest place to do 215this is '/etc/profile', right next to PATH and MANPATH: 216 217INFOPATH=/usr/local/info:/usr/info 218 2192. Create a file called 'dir' in 'usr/local/info'. Use the file 220'/usr/info/dir' as a template. You can add the line for gforth 221manually, or use '/sbin/install-info' (man install-info for details). 222