Welcome! (or "☡ Guile ∘ SDL ∞")
===============================

	Guile-SDL is a set of modules that provide bindings for various
	Simple DirectMedia Layer (https://www.libsdl.org) libraries.

	Most of the SDL functions are wrapped, with the exception of a
	few functions that are too C-centric.  The SDL threads, audio
	and network functions are not included.  However, there are
	(optionally configured) bindings for SDL_mixer and SDL_ttf.

	Also included is SDL_gfx 2.0.22 (by Andreas Schiffler) source
	code (LGPL 2.1) and bindings for it.

	This is alpha code (pre 1.0 release), tested with various,
	but not all, versions of Guile and SDL.  It may have bugs,
	and the interfaces may change from version to version.


Requirements
============

	* Guile 1.4 or later
	* SDL 1.2
	* SDL_image
	* SDL_mixer (optional)
	* SDL_ttf (optional)


Installation Process
====================

	See file INSTALL for generic installation instructions.
	Briefly:

	  ./configure [--disable-{mixer,ttf,embedded-gfx}]
	  make
	  make check [options]
	  make install
	  make installcheck [options]

	By default, configuration tries to find the libSDL_mixer and
	libSDL_ttf libs and headers to build modules (sdl mixer) and
	(sdl ttf), respectively.  If they are not found, these modules
	will not be installed.

	Also by default, Guile-SDL embeds SDL_gfx in module (sdl gfx).
	To use the system SDL_gfx (which is then loaded at run time),
	use configure option ‘--disable-embedded-gfx’, and ignore the
	following paragraph re ‘IMFI_CFLAGS’ (but see ‘NOMMX=1’ below).

	If your cpu supports MMX but your compiler mishandles the
	assembly in the imagefilter functions (causing a segfault),
	you can use env var ‘IMFI_CFLAGS’ to try to work around the
	problem for that particular compilation unit.  For example:

	  ./configure CFLAGS='-g -O3' IMFI_CFLAGS='-O1'

	arranges to pass ‘-g -O3 -O1’ to the compiler, which should
	set the optimization level to one (later option overrides).
	This var is marked special and is automatically re-supplied
	in config.status invocations.

	Note: The output of "./configure --help" mentions the option
	‘--disable-sdltest’.  However, that is an artifact of SDL's
	autoconf support, and is silently ignored.

	Note (Guile 2): Guile-SDL build, test and use is done strictly
	w/ ‘GUILE_AUTO_COMPILE=0’ in the environment.  If there are
	build problems, try that first (w/ a freshly unpacked tarball).


Options for "make check"
========================

	Several options influence what "make check" does:
	 - INTERACTIVE=1
	 - VERBOSE=1
	 - DEBUG=1
	 - NOMMX=1
 	 - OGGPLAYER=COMMAND
	These can be specified on the command-line, or by modifying
	the environment and arranging for make(1) to honor env vars.

	By default, "make check" and "make installcheck" run only tests
	which do not require user interaction.  You can specify
	‘INTERACTIVE=1’ to enable running these particular tests.  If
	there are problems, add ‘DEBUG=1 VERBOSE=1’ and send the output
	to the maintainer along w/ a precise description of observations
	and expectations (i.e. file a bug report).

	If the gfx test segfaults, try running it with ‘NOMMX=1’.
	(But, it could be a compiler problem, see ‘IMFI_CFLAGS’ above.)

	The mixer test additionally honors ‘OGGPLAYER=COMMAND’, in that
	case interrupting the normal playback part of the way through and
	restarting it by synchronously invoking COMMAND with one arg, the
	name of the Ogg-Vorbis file to play (test/background.ogg).  For
	example:

	 cd test
	 echo 'echo 0.8 0.9 1000 0.3 1800 0.25' > bgfx
	 make check INTERACTIVE=1 OGGPLAYER='play --effects-file bgfx'

	uses play(1) (from https://sourceforge.net/projects/sox) for the
	mixer test's nefarious purposes...


Installation Result
===================

	Doing "make install" copies six modules (four machine-dependent
	shared object libraries and two human-readable text), and the
	documentation (info format file) to various directories under
	${prefix} and ${exec_prefix}, with the result being that the
	following modules are available:

	  (sdl sdl)
	  (sdl mixer)
	  (sdl ttf)
	  (sdl gfx)
	  (sdl misc-utils)
	  (sdl simple)

	See the output of ‘./configure --help’ for information on how to
	customize the installation directories.

	Additionally, if you have "guile-tools make-module-catalog",
	that program is run in the "site directory" to create and/or
	update the module catalog there.


Reporting Bugs
==============

	Please report bugs; ‘./configure --help’ tells where.
	Alternatively, you can file a report on Savannah.
