| 1 | Guile Installation Guide |
| 2 | Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc. |
| 3 | |
| 4 | Permission is granted to anyone to make or distribute verbatim copies |
| 5 | of this document as received, in any medium, provided that the |
| 6 | copyright notice and permission notice are preserved, |
| 7 | and that the distributor grants the recipient permission |
| 8 | for further redistribution as permitted by this notice. |
| 9 | |
| 10 | Permission is granted to distribute modified versions |
| 11 | of this document, or of portions of it, |
| 12 | under the above conditions, provided also that they |
| 13 | carry prominent notices stating who last changed them, |
| 14 | and that any new or changed statements about the activities |
| 15 | of the Free Software Foundation are approved by the Foundation. |
| 16 | |
| 17 | |
| 18 | Brief Installation Instructions =========================================== |
| 19 | |
| 20 | To build Guile on unix, there are two basic steps: |
| 21 | |
| 22 | 1. Type "./configure", to configure the package for your system. |
| 23 | 2. Type "make", to build the package. |
| 24 | |
| 25 | Generic instructions for configuring and compiling GNU distributions |
| 26 | are included below. (For instructions how to install SLIB, the scheme |
| 27 | procedure library, see below.) |
| 28 | |
| 29 | |
| 30 | Guile can use a number of external packages such as `readline' when |
| 31 | they are available. Guile expects to be able to find these packages |
| 32 | in the default compiler setup, it does not try to make any special |
| 33 | arrangements itself. For example, for the `readline' package, Guile |
| 34 | expects to be able to find the include file <readline/readline.h>, |
| 35 | without passing any special `-I' options to the compiler. |
| 36 | |
| 37 | If you installed an external package, and you used the --prefix |
| 38 | installation option to install it somewhere else than /usr/local, you |
| 39 | must arrange for your compiler to find it by default. If that |
| 40 | compiler is gcc, one convenient way of making such arrangements is to |
| 41 | use the --with-local-prefix option during installation, naming the |
| 42 | same directory as you used in the --prefix option of the package. In |
| 43 | particular, it is not good enough to use the same --prefix option when |
| 44 | you install gcc and the package; you need to use the |
| 45 | --with-local-prefix option as well. See the gcc documentation for |
| 46 | more details. |
| 47 | |
| 48 | |
| 49 | Special Instructions For Some Systems ===================================== |
| 50 | |
| 51 | We would like Guile to build on all systems using the simple |
| 52 | instructions above, but it seems that a few systems still need special |
| 53 | treatment. If you can send us fixes for these problems, we'd be |
| 54 | grateful. |
| 55 | |
| 56 | SunOS 4.1: Guile's shared library support seems to be confused, but |
| 57 | hey; shared libraries are confusing. You may need to configure |
| 58 | Guile with a command like: |
| 59 | ./configure --disable-shared |
| 60 | For more information on `--disable-shared', see below, "Flags |
| 61 | Accepted by Configure". |
| 62 | |
| 63 | HP/UX: GCC 2.7.2 (and maybe other versions) have trouble creating |
| 64 | shared libraries if they depend on any non-shared libraries. GCC |
| 65 | seems to have other problems as well. To work around this, we |
| 66 | suggest you configure Guile to use the system's C compiler: |
| 67 | CC=cc ./configure |
| 68 | |
| 69 | NetBSD: Perry Metzger says, "Guile will build under NetBSD only using |
| 70 | gmake -- the native make will not work. (gmake is in our package |
| 71 | system, so this will not be a problem when we packagize 1.3.)" |
| 72 | |
| 73 | |
| 74 | Flags Accepted by Configure =============================================== |
| 75 | |
| 76 | If you run the configure script with no arguments, it should examine |
| 77 | your system and set things up appropriately. However, there are a few |
| 78 | switches specific to Guile you may find useful in some circumstances. |
| 79 | |
| 80 | |
| 81 | --enable-maintainer-mode |
| 82 | |
| 83 | If you have automake, autoconf, and libtool installed on your |
| 84 | system, this switch causes configure to generate Makefiles which |
| 85 | know how to automatically regenerate configure scripts, makefiles, |
| 86 | and headers, when they are out of date. The HACKING file says which |
| 87 | versions of those tools you will need. |
| 88 | |
| 89 | |
| 90 | --with-threads --- Build with thread support |
| 91 | |
| 92 | Build a Guile executable and library that supports cooperative |
| 93 | threading. If you use this switch, Guile will also build and |
| 94 | install the QuickThreads non-preemptive threading library, |
| 95 | libqthreads, which you will need to link into your programs after |
| 96 | libguile. When you use `guile-config', you will pick up all |
| 97 | neccessary linker flags automatically. |
| 98 | |
| 99 | Cooperative threads are not yet thoroughly tested; once they are, |
| 100 | they will be enabled by default. The interaction with blocking I/O |
| 101 | is pretty ad hoc at the moment. In our experience, bugs in the |
| 102 | thread support do not affect you if you don't actually use threads. |
| 103 | |
| 104 | |
| 105 | --disable-linuxthreads --- Disable pthread compatability hack on Linux |
| 106 | |
| 107 | If you experience problems on GNU/Linux that are related to |
| 108 | pthreads, you might try this option. Guile with then not link with |
| 109 | the pthreads library, but will also not try to be compatible to |
| 110 | programs that use both libguile and libpthread. |
| 111 | |
| 112 | |
| 113 | --with-modules --- Specify statically linked `modules' |
| 114 | |
| 115 | Guile can dynamically load `plugin modules' during runtime, using |
| 116 | facilities provided by libtool. Not all platforms support this, |
| 117 | however. On these platforms, you can statically link the plugin |
| 118 | modules into libguile when Guile itself is build. XXX - how does |
| 119 | one specify the modules? |
| 120 | |
| 121 | |
| 122 | --enable-deprecated=LEVEL --- Control the inclusion of deprecated features. |
| 123 | |
| 124 | You can select between different behaviours via the LEVEL argument: |
| 125 | a value of "no" will omit all deprecated features and you will get |
| 126 | "undefined reference", "variable unbound" or similar errors when you |
| 127 | try to use them. All other values will include all deprecated |
| 128 | features. The LEVEL argument is used to determine the default value |
| 129 | for the environment variable GUILE_WARN_DEPRECATED. See the README |
| 130 | for more information. |
| 131 | |
| 132 | The default is to get a vague warning at program exit if deprecated |
| 133 | features were used: |
| 134 | |
| 135 | --enable-deprecated=yes |
| 136 | --enable-deprecated=summary |
| 137 | |
| 138 | To get a detailed warning at first use of a deprecated feature: |
| 139 | |
| 140 | --enable-deprecated=detailed |
| 141 | |
| 142 | To get no warnings: |
| 143 | |
| 144 | --enable-deprecated=shutup |
| 145 | |
| 146 | To omit deprecated features completely and irrevokably: |
| 147 | |
| 148 | --enable-deprecated=no |
| 149 | |
| 150 | |
| 151 | --disable-shared --- Do not build shared libraries. |
| 152 | --disable-static --- Do not build static libraries. |
| 153 | |
| 154 | Normally, both static and shared libraries will be built if your |
| 155 | system supports them. |
| 156 | |
| 157 | |
| 158 | --enable-debug-freelist --- Enable freelist debugging. |
| 159 | |
| 160 | This enables a debugging version of SCM_NEWCELL(), and also |
| 161 | registers an extra primitive, the setter |
| 162 | `gc-set-debug-check-freelist!'. |
| 163 | |
| 164 | Configure with the --enable-debug-freelist option to enable the |
| 165 | gc-set-debug-check-freelist! primitive, and then use: |
| 166 | |
| 167 | (gc-set-debug-check-freelist! #t) # turn on checking of the freelist |
| 168 | (gc-set-debug-check-freelist! #f) # turn off checking |
| 169 | |
| 170 | Checking of the freelist forces a traversal of the freelist and a |
| 171 | garbage collection before each allocation of a cell. This can slow |
| 172 | down the interpreter dramatically, so the setter should be used to |
| 173 | turn on this extra processing only when necessary. |
| 174 | |
| 175 | |
| 176 | --enable-debug-malloc --- Enable malloc debugging. |
| 177 | |
| 178 | Include code for debugging of calls to scm_must_malloc/realloc/free. |
| 179 | |
| 180 | Checks that |
| 181 | |
| 182 | 1. objects freed by scm_must_free has been mallocated by scm_must_malloc |
| 183 | 2. objects reallocated by scm_must_realloc has been allocated by |
| 184 | scm_must_malloc |
| 185 | 3. reallocated objects are reallocated with the same what string |
| 186 | |
| 187 | But, most importantly, it records the number of allocated objects of |
| 188 | each kind. This is useful when searching for memory leaks. |
| 189 | |
| 190 | A Guile compiled with this option provides the primitive |
| 191 | `malloc-stats' which returns an alist with pairs of kind and the |
| 192 | number of objects of that kind. |
| 193 | |
| 194 | |
| 195 | --enable-guile-debug --- Include internal debugging functions |
| 196 | --disable-arrays --- omit array and uniform array support |
| 197 | --disable-posix --- omit posix interfaces |
| 198 | --disable-networking --- omit networking interfaces |
| 199 | --disable-regex --- omit regular expression interfaces |
| 200 | |
| 201 | |
| 202 | Cross building Guile ===================================================== |
| 203 | |
| 204 | As of guile-1.5.x, the build process uses compiled C files for |
| 205 | snarfing, and (indirectly, through libtool) for linking, and uses the |
| 206 | guile executable for generating documentation. |
| 207 | |
| 208 | When cross building guile, you first need to configure, build and |
| 209 | install guile for your build host. |
| 210 | |
| 211 | Then, you may configure guile for cross building, eg: |
| 212 | |
| 213 | ./configure --host=i686-pc-cygwin --disable-shared |
| 214 | |
| 215 | Two special options for cross building are available: |
| 216 | |
| 217 | --with-cc-for-build --- native C compiler, to be used during build |
| 218 | defaults to: `PATH=/usr/bin:$PATH cc' |
| 219 | |
| 220 | --with-guile-for-build --- native Guile executable, to be used during build |
| 221 | defaults to: `guile', assuming you just |
| 222 | installed this guile natively. |
| 223 | |
| 224 | |
| 225 | Using Guile Without Installing It ========================================= |
| 226 | |
| 227 | If you want to run Guile without installing it, set the environment |
| 228 | variable `GUILE_LOAD_PATH' to a colon-separated list of directories, |
| 229 | including the directory containing this INSTALL file. If you used a |
| 230 | separate build directory, you'll need to include the build directory |
| 231 | in the path as well. |
| 232 | |
| 233 | For example, suppose the Guile distribution unpacked into a directory |
| 234 | called `/home/jimb/guile-snap' (so the full name of this INSTALL file |
| 235 | would be `/home/jimb/guile-snap/INSTALL'). Then you might say, if |
| 236 | you're using Bash or any other Bourne shell variant, |
| 237 | |
| 238 | export GUILE_LOAD_PATH=/home/jimb/guile-snap |
| 239 | |
| 240 | or if you're using CSH or one of its variants: |
| 241 | |
| 242 | setenv GUILE_LOAD_PATH /home/jimb/guile-snap |
| 243 | |
| 244 | You will additionally need to set your `LTDL_LIBRARY_PATH' environment |
| 245 | variable to the directory in which the compiled SRFI support modules |
| 246 | are created if you want to use the modules for SRFI-4, SRFI-13 or |
| 247 | SRFI-14 support. Similar to the example above, this will be, |
| 248 | |
| 249 | export LTDL_LIBRARY_PATH=/home/jimb/guile-snap/srfi/.libs |
| 250 | |
| 251 | or if you're using CSH or one of its variants: |
| 252 | |
| 253 | setenv LTDL_LIBRARY_PATH /home/jimb/guile-snap/srfi/.libs |
| 254 | |
| 255 | |
| 256 | Installing SLIB =========================================================== |
| 257 | |
| 258 | In order to use SLIB from Guile you basically only need to put the |
| 259 | `slib' directory _in_ one of the directories on Guile's load path. |
| 260 | |
| 261 | The standard installation is: |
| 262 | |
| 263 | 1. Obtain slib from http://www-swiss.ai.mit.edu/~jaffer/SLIB.html |
| 264 | |
| 265 | 2. Put it in Guile's data directory, that is the directory printed when |
| 266 | you type |
| 267 | |
| 268 | guile-config info pkgdatadir |
| 269 | |
| 270 | at the shell prompt. This is normally `/usr/local/share/guile', so the |
| 271 | directory will normally have full path `/usr/local/share/guile/slib'. |
| 272 | |
| 273 | 3. Start guile as a user with write access to the data directory and type |
| 274 | |
| 275 | (use-modules (ice-9 slib)) |
| 276 | |
| 277 | at the Guile prompt. This will generate the slibcat catalog next to |
| 278 | the slib directory. |
| 279 | |
| 280 | SLIB's `require' is provided by the Guile module (ice-9 slib). |
| 281 | |
| 282 | Example: |
| 283 | |
| 284 | (use-modules (ice-9 slib)) |
| 285 | (require 'primes) |
| 286 | (prime? 7) |
| 287 | |
| 288 | |
| 289 | Generic Instructions for Building Auto-Configured Packages ================ |
| 290 | |
| 291 | The `configure' shell script attempts to guess correct values for |
| 292 | various system-dependent variables used during compilation. It uses |
| 293 | those values to create a `Makefile' in each directory of the package. |
| 294 | It may also create one or more `.h' files containing system-dependent |
| 295 | definitions. Finally, it creates a shell script `config.status' that |
| 296 | you can run in the future to recreate the current configuration, a file |
| 297 | `config.cache' that saves the results of its tests to speed up |
| 298 | reconfiguring, and a file `config.log' containing compiler output |
| 299 | (useful mainly for debugging `configure'). |
| 300 | |
| 301 | If you need to do unusual things to compile the package, please try |
| 302 | to figure out how `configure' could check whether to do them, and mail |
| 303 | diffs or instructions to the address given in the `README' so they can |
| 304 | be considered for the next release. If at some point `config.cache' |
| 305 | contains results you don't want to keep, you may remove or edit it. |
| 306 | |
| 307 | The file `configure.in' is used to create `configure' by a program |
| 308 | called `autoconf'. You only need `configure.in' if you want to change |
| 309 | it or regenerate `configure' using a newer version of `autoconf'. |
| 310 | |
| 311 | The simplest way to compile this package is: |
| 312 | |
| 313 | 1. `cd' to the directory containing the package's source code and type |
| 314 | `./configure' to configure the package for your system. If you're |
| 315 | using `csh' on an old version of System V, you might need to type |
| 316 | `sh ./configure' instead to prevent `csh' from trying to execute |
| 317 | `configure' itself. |
| 318 | |
| 319 | Running `configure' takes awhile. While running, it prints some |
| 320 | messages telling which features it is checking for. |
| 321 | |
| 322 | 2. Type `make' to compile the package. |
| 323 | |
| 324 | 3. Optionally, type `make check' to run any self-tests that come with |
| 325 | the package. |
| 326 | |
| 327 | 4. Type `make install' to install the programs and any data files and |
| 328 | documentation. |
| 329 | |
| 330 | 5. You can remove the program binaries and object files from the |
| 331 | source code directory by typing `make clean'. To also remove the |
| 332 | files that `configure' created (so you can compile the package for |
| 333 | a different kind of computer), type `make distclean'. There is |
| 334 | also a `make maintainer-clean' target, but that is intended mainly |
| 335 | for the package's developers. If you use it, you may have to get |
| 336 | all sorts of other programs in order to regenerate files that came |
| 337 | with the distribution. |
| 338 | |
| 339 | Compilers and Options |
| 340 | ===================== |
| 341 | |
| 342 | Some systems require unusual options for compilation or linking that |
| 343 | the `configure' script does not know about. You can give `configure' |
| 344 | initial values for variables by setting them in the environment. Using |
| 345 | a Bourne-compatible shell, you can do that on the command line like |
| 346 | this: |
| 347 | CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure |
| 348 | |
| 349 | Or on systems that have the `env' program, you can do it like this: |
| 350 | env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure |
| 351 | |
| 352 | Compiling For Multiple Architectures |
| 353 | ==================================== |
| 354 | |
| 355 | You can compile the package for more than one kind of computer at the |
| 356 | same time, by placing the object files for each architecture in their |
| 357 | own directory. To do this, you must use a version of `make' that |
| 358 | supports the `VPATH' variable, such as GNU `make'. `cd' to the |
| 359 | directory where you want the object files and executables to go and run |
| 360 | the `configure' script. `configure' automatically checks for the |
| 361 | source code in the directory that `configure' is in and in `..'. |
| 362 | |
| 363 | If you have to use a `make' that does not supports the `VPATH' |
| 364 | variable, you have to compile the package for one architecture at a time |
| 365 | in the source code directory. After you have installed the package for |
| 366 | one architecture, use `make distclean' before reconfiguring for another |
| 367 | architecture. |
| 368 | |
| 369 | Installation Names |
| 370 | ================== |
| 371 | |
| 372 | By default, `make install' will install the package's files in |
| 373 | `/usr/local/bin', `/usr/local/man', etc. You can specify an |
| 374 | installation prefix other than `/usr/local' by giving `configure' the |
| 375 | option `--prefix=PATH'. |
| 376 | |
| 377 | You can specify separate installation prefixes for |
| 378 | architecture-specific files and architecture-independent files. If you |
| 379 | give `configure' the option `--exec-prefix=PATH', the package will use |
| 380 | PATH as the prefix for installing programs and libraries. |
| 381 | Documentation and other data files will still use the regular prefix. |
| 382 | |
| 383 | In addition, if you use an unusual directory layout you can give |
| 384 | options like `--bindir=PATH' to specify different values for particular |
| 385 | kinds of files. Run `configure --help' for a list of the directories |
| 386 | you can set and what kinds of files go in them. |
| 387 | |
| 388 | If the package supports it, you can cause programs to be installed |
| 389 | with an extra prefix or suffix on their names by giving `configure' the |
| 390 | option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'. |
| 391 | |
| 392 | Optional Features |
| 393 | ================= |
| 394 | |
| 395 | Some packages pay attention to `--enable-FEATURE' options to |
| 396 | `configure', where FEATURE indicates an optional part of the package. |
| 397 | They may also pay attention to `--with-PACKAGE' options, where PACKAGE |
| 398 | is something like `gnu-as' or `x' (for the X Window System). The |
| 399 | `README' should mention any `--enable-' and `--with-' options that the |
| 400 | package recognizes. |
| 401 | |
| 402 | For packages that use the X Window System, `configure' can usually |
| 403 | find the X include and library files automatically, but if it doesn't, |
| 404 | you can use the `configure' options `--x-includes=DIR' and |
| 405 | `--x-libraries=DIR' to specify their locations. |
| 406 | |
| 407 | Specifying the System Type |
| 408 | ========================== |
| 409 | |
| 410 | There may be some features `configure' can not figure out |
| 411 | automatically, but needs to determine by the type of host the package |
| 412 | will run on. Usually `configure' can figure that out, but if it prints |
| 413 | a message saying it can not guess the host type, give it the |
| 414 | `--host=TYPE' option. TYPE can either be a short name for the system |
| 415 | type, such as `sun4', or a canonical name with three fields: |
| 416 | CPU-COMPANY-SYSTEM |
| 417 | |
| 418 | See the file `config.sub' for the possible values of each field. If |
| 419 | `config.sub' isn't included in this package, then this package doesn't |
| 420 | need to know the host type. |
| 421 | |
| 422 | If you are building compiler tools for cross-compiling, you can also |
| 423 | use the `--target=TYPE' option to select the type of system they will |
| 424 | produce code for and the `--build=TYPE' option to select the type of |
| 425 | system on which you are compiling the package. |
| 426 | |
| 427 | Sharing Defaults |
| 428 | ================ |
| 429 | |
| 430 | If you want to set default values for `configure' scripts to share, |
| 431 | you can create a site shell script called `config.site' that gives |
| 432 | default values for variables like `CC', `cache_file', and `prefix'. |
| 433 | `configure' looks for `PREFIX/share/config.site' if it exists, then |
| 434 | `PREFIX/etc/config.site' if it exists. Or, you can set the |
| 435 | `CONFIG_SITE' environment variable to the location of the site script. |
| 436 | A warning: not all `configure' scripts look for a site script. |
| 437 | |
| 438 | Operation Controls |
| 439 | ================== |
| 440 | |
| 441 | `configure' recognizes the following options to control how it |
| 442 | operates. |
| 443 | |
| 444 | `--cache-file=FILE' |
| 445 | Use and save the results of the tests in FILE instead of |
| 446 | `./config.cache'. Set FILE to `/dev/null' to disable caching, for |
| 447 | debugging `configure'. |
| 448 | |
| 449 | `--help' |
| 450 | Print a summary of the options to `configure', and exit. |
| 451 | |
| 452 | `--quiet' |
| 453 | `--silent' |
| 454 | `-q' |
| 455 | Do not print messages saying which checks are being made. To |
| 456 | suppress all normal output, redirect it to `/dev/null' (any error |
| 457 | messages will still be shown). |
| 458 | |
| 459 | `--srcdir=DIR' |
| 460 | Look for the package's source code in directory DIR. Usually |
| 461 | `configure' can determine that directory automatically. |
| 462 | |
| 463 | `--version' |
| 464 | Print the version of Autoconf used to generate the `configure' |
| 465 | script, and exit. |
| 466 | |
| 467 | `configure' also accepts some other, not widely useful, options. |