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

doc/ref/files.xml

@@ -81,10 +81,6 @@ 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/>
-Furthermore, &GAP; looks for available packages by examining the
-subdirectories <F>pkg/</F> in each of the directories in
-<C>GAPInfo.RootPaths</C>.
-<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
@@ -100,6 +96,24 @@ for more information how to do this.
 </Section>
 
 
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<Section Label="GAP Package Directories">
+<Heading>GAP Package Directories</Heading>
+<Index Key="GAPInfo.PackageDirectories"><C>GAPInfo.PackageDirectories</C></Index>
+
+When &GAP; is started it determines a list of directories potentially
+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.
+<P/>
+&GAP; looks for available packages by examining each of the directories in
+<C>GAPInfo.PackageDirectories</C>.
+
+</Section>
+
+
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <Section Label="Directories">
 <Heading>Directories</Heading>

doc/ref/gappkg.xml

@@ -96,6 +96,7 @@ that is they will be loaded automatically when ⪆ starts
 
 <#Include Label="SetPackagePath">
 <#Include Label="ExtendRootDirectories">
+<#Include Label="ExtendPackageDirectories">
 <#Include Label="DisplayPackageLoadingLog">
 
 </Section>

lib/package.gd

@@ -859,7 +859,8 @@ DeclareGlobalFunction( "LoadPackage" );
 ##  <P/>
 ##  See <Ref Func="SetPackagePath"/> for a way to force the loading of a
 ##  prescribed package version.
-##  See also <Ref Func="ExtendRootDirectories"/> for a method of adding
+##  See also <Ref Func="ExtendRootDirectories"/> and
+##  <Ref Func="ExtendPackageDirectories"/> for methods of adding
 ##  directories containing packages <E>after</E> &GAP; has been started.
 ##  </Subsection>
 ##  <#/GAPDoc>
@@ -947,6 +948,29 @@ DeclareGlobalFunction( "SetPackagePath" );
 ##
 DeclareGlobalFunction( "ExtendRootDirectories" );
 
+
+#############################################################################
+##
+#F  ExtendPackageDirectories( <paths> )
+##
+##  <#GAPDoc Label="ExtendPackageDirectories">
+##  <ManSection>
+##  <Func Name="ExtendPackageDirectories" Arg='paths'/>
+##
+##  <Description>
+##  Let <A>paths</A> be a list of strings that denote paths to intended
+##  &GAP; package directories (see <Ref Sect="GAP Package Directories"/>).
+##  The function <Ref Func="ExtendPackageDirectories"/> adds these paths to
+##  the global list <C>GAPInfo.PackageDirectories</C> and calls the initialization of
+##  available &GAP; packages,
+##  such that later calls to <Ref Func="LoadPackage"/> will find the &GAP;
+##  packages that are contained in the directories given by <A>paths</A>.
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+DeclareGlobalFunction( "ExtendPackageDirectories" );
+
 #############################################################################
 ##
 #F  InstalledPackageVersion( <name> )

lib/package.gi

@@ -286,7 +286,7 @@
 ##  In earlier versions, this function had an argument; now we ignore it.
 ##
 InstallGlobalFunction( InitializePackagesInfoRecords, function( arg )
-    local pkgdirs, pkgdir, ignore, name, files, record, r;
+    local pkgdirs, pkgdir, pkgdirstrs, ignore, name, files, record, r;
 
     if IsBound( GAPInfo.PackagesInfoInitialized ) and
        GAPInfo.PackagesInfoInitialized = true then
@@ -300,8 +300,24 @@
 
     LogPackageLoadingMessage( PACKAGE_DEBUG,
         "entering InitializePackagesInfoRecords", "GAP" );
+
+    # 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
     pkgdirs:= DirectoriesLibrary( "pkg" );
-    if pkgdirs = fail then
+    if pkgdirs <> fail then
+        pkgdirs:= Filtered( pkgdirs, dir -> not dir in GAPInfo.PackageDirectories );
+        if not IsEmpty(pkgdirs) then
+            APPEND_LIST_INTR( GAPInfo.PackageDirectories, pkgdirs );
+        fi;
+    fi;
+
+    if IsEmpty(GAPInfo.PackageDirectories) then
       LogPackageLoadingMessage( PACKAGE_DEBUG,
           "exit InitializePackagesInfoRecords (no pkg directories found)",
           "GAP" );
@@ -327,7 +343,7 @@
     # Loop over the package directories,
     # remove the packages listed in `NOAUTO' files from GAP's suggested
     # packages, and unite the information for the directories.
-    for pkgdir in pkgdirs do
+    for pkgdir in GAPInfo.PackageDirectories do
 
       if IsBound( GAPInfo.ExcludeFromAutoload ) then
         UniteSet( GAPInfo.ExcludeFromAutoload,
@@ -1936,6 +1952,7 @@
     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
@@ -1958,6 +1975,35 @@
     end );
 
 
+#############################################################################
+##
+#F  ExtendPackageDirectories( <paths_or_dirs> )
+##
+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 );
+
+
 #############################################################################
 ##
 #F  InstalledPackageVersion( <name> )

lib/system.g

@@ -95,6 +95,9 @@ BIND_GLOBAL( "GAPInfo", rec(
                      "directories to the end/start of existing list",
                      "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",
+                     "Directories are separated using ';'." ] ),
       ,
       rec( section:= ["Loading:"] ),
       rec( short:= "A", default := false, help := ["disable/enable autoloading of suggested", "GAP packages"] ),
@@ -302,6 +305,7 @@ CallAndInstallPostRestore( function()
 
     # paths
     GAPInfo.RootPaths:= GAPInfo.KernelInfo.GAP_ROOT_PATHS;
+    GAPInfo.PackageDirectories := [];
     if  IsBound(GAPInfo.SystemEnvironment.HOME) then
       GAPInfo.UserHome := GAPInfo.SystemEnvironment.HOME;
     else