packages proposal

[Tyson Dowd]

On 10-Feb-1998, Fergus Henderson <fjh at cs.mu.OZ.AU> wrote:
> Hi,
> 
> The tests failed last night because `extras/cfloat/cfloat_lib.m',
> which is now compiled with `--halt-at-warn', got an error about
> nothing exported in the interface section.  The reason it exports
> nothing is that it is a package (i.e. a library of modules),
> not a module.
> 
> The quick fix is to add a dummy type or pred to the interface.
> But that's an ugly hack.
> 
> So, to solve this problem, I have a proposal for a new syntax for packages.

Fergus, your thesis is going to look like a Dickens novel with all these
chapters you keep adding...

> 
> Syntax:
> 
> 	:- package <ThisPackageName>.
> 	:- interface.
> 	:- import_package <PackageName>, <PackageName>, ...
> 	:- include_module <ModuleName>, <ModuleName>, ...
> 
> 	:- implementation.
> 	:- import_package <PackageName>, <PackageName>, ...
> 	:- include_module <ModuleName>, <ModuleName>, ...
> 	:- end_package <ThisPackageName>.
> 
> Examples:
> 
> 	Here's an arbitrary
> 
> 		:- package foo.
> 		:- interface.
> 		:- import_package bar, baz.
> 		:- include_module m1, m2, m3.
> 
> 		:- implementation.
> 		:- import_package quux.
> 		:- include_module m4, m5.
> 		:- end_package foo.
> 
> 	Here's the package definition for the Mercury standard library.
> 
> 		:- package std.
> 		:- interface.
> 		:- include_module io, string, char, ...
> 
> 		:- implementation.
> 		:- import_package debugger_interface.
> 
> 	Here's the package definition for the trailed_update package.
> 
> 		:- package trailed_update.
> 		:- interface.
> 		:- import_package std.
> 		:- include_module tr_store, tr_array, var.
> 
> 		:- implementation.
> 		:- include_module unsafe.
> 
> Semantics:
> 
> 	The `:- package' and `:- end_package' declarations are
> 	analagous to `:- module' and `:- end_module' declarations, but
> 	for packages instead of modules.  `:- end_package' is optional.
> 	A package is like a module, but a package can contain only
> 	`include_module' declarations; packages may not declare or
> 	define any types, insts, modes, preds, funcs, typeclasses, or
> 	typeclass instances.
> 

I'm a little unsure about the intended relationship between packages
and programs. What if a package includes a module that defines main?
What is a program imports a package that defines main? I think I know
what should happen, but your definition by analogy doesn't really
make it clear.

Also, you're not very clear about the meaning of `:- implementation'
in pacakges.

Should you have to include the dependencies in the `:- implementation'?
Why can't they be generated for you like they are for programs?


> 	An `:- import_package foo' declaration declares that this
> 	module or package makes use of modules defined in package
> 	`foo'.  Implementations could use this information to make
> 	it easier to use packages.  For example, for our current
> 	implementation, we could modify `mmc --generate-dependencies'
> 	to check for `import_package' declarations and would spit out
> 	appropropriate things in the `.dep' file which Mmake would use
> 	to include appropriate options when invoking `ml'. 
> 
> 	The Mercury implementation could encourage the use of
> 	standard paths for a package based on the package name,
> 	just as the current implementation strongly encourages the use
> 	of the same module name and file name.
> 	Command-line options would specify the directory

Options for what command? Should mmc search the libraries, or should it
just know about the -I option, and get mmake (or --generate
dependencies) to do the work?

Are packages more of a language feature or a build environment feature?
What is the division of responsibiliy?

> 	root, i.e. the first part of the path, for libraries
> 	(e.g. the default would be /usr/local/mercury-<version>/lib/mercury,
> 	but users could add additional ones), and the interface files
> 	and the .a and .so files would be searched for in standard locations
> 	relative to that root, e.g. $ROOT/ints/$PACKAGE/*.{int,int2,int3,opt},
> 	$ROOT/libs/lib$PACKAGE.a, $ROOT/libs/$PACKAGE.so, and
> 	$ROOT/modules/$PACKAGE.init.
> 
> 	This would help us to make the "Using Libraries" section of the
> 	Mercury User's Guide a little less awful (currently you
> 	have to set about 5 different variables to import a library).

Yes.

> 
> 	Note that `import_package' declarations should be allowed in
> 	modules as well as in packages.  It would be good style for
> 	each package to have `import_package' declarations for any
> 	packages imported by modules which that package includes (in
> 	other words, the import_package declarations in a package
> 	should be the union of the import_package declarations in its
> 	modules); perhaps the compiler should check this.
> 
> 	Initially, we will not allow explicit package qualifiers.
> 	Later, perhaps, we can add support for package qualifiers and
> 	`use_package' declarations (by analogy with `use_module').
> 
> 	Note the use of `include_module' rather than `import_module'.
> 	This is becaused `include_module' makes a module part of a
> 	package, whereas `import_module' would just be saying that the
> 	package uses that module.  `include_module' declarations would
> 	be allowed only in packages, not in modules.
> 
> 	Initially, we would leave the name mangling alone.
> 	Later, we can add a `--in-package <package-name>' option,
> 	and have `mmake package.depend' cause the files in that
> 	package to be compiled with this option, and have
> 	the compiler include the package name in the mangled name.
> 	Or we could allow module declarations of the
> 	form `:- module std.io' (or `:- module std:io', if we're
> 	still using `:' as module- and package- qualifier).
> 
> Because this proposal does not allow modules to contain other modules,
> and because packages can contain only other modules, not types or
> insts, etc., this proposal avoids much of the complexity that would
> be associated with having.

Having ... lunch? A baby? Infinite loops? Nested modules?

> 
> One thing that this proposal does not address is meta-packages
> (packages of packages) and/or hierarchical partitioning of the
> package namespace (allowing `.' in package names).
> 
> I think meta-packages would probably be a bad idea (too much
> complexity for too little gain), but I think you can probably
> get most of the same effect using a hierarchical partitioning
> of the package namespace.

I don't think meta-packages are worth implementing right now (or
in the near future) but it might be worth leaving the syntax or
implementation open. 

(if only because I'm sure they once said the same thing about
subdirectories).

> 
> Comments?

This is definitely worthwhile, but I'd like to know where you see
the packages fitting into the implementation. 

I probably have other comments, but I can't think of them just now.