# Meta packages for GAP distribution

## What do we want?

Have "Meta-packages" (dummy packages) which hold several "sub-packages" (complete and real GAP packages), which are distributed in a single tarball.
This is useful for several reasons

* Projects (CAP, homalg) use single repositories for all packages in the project. For releases, they have to be ripped appart
* Having a consistent version of the whole project, useful for referencing
* Make it possible to load the whole project at once
* Have a build script for the whole project, allowing to link package kernel extensions together
* Ease navigation within the `pkg` directory and within the Packages section of the GAP website

## Links

* Github meta package demo
* https://github.com/sebasguts/MetaPackage
* Original pull request with discussion (Now updated)
* https://github.com/gap-system/gap/pull/2267
* GAP distribution code that creates package web pages from `PackageInfo.g`
* https://github.com/gap-system/gap-distribution/blob/master/DistributionUpdate/PackageUpdate/PackageInfoTools.g#L1491

## Things to consider

* should sub-packages be allowed to have sub-packags of their own?
* Max: I don't have a strong oppinion on this, but would tend to say we should forbid it initially: it is trivial to allow it later on, should it be requested; but it is hard to take a feature back once it's been made available
* Sebastian: I am also against it
* Alex: agree with Max

* what about the name(s): some people found meta-package confusing; subpackage seems to be OK. Alternatives?
* meta package (just keep it)
* superpackage
* package with sub-packages
* PackageCollection
* project
* package suite
* package bundle
* (parent package)
* ...

* dependencies: should the meta package depend on its subpackages / children? or the other way around? or nothing at all?
* Max: I'd prefer if the metapackage just depends on its subpackags. That makes it very easy to implement; it also is very easy to explain, and makes it trivial to have `LoadPackage("metapkg")` do the expected thing (i.e., load all subpackages)
* it was also suggested that the meta package could contain code used by all subpackages; that would then imply that the metapackage is a dependency of the sub-packages. That means `LoadPackage("metapackage")` would not do what you'd expect (at least not without a hack; which in turn would make it more complicatd to explain what LoadPackage does).
* Alex: it probably stops to be "meta" as soon as it has code needed by subpackages...
* Sebastian: Having the meta package containing additional code is probably not necessary at all. Having code that sits "below" or "above" all packages can easily be achieved by adding another package to the meta package that is required/requires all other packages in the meta package.
* Alex: Indeed. Does this mean e.g. that current homalg will have to be moved into a new package, or there wil be a new meta-package for the homalg project?

* should the meta package be allowed to have an init.g (and read.g)? Be required (as regular packages are)? Be forbidden
* Max: I don't think it should be *required* to have an `init.g`. I am neutral on whethr it should be allowed to have one; but of course once again, it's easier to add this later, then to remove a feature once it's out in the open (implementation wise, allowing `init.g` is the least work, but it should be a 1-2 line change to forbid it for metapackages)
* Sebastian: I would, together with the additional code, not allow it
* Alex: if the package has no code, then I do not see a need in init.g. Dependencies mechanism alone should allow to load subpackages.
* Alex: another question is what *is* allowed: I think `doc` and `tst` directories, and scripts to build the meta-manual and run tests should be permitted.

* the validator needs to be update to deal with meta and sub packages
* Sebastian: Done

* documentation needs to be written

* the GAP distribution needs to be adapted to support them:
* ...

* Website / GapWWW:
* Max: Right now, we have an URL like this for a package: <https://www.gap-system.org/Packages/aclib.html>. I suggest we change this to directories, containing an `index.html`, so this becomes <https://www.gap-system.org/Packages/aclib/>. Now suppose you have `MetaPkg` containing `Sub1` and `Sub2`. Then the URLs for this could be <https://www.gap-system.org/Packages/MetaPkg/>, <https://www.gap-system.org/Packages/MetaPkg/Sub1>, <https://www.gap-system.org/Packages/MetaPkg/Sub2>. I think this is not too hard to do, but of course if something is easier to implement, I am also open to that
* Alex: agree with Max.

## Roadmap

Sebastian has started work on a prototype

* adapt LoadPackages code to load subpackages, but only if `IsMetaPackage = true` (Currently in https://github.com/gap-system/gap/pull/2267)
* ...

## TODO: notes from discussion on 2019-03-20 (to be sorted into text above)

- document: meta packages don't need a manual; but they can, and we encourage that they either have one; or that some subpackage has a manual index entry named "NameOfMetaPackage" so that people can enter `?NameOfMetaPackage` to learn what the meta package is about

- how to present meta/sub packages on website?
- ...

- interaction with PackageManager ?
- ...

- Fix validator code

- Policies of meta-packages
- good practice to inform GAP mailing lists of adding new packages
- Treat adding new packages as a major change

- testing: when importing package updates, I think we run tests at some point. Well, for meta packages, we should run the tests of all subpackages! So we need to ensure we do that.