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