Commit | Line | Data |
---|---|---|
2e562f3a MV |
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. |