[modules-dev] Thoughts on initial repository tool

[Dave Bristor]

Hi folks,

Here are some notes, on an initial repository tool "jrepo".

Usage: jrepo <subcommand> <flags> <options>

Common flags:
-v: verbose - yields more output
-p: parent - follow parent chain (see below)
-r repositoryLocation: repository  - location is filesystem path or URL to 
repository to be used

Subcommands & associated args:

* list [-v] [-p] [-r repositoryLocation]
Lists the names & versions of modules in a repository.  With -v, also gives 
platform, architecture, pathname, and last modified time (if available).  With 
-p, includes parent repositories.  With -r, uses the given repository; else 
the system repository.  Listed modules are displayed in the same order that 
Repository.find() would find them (i.e. bootstrap-repository-first).

* find [-v] [-p] [-r repositoryLocation] moduleName [moduleVersion]
query (synonym for find)
Results are similar to "list", but include repository name and module info as 
in "list".  Options similar to "list".  Exits non-zero if no match found in 
any repository.  Repository search order is same as Repository.find() *but* 
results do not take into account current platform-arch.  Open issue: probably 
should allow versionConstraint instead of a simple version, as well as other 
query args.

* install [-v] [-f] JAMFile repositoryLocation  JAMFile
Installs the named JAMfile into the named repository.  -f forces installation 
even if another module with same characteristics (name, version, platform, 
architecture) is already installed.  With -v, issues warnings if any dependent 
modules are not accessible (this might not be in jrepo v0.1).

* uninstall [-v] repositoryLocation moduleName [moduleVersion] \ 
[modulePlatform-moduleArch]
Uninstalls the identified module from the named repository.  Fails if 
information given identifies more than one module.


The remaining subcommands won't (necessarily) appear in the initial tool; they 
need more thought:

dependencies [-v] [-r repositoryLocation] moduleName [moduleVersion] \ 
[modulePlatform-moduleArch]
Lists all the modules on which the identified module depends.  Fails if 
information given identifies more than one module.

contents [-v] [-r repositoryLocation] moduleName [moduleVersion] \ 
[modulePlatform-moduleArch]
Lists the contents of the identified module (e.g. similar to "ls -lR" or "jar 
tf").

get [-v] [-r repositoryLocation] moduleName [moduleVersion] \ 
[modulePlatform-moduleArch]
Creates a JAM file from the identified module.

check [-v] [-r repositoryLocation] moduleName [moduleVersion] \ 
[modulePlatform-moduleArch]
Runs shallow (or deep?) validationon the given module.


Notes:

* If repositoryPath is not given, jrepo will use the currently configured 
repositories.  (Repository configuration is not yet implemented, but when it 
is...see bug 6560281.)

* Users should not have to type the entire subcommand, just enough characters 
to distinguish it from other subcommands.

* Needs more thought: a module can be defined in more than one repository; 
"list -p" will identify these situations.  Should "contents -p" be allowed, 
and if so, what should be its behavior in this situation?  Show the contents 
of each module, or stop at the first?

* Question: are there other module attributes/annotations/characteristics that 
should be considered in identifying the module?  This applies to install, 
uninstall, dependencies, etc.

* install can give warnings if dependencies are not satisfied

* repositoryPath does not identify the *type* of the repository: the initial 
tool will treat it as a file system path or URL and use a Local or 
URLRepository as appropriate.  In the fullness of time, we probably need some 
way to allow users to specify the kind of repository, e.g. a "-class clazz" or 
"-type serviceType" argument.

Feedback welcome,
	Dave