-*- mode: org -*-

Guile-SDL2 provides Guile Scheme bindings for the SDL2 C shared
library.  The bindings are written in pure Scheme by using Guile's
foreign function interface.

In addition to the SDL2 core library, bindings are also provided for
SDL2_image, SDL2_mixer, and SDL2_ttf.

* Requirements

  Guile-SDL2 currently depends on the following packages:

  - GNU Guile >= 2.0.9
  - SDL2 >= 2.0.0
  - GNU Make
  - GNU pkg-config

  The following packages enable additional features:

  - SDL2_image >= 2.0.0
  - SDL2_mixer >= 2.0.0
  - SDL2_ttf >= 2.0.0

  When building from a Git checkout, the following additional packages
  are required:

  - GNU Autoconf
  - GNU Automake
  - GNU Texinfo

* Installing

  Guile-SDL2 uses the standard GNU build system, so installation
  requires the usual incantations:

  #+BEGIN_SRC sh
    ./configure
    make
    make install
  #+END_SRC

  To turn off non-core library bindings, the following configure flags
  may be used:

  #+BEGIN_SRC sh
    ./configure --with-libsdl2-image=no \
                --with-libsdl2-mixer=no \
                --with-libsdl2-ttf=no
  #+END_SRC

  When building from a Git checkout, the following spell is necessary
  before running any of the above commands:

  #+BEGIN_SRC sh
    ./bootstrap
  #+END_SRC

  GNU Guix users may install the current development snapshot
  described in =guix.scm= with the following command:

  #+BEGIN_SRC sh
    guix package -f guix.scm
  #+END_SRC

  To configure the build properly, run the following:

  #+BEGIN_SRC sh
    ./configure --with-libsdl2-prefix=$(guix build sdl2 | tail -1) \
                --with-libsdl2-image-prefix=$(guix build sdl2-image | tail -1) \
                --with-libsdl2-ttf-prefix=$(guix build sdl2-ttf | tail -1) \
                --with-libsdl2-mixer-prefix=$(guix build sdl2-mixer | tail -1)
  #+END_SRC

* Usage

  Guile-SDL2 provides modules in the =(sdl2 ...)= namespace, roughly
  organized how the SDL2 C header files are organized.  See the
  =examples= directory for practical examples.

  Low-level bindings are available in the =(sdl2 bindings ...)=
  namespace, but these are not recommended for normal usage.

  Additionally, SDL2 extension library bindings are available in the
  following modules:

  - SDL2_image: =(sdl2 image)=
  - SDL2_mixer: =(sdl2 mixer)=
  - SDL2_ttf: =(sdl2 ttf)=

  See the =examples= directory for code samples.

* Developing

  To build the source code from a Git checkout, run the following:

  #+BEGIN_SRC sh
    ./bootstrap
    ./configure
    make
  #+END_SRC

  To start a Guile REPL with a pre-configured load path for using
  guile-sdl2, use the =pre-inst-env= script:

  #+BEGIN_SRC sh
    ./pre-inst-env guile
  #+END_SRC

  GNU Guix users may create a development environment with all of the
  necessary dependencies by running the following command:

  #+BEGIN_SRC sh
    guix environment -l guix.scm
  #+END_SRC

  In order to configure the proper library locations for Guix-based
  builds, the configure script should be invoked like so:

  #+BEGIN_SRC sh
    ./configure --with-libsdl2-prefix=$(guix build sdl2) \
                --with-libsdl2-image-prefix=$(guix build sdl2-image) \
                --with-libsdl2-ttf-prefix=$(guix build sdl2-ttf) \
                --with-libsdl2-mixer-prefix=$(guix build sdl2-mixer)
  #+END_SRC

* Contact

  Bug reports and patches may be sent to <davet@gnu.org>.

  The maintainer of this library hangs out in the #guile channel on
  irc.libera.chat, so help and general discussion may also be found
  there.