LibGAP
======

A C library version of the GAP kernel.

GAP (http://www.gap-system.org) is a system for computational group
theory. This repo contains a shared library version of the GAP kernel,
allowing to directly talk to GAP from C/C++ code.

Much of the group theory in SageMath (http://www.sagemath.org) is
implemented using LibGAP.


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

Runtime:
  * the GAP library (scripts in the GAP language)
  * GMP/MPIR shared library

Compile-time:
  * GMP/MPIR headers

Packaging (to run "make dist"):
  * Python
  * The Python PLY module (http://www.dabeaz.com/ply)


Packaging
=========

The current tarball can be found at

https://bitbucket.org/vbraun/libgap/downloads/libgap-x.y.z.tar.gz

  * Always use the libgap-x.y.z.tar.gz tarball (the output of "make
    dist"), and not the files in the repository. Only the former has
    its symbols transformed with the "libGAP_" prefix.

  * For the testsuite, you need to have the gap library installed
    somewhere. Configure and make libGAP with
    -DSYS_DEFAULT_PATHS=<gap_root> cflags tests, where the path is
    quoted so as to end up with quotation marks in C sources:

        $ ./configure CFLAGS='-DSYS_DEFAULT_PATHS=\"/path/to/gap\"'

    or

        $ export CFLAGS='-DSYS_DEFAULT_PATHS=\"/home/vbraun/Sage/git/local/gap/latest\"'
        $ ./configure
        $ make check

    For example, using the GAP installation in SageMath:

        $ ./configure CFLAGS='-DSYS_DEFAULT_PATHS=\"$SAGE_ROOT/local/gap/latest\"'


Hacking
=======

LibGAP aims to track upstream GAP development as close as
possible. To update LibGAP-x.y.z to a new GAP-x.y.(z+1) release, use
the following steps:

  1. Copy the previous and new GAP src directory to upstream-gap-x.y.z
     and upstream-gap-x.y.(z+1), respectively.

  2. Run scripts/generate_patch.sh, which will generate
     patches/gap-x.y.z.patch

  3. Replace the C sources in LibGAP's src with the new
     upstream-gap-x.y.(z+1):

         cp upstream/src/*.[c,h] src/

  4. Apply patches/gap-x.y.z.patch to the new src
     directory. Hopefully, there are no conflicts. Good luck!

         $ cd src && patch -p1 < ../patches/gap-x.y.z.patch

  5. Update src/Makefile.am if C sources have been added/removed.

  6. Update the version in src/libgap.map.

  7. Update the version in configure.ac and run

         $ autoreconf -fiv

  8. Run "make distcheck" (the testsuite will fail because it does not
     pass CFLAGS -- ignore that).

The tests use unescaped GAP symbols since it's easier to develop.
The test/Makefile.am dist-hook rewrites them with the libGAP_ prefix.
If you change tests make sure to update the dist-hook to also prefix
any new GAP symbols that you use in the tests.

For debugging you should probably build GAP and LibGAP with debug symbols:

    $ ./configure CFLAGS='-O0 -g3'    # standalone GAP
    $ SAGE_DEBUG=yes ./sage -f gap    # inside SageMath
    $ ./configure CFLAGS='-DSYS_DEFAULT_PATHS=\"/path/to/gap\" -O0 -g3 -DDEBUG_MASTERPOINTERS -DDEBUG_GLOBAL_BAGS -DDEBUG_FUNCTIONS_BAGS'


Usage
=====

See SageMath, and in particular $SAGE_ROOT/sage/libs/gap/, for real-world
usage of LibGAP. SageMath contains a Cython interface to LibGAP if you are
so inclined.

Talk about LibGAP:

  * Slides: https://bitbucket.org/vbraun/libgap/downloads/libGAP.pdf

  * Video: https://www.youtube.com/watch?v=0gOL0QRHkmA
