mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-04-30 03:40:34 +02:00
Code Activity

* README: merge information from INSTALL and remove at least some

Browse source 
of the stale bits.
This commit is contained in:
Rob Browning 2003-03-25 23:46:04 +00:00
parent bac0f89f0c
commit d165aa1542
1 changed files with 274 additions and 96 deletions
Download patch file Download diff file Expand all files Collapse all files

370
README
View file

@ -18,6 +18,277 @@ The next stable release will be version 1.8.0.
Please send bug reports to bug-guile@gnu.org.
See the LICENSE file for the specific terms that apply to Guile.
Additional INSTALL instructions ===========================================
Generic instructions for configuring and compiling Guile can be found
in the INSTALL file. Guile specific information and configure options
can be found below, including instructions for installing SLIB.
Guile can use a number of external packages such as `readline' when
they are available. Guile expects to be able to find these packages
in the default compiler setup, it does not try to make any special
arrangements itself. For example, for the `readline' package, Guile
expects to be able to find the include file <readline/readline.h>,
without passing any special `-I' options to the compiler.
If you installed an external package, and you used the --prefix
installation option to install it somewhere else than /usr/local, you
must arrange for your compiler to find it by default. If that
compiler is gcc, one convenient way of making such arrangements is to
use the --with-local-prefix option during installation, naming the
same directory as you used in the --prefix option of the package. In
particular, it is not good enough to use the same --prefix option when
you install gcc and the package; you need to use the
--with-local-prefix option as well. See the gcc documentation for
more details.
Special Instructions For Some Systems =====================================
We would like Guile to build on all systems using the simple
instructions above, but it seems that a few systems still need special
treatment. If you can send us fixes for these problems, we'd be
grateful.
SunOS 4.1: Guile's shared library support seems to be confused, but
hey; shared libraries are confusing. You may need to configure
Guile with a command like:
./configure --disable-shared
For more information on `--disable-shared', see below, "Flags
Accepted by Configure".
HP/UX: GCC 2.7.2 (and maybe other versions) have trouble creating
shared libraries if they depend on any non-shared libraries. GCC
seems to have other problems as well. To work around this, we
suggest you configure Guile to use the system's C compiler:
CC=cc ./configure
NetBSD: Perry Metzger says, "Guile will build under NetBSD only using
gmake -- the native make will not work. (gmake is in our package
system, so this will not be a problem when we packagize 1.3.)"
Guile specific flags Accepted by Configure =================================
If you run the configure script with no arguments, it should examine
your system and set things up appropriately. However, there are a few
switches specific to Guile you may find useful in some circumstances.
--with-threads --- Build with thread support
Build a Guile executable and library that supports cooperative
threading. If you use this switch, Guile will also build and
install the QuickThreads non-preemptive threading library,
libqthreads, which you will need to link into your programs after
libguile. When you use `guile-config', you will pick up all
neccessary linker flags automatically.
Cooperative threads are not yet thoroughly tested; once they are,
they will be enabled by default. The interaction with blocking I/O
is pretty ad hoc at the moment. In our experience, bugs in the
thread support do not affect you if you don't actually use threads.
--with-modules --- Specify statically linked `modules'
Guile can dynamically load `plugin modules' during runtime, using
facilities provided by libtool. Not all platforms support this,
however. On these platforms, you can statically link the plugin
modules into libguile when Guile itself is built. XXX - how does
one specify the modules?
--enable-deprecated=LEVEL
Guile may contain features that are `deprecated'. When a feature is
deprecated, it means that it is still there and fully functional,
but that there is a better way of achieving the same thing, and we'd
rather have you use this better way. This allows us to eventually
remove the old implementation and helps to keep Guile reasonably
clean of historic baggage.
See the file NEWS for a list of features that are currently
deprecated. Each entry will also tell you what you should replace
your code with.
To give you some help with this process, and to encourage (OK,
nudge) people to switch to the newer methods, Guile can emit
warnings or errors when you use a deprecated feature. There is
quite a range of possibilities, from being completely silent to
giving errors at link time. What exactly happens is determined both
by the value of the `--enable-deprecated' configuration option when
Guile was built, and by the GUILE_WARN_DEPRECATED environment
variable.
It works like this:
When Guile has been configured with `--enable-deprecated=no' (or,
equivalently, with `--disable-deprecated') then all deprecated
features are omitted from Guile. You will get "undefined
reference", "variable unbound" or similar errors when you try to
use them.
When `--enable-deprecated=LEVEL' has been specified (for LEVEL not
"no"), LEVEL will be used as the default value of the environment
variable GUILE_WARN_DEPRECATED. A value of "yes" is changed to
"summary" and "shutup" is changed to "no", however.
When GUILE_WARN_DEPRECATED has the value "no", nothing special
will happen when a deprecated feature is used.
When GUILE_WARN_DEPRECATED has the value "summary", and a
deprecated feature has been used, Guile will print this message at
exit:
Some deprecated features have been used. Set the environment
variable GUILE_WARN_DEPRECATED to "detailed" and rerun the
program to get more information. Set it to "no" to suppress
this message.
When GUILE_WARN_DEPRECATED has the value "detailed", a detailed
warning is emitted immediatly for the first use of a deprecated
feature.
The default is `--enable-deprecated=yes'.
--disable-shared --- Do not build shared libraries.
--disable-static --- Do not build static libraries.
Normally, both static and shared libraries will be built if your
system supports them.
--enable-debug-freelist --- Enable freelist debugging.
This enables a debugging version of SCM_NEWCELL(), and also
registers an extra primitive, the setter
`gc-set-debug-check-freelist!'.
Configure with the --enable-debug-freelist option to enable the
gc-set-debug-check-freelist! primitive, and then use:
(gc-set-debug-check-freelist! #t) # turn on checking of the freelist
(gc-set-debug-check-freelist! #f) # turn off checking
Checking of the freelist forces a traversal of the freelist and a
garbage collection before each allocation of a cell. This can slow
down the interpreter dramatically, so the setter should be used to
turn on this extra processing only when necessary.
--enable-debug-malloc --- Enable malloc debugging.
Include code for debugging of calls to scm_must_malloc/realloc/free.
Checks that
1. objects freed by scm_must_free has been mallocated by scm_must_malloc
2. objects reallocated by scm_must_realloc has been allocated by
scm_must_malloc
3. reallocated objects are reallocated with the same what string
But, most importantly, it records the number of allocated objects of
each kind. This is useful when searching for memory leaks.
A Guile compiled with this option provides the primitive
`malloc-stats' which returns an alist with pairs of kind and the
number of objects of that kind.
--enable-guile-debug --- Include internal debugging functions
--disable-arrays --- omit array and uniform array support
--disable-posix --- omit posix interfaces
--disable-networking --- omit networking interfaces
--disable-regex --- omit regular expression interfaces
Cross building Guile =====================================================
As of guile-1.5.x, the build process uses compiled C files for
snarfing, and (indirectly, through libtool) for linking, and uses the
guile executable for generating documentation.
When cross building guile, you first need to configure, build and
install guile for your build host.
Then, you may configure guile for cross building, eg:
./configure --host=i686-pc-cygwin --disable-shared
Two special options for cross building are available:
--with-cc-for-build --- native C compiler, to be used during build
defaults to: `PATH=/usr/bin:$PATH cc'
--with-guile-for-build --- native Guile executable, to be used during build
defaults to: `guile', assuming you just
installed this guile natively.
Using Guile Without Installing It =========================================
If you want to run Guile without installing it, set the environment
variable `GUILE_LOAD_PATH' to a colon-separated list of directories,
including the directory containing this INSTALL file. If you used a
separate build directory, you'll need to include the build directory
in the path as well.
For example, suppose the Guile distribution unpacked into a directory
called `/home/jimb/guile-snap' (so the full name of this INSTALL file
would be `/home/jimb/guile-snap/INSTALL'). Then you might say, if
you're using Bash or any other Bourne shell variant,
export GUILE_LOAD_PATH=/home/jimb/guile-snap
or if you're using CSH or one of its variants:
setenv GUILE_LOAD_PATH /home/jimb/guile-snap
You will additionally need to set your `LTDL_LIBRARY_PATH' environment
variable to the directory in which the compiled SRFI support modules
are created if you want to use the modules for SRFI-4, SRFI-13 or
SRFI-14 support. Similar to the example above, this will be,
export LTDL_LIBRARY_PATH=/home/jimb/guile-snap/srfi/.libs
or if you're using CSH or one of its variants:
setenv LTDL_LIBRARY_PATH /home/jimb/guile-snap/srfi/.libs
Installing SLIB ===========================================================
In order to use SLIB from Guile you basically only need to put the
`slib' directory _in_ one of the directories on Guile's load path.
The standard installation is:
1. Obtain slib from http://www-swiss.ai.mit.edu/~jaffer/SLIB.html
2. Put it in Guile's data directory, that is the directory printed when
you type
guile-config info pkgdatadir
at the shell prompt. This is normally `/usr/local/share/guile', so the
directory will normally have full path `/usr/local/share/guile/slib'.
3. Start guile as a user with write access to the data directory and type
(use-modules (ice-9 slib))
at the Guile prompt. This will generate the slibcat catalog next to
the slib directory.
SLIB's `require' is provided by the Guile module (ice-9 slib).
Example:
(use-modules (ice-9 slib))
(require 'primes)
(prime? 7)
Guile Documentation ==================================================
The doc directory contains a few articles on specific topics and some
@ -42,106 +313,13 @@ The Guile WWW page is at
It contains a link to the Guile FAQ.
Guile License ==================================================
The license of Guile consists of the GNU GPL plus a special statement
giving blanket permission to link with non-free software. This is the
license statement as found in any individual file that it applies to:
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this software; see the file COPYING. If not, write to
the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
Boston, MA 02111-1307 USA
As a special exception, the Free Software Foundation gives permission
for additional uses of the text contained in its release of GUILE.
The exception is that, if you link the GUILE library with other files
to produce an executable, this does not by itself cause the
resulting executable to be covered by the GNU General Public License.
Your use of that executable is in no way restricted on account of
linking the GUILE library code into it.
This exception does not however invalidate any other reasons why
the executable file might be covered by the GNU General Public License.
This exception applies only to the code released by the
Free Software Foundation under the name GUILE. If you copy
code from other Free Software Foundation releases into a copy of
GUILE, as the General Public License permits, the exception does
not apply to the code that you add in this way. To avoid misleading
anyone as to the status of such modified files, you must delete
this exception notice from them.
If you write modifications of your own for GUILE, it is your choice
whether to permit this exception to apply to your modifications.
If you do not wish that, delete this exception notice.
Handling of Deprecated Features ======================================
Guile may contain features that are `deprecated'. When a feature is
deprecated, it means that it is still there and fully functional, but
that there is a better way of achieving the same thing, and we'd
rather have you use this better way. This allows us to eventually
remove the old implementation and helps to keep Guile reasonably clean
of historic baggage.
See the file NEWS for a list of features that are currently
deprecated. Each entry will also tell you what you should replace
your code with.
To give you some help with this process, and to encourage (OK, nudge)
people to switch to the newer methods, Guile can emit warnings or
errors when you use a deprecated feature. There is quite a range of
possibilities, from being completely silent to giving errors at link
time. What exactly happens is determined both by the value of the
`--enable-deprecated' configuration option when Guile was built, and
by the GUILE_WARN_DEPRECATED environment variable.
It works like this:
When Guile has been configured with `--enable-deprecated=no' (or,
equivalently, with `--disable-deprecated') then all deprecated
features are omitted from Guile. You will get "undefined
reference", "variable unbound" or similar errors when you try to use
them.
When `--enable-deprecated=LEVEL' has been specified (for LEVEL not
"no"), LEVEL will be used as the default value of the environment
variable GUILE_WARN_DEPRECATED. A value of "yes" is changed to
"summary" and "shutup" is changed to "no", however.
When GUILE_WARN_DEPRECATED has the value "no", nothing special will
happen when a deprecated feature is used.
When GUILE_WARN_DEPRECATED has the value "summary", and a deprecated
feature has been used, Guile will print this message at exit:
Some deprecated features have been used. Set the environment
variable GUILE_WARN_DEPRECATED to "detailed" and rerun the program
to get more information. Set it to "no" to suppress this message.
When GUILE_WARN_DEPRECATED has the value "detailed", a detailed
warning is emitted immediatly for the first use of a deprecated
feature.
The default is `--enable-deprecated=yes'.
About This Distribution ==============================================
Interesting files include:
- INSTALL, which contains instructions on building and installing Guile.
- LICENSE, which contains the exact terms of the Guile license.
- COPYING, which contains the terms of the GNU General Public License.
- INSTALL, which contains general instructions for building/installing Guile.
- NEWS, which describes user-visible changes since the last release of Guile.
Files are usually installed according to the prefix specified to