Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ekaitz-zarraga/guile


https://github.com/ekaitz-zarraga/guile

Last synced: 3 days ago
JSON representation

Awesome Lists containing this project

README 

        
This is version 3.0 of Guile, Project GNU's extension language library.

Guile is an implementation of the Scheme programming language, packaged

as a library that can be linked into applications to give them their own

extension language.  Guile supports other languages as well, giving

users of Guile-based applications a choice of languages.



Please send bug reports to [email protected].



See the LICENSE file for the specific terms that apply to Guile.  Note

that for any copyright year range specified as YYYY-ZZZZ in this

package, the range specifies every single year in that closed interval.



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 depends on the following external libraries.

- libgmp

- libiconv

- libintl

- libltdl

- libunistring

- libgc

- libffi

It will also use the libreadline library if it is available.



There is a corresponding `--with-XXX-prefix' option for each of these

libraries (except for libgc and libffi which use `pkg-config', see

below) that you can use when invoking ./configure, if you have these

libraries installed in a location other than the standard places (/usr

and /usr/local).



These options are provided by the Gnulib `havelib' module, and details

of how they work are documented in `Searching for Libraries' in the

Gnulib manual (http://www.gnu.org/software/gnulib/manual).  The extent

to which they work on a given OS depends on whether that OS supports

encoding full library path names in executables (aka `rpath').  Also

note that using these options, and hence hardcoding full library path

names (where that is supported), makes it impossible to later move the

built executables and libraries to an installation location other than

the one that was specified at build time.



Another possible approach is to set CPPFLAGS and LDFLAGS on the

configure command-line, so that they include -I options for all the

non-standard places where you have installed header files and -L

options for all the non-standard places where you have installed

libraries.  This will allow configure and make to find those headers

and libraries during the build.  E.g.:



  ../configure [...] CPPFLAGS='-I/my/include' LDFLAGS='-L/my/lib'



The locations found will not be hardcoded into the build executables and

libraries, so with this approach you will probably also need to set

LD_LIBRARY_PATH correspondingly, to allow Guile to find the necessary

libraries again at runtime.



Required External Packages ================================================



Guile requires the following external packages:



  - GNU MP, at least version 4.2



    GNU MP is used for bignum arithmetic.  It is available from

    http://gmplib.org/ .



  - libltdl from GNU Libtool, at least version 1.5.6



    libltdl is used for loading extensions at run-time.  It is

    available from http://www.gnu.org/software/libtool/ .



  - GNU libunistring, at least version 0.9.3



    libunistring is used for Unicode string operations, such as the

    `utf*->string' procedures.  It is available from

    http://www.gnu.org/software/libunistring/ .



  - libgc, at least version 7.2



    libgc (aka. the Boehm-Demers-Weiser garbage collector) is the

    conservative garbage collector used by Guile.  It is available

    from http://www.hboehm.info/gc/ .



  - libffi



    libffi provides a "foreign function interface", used by the

    `(system foreign)' module.  It is available from

    http://sourceware.org/libffi/ .



  - pkg-config



    Guile's ./configure script uses pkg-config to discover the correct

    compile and link options for libgc and libffi.  For this to work,

    the `PKG_CONFIG_PATH' environment variable must be set to point to

    the places where libgc's and libffi's `.pc' files can be found:



      PKG_CONFIG_PATH=/path/to/libgc/lib/pkgconfig:/path/to/libffi/lib/pkgconfig



    Alternatively, when pkg-config is not installed, you can work around

    this by setting some variables as part of the configure

    command-line:



    - PKG_CONFIG=true



    - BDW_GC_CFLAGS=



    - BDW_GC_LIBS=



    Note that because you're bypassing all pkg-config checks, you will

    also have to specify libffi flags as well:



    - LIBFFI_CFLAGS=



    - LIBFFI_LIBS=



When building from a Git checkout, these additional packages are needed:



  - GNU Autoconf

  - GNU Automake

  - GNU Libtool

  - Flex

  - GNU Gettext

  - GNU Texinfo

  - GNU Gperf



If you use GNU Guix, you can obtain a shell for development with all the

dependencies by running the following command from the top directory of

the checkout:



  guix shell



You can also build Guile by running:



  guix build -f guix.scm



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.



FreeBSD 11.0:

  For a build supporting threads, please `pkg install' the following

    - pkgconf : provides pkg-config

    - gmake : /usr/bin/make does not work

    - boehm-gc-threaded : needed for threaded support



  Configure as:



    ./configure --with-bdw-gc=bdw-gc-threaded



  Alternately if you want a Guile without threads, then install boehm-gc

  and configure as:



    ./configure --without-threads



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.



--without-threads  ---  Build without thread support



  Build a Guile executable and library that supports multi-threading.



  The default is to enable threading support when your operating

  system offers 'POSIX threads'.  When you do not want threading, use

  `--without-threads'.



--enable-deprecated=LEVEL



  Guile may contain features that are `deprecated'.  When a feature is

  deprecated, it means that it is still there, 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'.



  In addition to setting GUILE_WARN_DEPRECATED in the environment, you

  can also use (debug-enable 'warn-deprecated) and (debug-disable

  'warn-deprecated) to enable and disable the detailed messaged at run

  time.



  Additionally, if your toolchain is new enough, you will receive

  warnings at link time if you have a Guile extension that uses

  deprecated functions provided by Guile.



--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_cell and scm_double_cell,

  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_malloc, scm_realloc, etc.



  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-posix       ---  omit posix interfaces

--disable-networking  ---  omit networking interfaces

--disable-regex       ---  omit regular expression interfaces



Cross building Guile  =====================================================



As of Guile 3.0.x, the build process produces a library, libguile-3.0,

along with Guile "object files" containing bytecode to be interpreted by

Guile's virtual machine.  The bytecode format depends on the endianness

and word size of the host CPU.



Thus, when cross building Guile, you first need to configure, build and

install it for your build host.



Then, you may configure Guile for cross building:



    ./configure --host=i686-pc-cygwin --disable-shared



A C compiler for the build system is required.  If that doesn't suit it

can be specified with the CC_FOR_BUILD variable in the usual way, for

instance:



    ./configure --host=m68k-unknown-linux-gnu CC_FOR_BUILD=/my/local/gcc



Guile for the build system can be specified similarly with the

GUILE_FOR_BUILD variable, which defaults to whatever `guile' executable

is found in $PATH.  It must have the exact same version has the Guile

that you intend to cross-build.



Using Guile Without Installing It =========================================



The "meta/" subdirectory of the Guile sources contains a script called

"guile" that can be used to run the Guile that has just been built. Note

that this is not the same "guile" as the one that is installed; this

"guile" is a wrapper script that sets up the environment appropriately,

then invokes the Guile binary.



You may also build external packages against an uninstalled Guile build

tree. The "uninstalled-env" script in the "meta/" subdirectory will set

up an environment with a path including "meta/", a modified dynamic

linker path, a modified PKG_CONFIG_PATH, etc.



For example, you can enter this environment via invoking



    meta/uninstalled-env bash



Within that shell, other packages should be able to build against

uninstalled Guile.



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 Guile Reference Manual (guile.info) is the primary documentation for

Guile.  A copy of the R5RS Scheme specification is included too

(r5rs.info).



Info format versions of this documentation are installed as part of

the normal build process.  The texinfo sources are under the doc

directory, and other formats like Postscript, PDF, DVI or HTML can be

generated from them with Tex and Texinfo tools.



The doc directory also includes an example-smob subdirectory which has

the example code from the "Defining New Types (Smobs)" chapter of the

reference manual.



The Guile WWW page is at



  http://www.gnu.org/software/guile/guile.html



It contains a link to the Guile FAQ.



About This Distribution ==============================================



Interesting files include:



- LICENSE, which contains the exact terms of the Guile license.

- COPYING.LESSER, which contains the terms of the GNU Lesser General Public 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

configure, /usr/local by default.  Building and installing gives you:



Executables, in ${prefix}/bin:



 guile --- a stand-alone interpreter for Guile.  With no arguments, this

 	is a simple interactive Scheme interpreter.  It can also be used

 	as an interpreter for script files; see the NEWS file for details.

 guile-config --- a Guile script which provides the information necessary

 	to link your programs against the Guile library.

 guile-snarf --- a script to parse declarations in your C code for

 	Scheme-visible C functions, Scheme objects to be used by C code,

 	etc.



Libraries, in ${prefix}/lib.  Depending on the platform and options

        given to configure, you may get shared libraries in addition

	to or instead of these static libraries:



 libguile.a --- an object library containing the Guile interpreter,

 	You can use Guile in your own programs by linking against this.

 libguilereadline.a --- an object library containing glue code for the

        GNU readline library.



 libguile-srfi-*.a --- various SRFI support libraries



Header files, in ${prefix}/include:



 libguile.h, guile/gh.h, libguile/*.h --- for libguile.

 guile-readline/readline.h --- for guile-readline.



Support files, in ${prefix}/share/guile/:



 ice-9/* --- run-time support for Guile: the module system,

 	read-eval-print loop, some R4RS code and other infrastructure.

 oop/* --- the Guile Object-Oriented Programming System (GOOPS)

 scripts/* --- executable modules, i.e., scheme programs that can be both

 	called as an executable from the shell, and loaded and used as a

 	module from scheme code.  See scripts/README for more info.

 srfi/* --- SRFI support modules.  See srfi/README for more info.



Automake macros, in ${prefix}/share/aclocal:



 guile.m4



Documentation in Info format, in ${prefix}/info:



 guile --- Guile reference manual.



 GOOPS --- GOOPS reference manual.



 r5rs --- Revised(5) Report on the Algorithmic Language Scheme.



The Guile source tree is laid out as follows:



libguile:

	The Guile Scheme interpreter --- both the object library

	for you to link with your programs, and the executable you can run.

module: Scheme libraries included with Guile.

guile-readline:

        The glue code for using GNU readline with Guile.  This

        will be build when configure can find a recent enough readline

        library on your system.

doc:	Documentation (see above).



Git Repository Access ================================================



Guile's source code is stored in a Git repository at Savannah.  Anyone

can access it using `git-clone' from one of the following URLs:



  git://git.savannah.gnu.org/guile.git

  https://git.savannah.gnu.org/git/guile.git



Developers with a Savannah SSH account can also access it from:



  ssh://git.sv.gnu.org/srv/git/guile.git



The repository can also be browsed on-line at the following address:



  https://git.savannah.gnu.org/cgit/guile.git/



For more information on Git, please see:



  https://git-scm.com



Please send problem reports to .