GAP (Vole) - Chapter 2: Setting up Vole

If you encounter problems, or have any other feedback for the authors, then please create an issue on our issue tracker, or contact us by any other appropriate means. See the title page of this manual for our contact details. We published Vole so that our ideas and algorithms could be used by, and be useful to, others in the community. But without feedback, it can be difficult to know whether we are achieving this aim. Therefore we are keen to hear your comments, remarks, and complaints.

2.1 Dependencies

Vole requires GAP 4.11.0 or newer and various other GAP packages to run, and Rust version 1.48 or newer is required to compile Vole.

Please note that if you are using Vole via a GAP Cygwin release (i.e. if you installed GAP in Windows via an installer that included Vole), then Vole came ready-compiled, and the included versions of GAP and its packages are sufficient to run Vole out-of-the-box. Therefore you may skip straight to Section 2.3.

In order to compile Vole, Rust must be installed and available with the cargo command, in version at least 1.48. You can test for Rust by running cargo --version in the terminal. You should obtain a version number in response, such as:

$ cargo --version
cargo 1.54.0

If Rust is not available, then running the command cargo --version will give an error such as cargo: command not found. If this is the case, then please follow the instructions at https://www.rust-lang.org/tools/install or https://rustup.rs for installing Rust.

In addition, the following GAP packages must be available in order to use Vole. This means that Vole will not load if one or more of these packages cannot be loaded in your GAP installation in a new enough version.

These packages, and GAP itself, in turn have their own dependencies, and so Vole inherits these additional dependencies. If one of the above packages does not load in your GAP installation, then please consult the documentation for that package in order to resolve the problem.

The following GAP packages are necessary to use a small, non-core subset of Vole's features, and are therefore optional.

The following GAP packages are needed to run Vole's test suite, but they are not required to use the rest of Vole, and are therefore also optional.

See Section 2.4 for more information about running the tests included in Vole.

In order to compile the Vole documentation, AutoDoc version 2019.09.04 or newer must be available. This step is usually unnecessary, and is not required in order to use Vole. See Section 2.5 for more information about compiling the documentation.

2.2 Installing Vole

Otherwise, if you do not yet have a copy of Vole, you should download the latest version of Vole.

If you have the PackageManager package installed, then you should be able to use it to download and compile Vole. Please consult the PackageManager documentation for full instructions of how to do this, but the commands should look something like:

gap> # Warning: this won't work until PackageManager has been taught about Vole!
gap> LoadPackage("PackageManager");
gap> InstallPackage("vole");
gap> CompilePackage("vole");

Alternatively, you can manually download the latest .tar.gz Vole archive from the Vole website and extract the archive into your GAP installation's pkg subdirectory. The commands to achieve this may look something like:

$ cd ~/gap/pkg
$ curl -O https://github.com/peal/vole/releases/download/vX.Y.Z/vole-X.Y.Z.tar.gz
$ tar xf vole-X.Y.Z.tar.gz

In order to compile Vole, change to your Vole directory and run make. This should look something like:

$ cd ~/gap/pkg/vole-X.Y.Z
$ make
cd rust && cargo build --bins && cargo build --release --bins
    [...
        potentially copious output omitted here
                                               ...]
    Compiling rust-vole v0.1.1
    Finished dev [unoptimized + debuginfo] target(s) in 8.93s
    Compiling rust-vole v0.1.1
    Finished release [optimized + debuginfo] target(s) in 30.06s

2.3 Loading Vole

If Vole is available to load, then it can be loaded by calling the function LoadPackage (Reference: LoadPackage) with the argument "vole", from within the relevant GAP installation. This should return true.

gap> LoadPackage("vole", false);
true

If LoadPackage instead returns fail, then Vole has failed to load. This is probably because GAP cannot find Vole or Vole is not compiled (Section 2.2), or one of the dependencies of Vole is not available (Section 2.1). If Vole fails to load, then please see the LoadPackage (Reference: LoadPackage) documentation for ways to help diagnose the problem further.

Otherwise, Vole is ready to use. To reassure yourself, you can quickly test that Vole is behaving as intended by quickly running a search, such that the following one:

gap> A4 := AlternatingGroup(4);
Alt( [ 1 .. 4 ] )
gap> D8 := DihedralGroup(IsPermGroup, 8);
Group([ (1,2,3,4), (2,4) ])
gap> Vole.Intersection(A4, D8) = Group([ (1,2)(3,4), (1,4)(2,3) ]);
true

If you wish to test your Vole installation more thoroughly, please see Section 2.4.

2.4 Running Vole's test suite

Optionally, if you wish to thoroughly test your Vole installation, then you can run the test suite. As well the dependencies of Vole itself, the test suite requires the GAP packages ferret (version 1.0.2 or newer) and QuickCheck (version 0.1 or newer) to be available.

There are two files that can be invoked to run extesive tests of Vole: run-tests.sh and tst/testall.g.

The run-tests.sh script, which is located in the root directory of Vole, begins by testing the Rust component directly, and then it tests the GAP-level interface to the Rust component. This script requires that the command gap, in your terminal environment, is set up to load the appropriate version of GAP for Vole.

$ ./run-tests.sh

To run only the GAP-level tests, please read the file testall.g of Vole's tst directory into GAP.

gap> Read("tst/testall.g");

2.5 Compiling the documentation for Vole

Released versions of Vole are distributed with precompiled documentation, so compiling the documentation should be an unnecessary for most users. However, development versions of Vole do not include precompiled documentation.

To compile the manual, it suffices to read Vole's makedoc.g file into GAP.

gap> Read("makedoc.g");

Alternatively, the makedoc.g file can be read into GAP by giving its path as an argument to GAP.

$ gap makedoc.g

Finally, running make doc in the Vole directory should compile the documentation of Vole if Vole is installed in the pkg subdirectory of the appropriate GAP installation.

$ make doc

2 Setting up Vole

2.1 Dependencies

2.2 Installing Vole

2.3 Loading Vole

2.4 Running Vole's test suite

2.5 Compiling the documentation for Vole