Update or delete some documentation (#5633)

- remove or update references to obsolete `make testFOO` targets
- remove text in the dev manual about compiling library code (the
  relevant functionality was already removed in 2016, the last version
  to have it was GAP 4.8)
- update an example which still assumed `gac` to be inside `bin/ARCH/`
- update recommend for `TestFile` to match current reality
- remove references to `dev/log/`
- remove or update some obsolete references to memory usage and test runtimes
- remove suggestions to alter GAP memory config using command line arguments

CONTRIBUTING.md

@@ -114,10 +114,9 @@ to create a GitHub account, see below for an alternative.
           single space, with blank lines in between, but conventions vary here
 
 * Make sure you have added any necessary tests for your changes.
-* Run all the tests to assure nothing else was accidentally broken.
+* Run some tests to assure nothing else was accidentally broken.
 
-        $ make testinstall
-        $ make teststandard
+        $ make check
 
 * Push your changes to a topic branch in your fork of the repository.
 

doc/dev/kernel.xml

@@ -1024,70 +1024,6 @@ operations with basic data types, such as lists or small integers.
 
 </Subsection>
 
-<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
-<Subsection Label="Compiling Library Code">
-<Heading>Compiling Library Code</Heading>
-
-This subsection describes the mechanism used to make &GAP; recognize compiled
-versions of library files. Note that there is no point in compiling
-the whole library as typically only few functions benefit from compilation as
-described in Section&nbsp;<Ref Sect="Suitability for Compilation"/>.
-<P/>
-All library files that come with &GAP; (not the files that belong to &GAP;
-packages) are read using the internal function <C>READ_GAP_ROOT</C>.
-This function then checks whether a compiled version of the file exists
-and if its CRC number (see&nbsp;<Ref Sect="CrcFile" BookName="ref"/>) matches the file.
-If it does, the compiled version is loaded.  Otherwise the file is read.
-You can start &GAP; with the <C>-D -N</C> option to see information printed
-about this process.
-<P/>
-To make &GAP; find the compiled versions, they must be
-put in the <F>bin/</F><A>systemname</A><F>/compiled</F> directory
-(<A>systemname</A> is the name you gave for compilation,
-for example <F>i386-ibm-linux-gcc2</F>).
-They have to be called according to the following scheme:
-Suppose the file is <F>humpty/dumpty.gi</F> in the &GAP; home directory.
-Then the compiled version will be
-<F>bin/</F><A>systemname</A><F>/compiled/humpty/gi/dumpty.so</F>.
-That is, the directory hierarchy is mirrored under the <F>compiled</F>
-directory.
-A further directory level is added for the suffix of the file,
-and the suffix of the compiled version of the file is set to <C>.so</C>
-(as produced by the compiler).
-<P/>
-For example we show how
-to compile the <F>combinat.gi</F> file on a Linux machine.
-Suppose we are in the home directory of the gap distribution.
-<P/>
-<Log><![CDATA[
-bin/i386-ibm-linux-gcc2/gac -d lib/combinat.gi
-]]></Log>
-<P/>
-creates a file <F>combinat.so</F>. We now put it in the right place, creating
-also the necessary directories:
-<P/>
-<Log><![CDATA[
-mkdir bin/i386-ibm-linux-gcc2/compiled
-mkdir bin/i386-ibm-linux-gcc2/compiled/lib
-mkdir bin/i386-ibm-linux-gcc2/compiled/lib/gi
-mv combinat.so bin/i386-ibm-linux-gcc2/compiled/lib/gi
-]]></Log>
-<P/>
-If you now start &GAP; and look, for example, at the function
-<Ref Func="Binomial" BookName="ref"/>, defined in <F>combinat.gi</F>,
-you see it is indeed compiled:
-<Log><![CDATA[
-gap> Display(GaussianCoefficient);
-function ( n, k, q )
-    <<compiled GAP code>> from GAPROOT/lib/combinat.g:26
-end
-]]></Log>
-<P/>
-The command line option <C>-M</C>  disables the loading of compiled modules
-and always reads code from the library.
-
-</Subsection>
-
 </Section>
 
 

doc/dev/testing.xml

@@ -213,43 +213,39 @@ you should make sure that the system is up to date, in particular,
 Then proceed as follows in the ⪆ root directory.
 <List>
   <Item>
-    Call <C>make testinstall</C>.
+    Call <C>dev/ci.sh testinstall</C>.
     This reads the file <C>tst/testinstall.g</C>,
     which should require just a few minutes.
   </Item>
   <Item>
-    Call <C>make testmanuals</C>.
+    Call <C>dev/ci.sh testmanuals</C>.
     This runs the examples in the main &GAP; manuals,
     and should also require only a few minutes.
     (Note that a new &GAP; process is started for each manual chapter.
     In order to accelerate this, a &GAP; workspace is created
     in the beginning, is reused for each chapter, and removed in the end.)
   </Item>
   <Item>
-    Call <C>make teststandard</C>.
+    Call <C>dev/ci.sh teststandard</C>.
     This runs the tests in <C>tst</C>,
     and may require a couple of hours.
   </Item>
   <Item>
-    Call <C>make testpackages</C>.
+    Call <C>dev/ci.sh testpackages</C>.
     This starts a new &GAP; session for each accepted or deposited package,
     and reads the file given by the component <C>TestFile</C> in the
     <F>PackageInfo.g</F> file (if this is available).
     It may require several hours.
   </Item>
   <Item>
-    Call <C>make testpackagesloading</C>.
+    Call <C>dev/ci.sh testpackagesloading</C>.
     This loads each accepted or deposited package in a new &GAP; session,
     then starts a new &GAP; session and calls <Ref BookName="ref" Func="LoadAllPackages"/>
     to check that all packages may be loaded simultaneosuly.
     It require just a few minutes.
   </Item>
 </List>
 
-In each case, &GAP; is called with the command line options
-<C>-m 100m -o 550m -A -N -q -x 80 -r</C>,
-cf. <Ref BookName="Ref" Sect="Command Line Options"/>,
-and the assertion level is set to 2 before the tests.
 <P/>
 
 The output is written to files in the directory <F>dev/log</F>,

doc/ref/gappkg.xml

@@ -133,13 +133,11 @@ and follows certain conventions to comply with the ⪆ kernel interface,
 which we plan to document later. In the meantime, we advice to get in touch
 with ⪆ developers if you plan to develop such a package.
 <P/>
-<!-- %%  The gac script works only on UNIX systems. It was written by -->
-<!-- %%  Ferenc&nbsp;R{\'a}k{\'o}czi and Martin Sch{\"o}nert. -->
 To use the <Package>gac</Package> script to produce dynamically loadable
 modules, call it with the <C>-d</C> option, for example:
 <P/>
 <Log><![CDATA[
-$ gap4/bin/i386-ibm-linux-gcc2/gac -d test.c
+$ gap4/gac -d test.c
 ]]></Log>
 <P/>
 This will produce a file <F>test.so</F>, which then can be loaded into &GAP;
@@ -1882,7 +1880,6 @@ in the example below:
 <Log><![CDATA[
 gap> Test("tst/testall.tst");
 Example package: testall.tst
-GAP4stones: 3333
 true
 ]]></Log>
 Tests which produce extended output and/or require substantial runtime
@@ -1893,16 +1890,18 @@ instructions on how to run them elsewhere.
 Because of different approaches to testing, used by different packages,
 it is not always easy to identify whether an automated test passed or failed.
 Presently, automated detection works fine if a package uses a single
-<F>.tst</F> file or uses <Ref Func="TestDirectory"/> to run a collection of
-tests. Otherwise, one should follow the convention to output a string of a
-fixed format to indicate the result of the test in the test script along the
-following lines:
+<F>.tst</F> file or uses <Ref Func="TestDirectory"/> with the <C>exitGAP</C>
+option set to <K>true</K> to run a collection of tests and then exits &GAP;
+in a way that allows an automated test setup to determine whether the test passed or failed:
 <Log><![CDATA[
-if testresult then
-  Print("#I  No errors detected while testing"\n");
-else
-  Print("#I  Errors detected while testing\n");
-fi;
+TestDirectory(DirectoriesPackageLibrary("packagename", "tst"), rec(exitGAP := true));
+]]></Log>
+If one needs a more sophisticated test file, then it should end with an invocation
+of <Ref Func="ForceQuitGap"/> with an argument that indicates whether the tests overall
+passed (<K>true</K>) or failed (<K>false</K> or <K>fail</K>). For example,
+if the test result is stored in a variable <C>testresult</C> then you can do this:
+<Log><![CDATA[
+ForceQuitGap(testresult);
 ]]></Log>
 </Subsection>
 
@@ -1941,65 +1940,12 @@ The test of loading all packages is the most subtle one. Quite often
 it reveals problems which do not occur in the default configuration
 but may cause difficulties to the users of specialised packages.
 <P/>
-For your convenience, <C>make testpackagesload</C> called in the &GAP;
-root directory will run all package loading tests listed in this subsection
-and write their output in its <C>dev/log</C> directory.
-<P/>
-It will produce four files with test logs, corresponding to the
-four cases above (the letter <C>N</C> in the filename stands for
-<Q>needed</Q>, <C>A</C> stands for <Q>autoloaded</Q>):
-<List>
-<Item>
-<F>dev/log/testpackagesload1_...</F>
-</Item>
-<Item>
-<F>dev/log/testpackagesloadN1_...</F>
-</Item>
-<Item>
-<F>dev/log/testpackagesloadA_...</F>
-</Item>
-<Item>
-<F>dev/log/testpackagesloadNA_...</F>
-</Item>
-</List>
-Each file contains small sections for loading individual packages: among those,
-you need to find the section related to your package and may ignore all other
-sections. For example, the section for the <Package>Example</Package> package looks like
-<Log><![CDATA[
-%%% Loading example 3.3.3
-[  ]
-### Loaded example 3.3.3
-]]></Log>
-so it has clearly passed the test. If there are any error messages displayed
-between <C>Loading ...</C> and <C>Loaded ...</C> lines, they will signal on
-errors during loading of your package.
-<P/>
-Additionally, this test collects information about variables created since
-the library was read (obtained using <Ref Func="NamesUserGVars"/>)
-with either short names (no more than three characters) or names breaking a
-recommended naming convention that the &GAP; core system and &GAP; packages
+Additionally, we recommend using <Ref Func="ShowPackageVariables"/> to
+see information about variables created by your package to check if any
+have either short names (no more than three characters) or names breaking a
+recommended naming convention that the &GAP; core system. &GAP; packages also
 should not use global variables starting in the lowercase
 (see Section <Ref Sect="Functions and Variables and Choices of Their Names"/>).
-Their list will be displayed in the test log (in the example above, <Package>Example</Package>
-packages does not create any such variables, so an empty list is displayed).
-It may be hard to attribute a particular identifier to a package, since it
-may be created by another package loaded because of dependencies, so when
-a more detailed and precise report on package variables is needed, it may
-be obtained using <Ref Func="ShowPackageVariables"/>
-(also, <C>make testpackagesvars</C> called in the &GAP; root directory
-produces such reports for each package and writes them to a file
-<F>dev/log/testpackagesvars_...</F>).
-<P/>
-Finally, each log file finishes with two large sections for loading all
-packages in the alphabetical and reverse alphabetical order (to check more
-combinations of loading one package after another). We are aiming at
-releasing only collections of package which do not break
-<Ref Func="LoadAllPackages"/> in any of the four configurations, so if
-it is broken when you plug in the development version of your package into
-the released version of &GAP;, it is likely that your package triggers
-this error. If you observe that <Ref Func="LoadAllPackages"/> is broken
-and suspect that this is not the fault of your package, please contact
-the &GAP; Support.
 </Subsection>
 
 <ManSection>
@@ -2031,15 +1977,15 @@ first you must start a new &GAP; session and then read either <F>testinstall.g</
 or <F>teststandard.g</F> as demonstrated below.
 <P/>
 
-The quicker test, <F>testinstall.g</F>, requires about 1 GB of memory and
-runs for several minutes. It may be started with the command
+The quicker test, <F>testinstall.g</F>, should run in about a minute depending
+on your hardware speed. It may be started with the command
 <Log><![CDATA[
 gap> Read( Filename( DirectoriesLibrary( "tst" ), "testinstall.g" ) );
 ]]></Log>
 You will get a large number of lines with output about the progress of
 the tests, for example:
 <Log><![CDATA[
-You should start GAP4 using `gap -A -x 80 -r -m 100m -o 1g -K 2g'.
+You should start GAP4 using `gap -A -x 80 -r'.
 
 Architecture: SOMETHING-SOMETHING-gcc-default64
 
@@ -2064,7 +2010,7 @@ will see in the test output, to run it in a more conservative settings).
 
 The more thorough test is <F>teststandard.g</F> which exercises more of &GAP;'s
 capabilities, also including all test files from <F>teststandard.g</F>.
-It requires about 1 GB of memory, runs for about one hour, and produces
+It runs quite a bit longer, maybe 10-20 minutes, and produces
 an output similar to the testinstall.g test.
 To run it, also start a new &GAP; session and then call
 <Log><![CDATA[

lib/test.gi

@@ -1044,22 +1044,7 @@ end);
 ##
 ##  The output of the test depends on the particular package, and it also
 ##  may depend on the current ⪆ session (loaded packages, state of the
-##  random sources, defined global variables etc.). If you would like to
-##  run the test for the same package in the same setting that is used
-##  for the testing of ⪆ releases, you have to call
-##
-##  <Log><![CDATA[
-##  make testpackage PKGNAME=pkgname
-##  ]]></Log>
-##
-##  in the UNIX shell (without quotes around <A>pkgname</A>). This will run
-##  the standard test for the package <A>pkgname</A> three times in different
-##  settings, and will write test output to three files in the <F>dev/log</F>
-##  directory. These output files will be named in the format
-##  <F>testpackageX_timestamp.pkgname</F>, where <C>X=A</C> for the test
-##  with packages loaded by default, <C>X=1</C> for the test without other
-##  packages (i.e. when &GAP; is started with <C>-A</C> command line option),
-##  and <C>X=2</C> when the test is run with all packages loaded.
+##  random sources, defined global variables etc.).
 ##  </Description>
 ##  </ManSection>
 ##  <#/GAPDoc>