Add command line option --packagedirs and GAP function ExtendPackageDirectories() to make it easier to use custom packages

doc/ref/files.xml

@@ -81,6 +81,10 @@ directories. For example when ⪆ wants to read its library file
 <C>GAPInfo.RootPaths</C> until it finds the path of an existing file.
 The first file found this way is read.
 <P/>
+Subdirectories <F>pkg/</F> in each of the directories in <C>GAPInfo.RootPaths</C>
+appear in <C>GAPInfo.PackageDirectories</C> (see <Ref Sect="GAP Package Directories"/>),
+which controls where &GAP; looks for available packages.
+<P/>
 The root directories are specified via one or several of the
 <C>-l paths</C> command line options, see <Ref Sect="Command Line Options"/>.
 Furthermore, by default &GAP; automatically prepends a user specific &GAP; root
@@ -91,6 +95,8 @@ This directory can be used to tell &GAP; about personal preferences,
 to always load some additional code, to install additional packages,
 or to overwrite some &GAP; files. See <Ref Sect="sect:gap.ini"/>
 for more information how to do this.
+After &GAP; has been started , one can add additional root directories
+via the function <Ref Func="ExtendRootDirectories"/>.
 <P/>
 
 </Section>
@@ -106,11 +112,13 @@ containing packages called the <E>&GAP; package directories</E>.
 In a running &GAP; session this list can be found in <C>GAPInfo.PackageDirectories</C>.
 <P/>
 Every subdirectory <F>pkg/</F> in a &GAP; root directory is automatically
-added to this list.
+added to this list. Further package directories can be specified via one or several of the
+<C>-/packagedirs paths</C> command line options, see <Ref Sect="Command Line Options"/>,
+or after &GAP; has been started via the function <Ref Func="ExtendPackageDirectories"/>.
 <P/>
 &GAP; looks for available packages by examining each of the directories in
 <C>GAPInfo.PackageDirectories</C>.
-
+The root directories are specified
 </Section>
 
 

doc/ref/run.xml

@@ -260,6 +260,27 @@ It is not possible  to use ⪆ without the  library files, so you must
 not  ignore this warning.  You  should leave ⪆   and start it again,
 specifying the correct root path using the <C>-l</C> option.
 </Item>
+<Mark><Index Key="--packagedirs"><C>-L</C></Index>
+<C>-l </C><A>path_list</A></Mark>
+<Item>
+can be used to add paths to &GAP;'s list of package directories
+(see <Ref Sect="GAP Package Directories"/>).
+The list always contains all subdirectories <F>pkg/</F> in a &GAP; root directory.
+<P/>
+<A>path_list</A> should be a list of directories separated by semicolons.
+No whitespace is permitted before or after a semicolon, and the first and
+last character of <A>path_list</A> may not be a semicolon.
+After &GAP; has completed its startup procedure  and
+displays the prompt, the list of package directories can be  seen  in  the
+variable <C>GAPInfo.PackageDirectories</C>,
+see <Ref Var="GAPInfo"/>.
+<P/>
+Usually this option is used inside a startup script to specify
+where additional &GAP; packages are located on the system.
+The <C>-l</C> option can also be used by individual users to tell &GAP;
+about additional &GAP; packages, without the need to setup a complete root
+directory structure.
+</Item>
 <Mark><Index Key="-M"><C>-M</C></Index>
 <C>-M</C></Mark>
 <Item>

lib/package.gi

@@ -304,8 +304,8 @@
     # the first time this is called, add the cmd line args to the list
     if IsEmpty(GAPInfo.PackageDirectories) then
         for pkgdirstrs in GAPInfo.CommandLineOptions.packagedirs do
             pkgdirs:= List( SplitString( pkgdirstrs, ";" ), Directory);
             APPEND_LIST_INTR( GAPInfo.PackageDirectories, pkgdirs );
         od;
     fi;
     # add any new pkg directories to the list
@@ -1952,7 +1952,6 @@
     local i;
 
     rootpaths:= Filtered( rootpaths, path -> not path in GAPInfo.RootPaths );
-    # TODO: validate the paths???
     if not IsEmpty( rootpaths ) then
       # 'DirectoriesLibrary' concatenates root paths with directory names.
       for i in [ 1 .. Length( rootpaths ) ] do
@@ -1981,26 +1980,26 @@
 ##
 InstallGlobalFunction( ExtendPackageDirectories, function( paths_or_dirs )
     local p, changed;
     changed:= false;
     for p in paths_or_dirs do
       if IsString( p ) then
         p:= Directory( p );
       elif not IsDirectory( p ) then
         Error("input must be a list of path strings or directory objects");
       fi;
       if not p in GAPInfo.PackageDirectories then
         Add( GAPInfo.PackageDirectories, p );
         changed:= true;
       fi;
     od;
     if changed then
       # Reread the package information.
       if IsBound( GAPInfo.PackagesInfoInitialized ) and
          GAPInfo.PackagesInfoInitialized = true then
         GAPInfo.PackagesInfoInitialized:= false;
         InitializePackagesInfoRecords();
       fi;
     fi;
     end );
 
 

lib/system.g

@@ -96,7 +96,7 @@ BIND_GLOBAL( "GAPInfo", rec(
                      "of root paths" ] ),
       rec( short:= "r", default := false, help := ["disable/enable user GAP root dir", "GAPInfo.UserGapRoot"] ),
       rec( long := "packagedirs", default := [], arg := "<paths>",
-           help := [ "set or modify the GAP directory paths",
+           help := [ "add additional GAP directory paths",
                      "Directories are separated using ';'." ] ),
       ,
       rec( section:= ["Loading:"] ),