draft proposal for relative paths in installed package descriptions

[Duncan Coutts]

All,

This is a draft proposal for a common mechanism for implementing
relative paths in installed package descriptions.

Comments and feedback are welcome. I'm cc'ing this to the cabal and
ghc-users lists but let's keep the discussion on the libraries list.

There has been some discussion of this issue on the cabal and ghc-users
list, but it's a relatively long thread and the idea has evolved
somewhat so this is an attempt to present the proposal clearly.


Proposal
========

This proposal is an extension to the Cabal spec section 3
http://haskell.org/cabal/proposal/x272.html


Motivation
----------

Being able to have relative paths in the installed package description
is useful as it makes it possible to construct relocatable
(prefix-independent) package installations. This is useful when
distributing compilers along with packages and there may be other uses.

This proposal does not require that all paths are relative. It is still
perfectly ok to use absolute paths where appropriate.  It just adds an
option to use relative paths.

The aim is for a single simple specification that any compiler can
implement and have the tools work uniformly, rather than ad-hoc
implementations for each compiler.


Details
-------

In the installed package description, we will allow paths that begin
with the variables ${pkgroot} or ${pkgrooturl}. For example:

library-dirs: ${pkgroot}/foo-1.0
haddock-html: ${pkgrooturl}/doc/foo-1.0

They may only appear at the beginning of the paths and must be followed
by a directory separator (platform-dependent '/' or '\'). This is
because the vars refer to a directory so it does not make sense to
construct extensions like ${pkgroot}blah. The use of '{}' is required
and is to avoid any ambiguity (especially since the string "$pkgrooturl"
is otherwise an extension of "$pkgroot").

Directly relative file paths like "blah" or "./blah" are not allowed.
Fields containing paths must be absolute or begin with ${pkgroot}. Field
containing urls must be absolute or begin with ${pkgrooturl}.

The var ${pkgroot} is to be interpreted as the directory containing the
installed package description. For ghc this will be the dir containing
the package.conf db, for hugs/nhc for each package there is a specific
installed package description file, and ${pkgroot} is thus the directory
containing that file. The syntax of the string representing this
directory is the usual system-dependent filepath syntax, e.g.
windows: c:\ghc\ghc-6.12.1
unix:    /opt/ghc-6.12.1

The var ${pkgrooturl} is to be interpreted as a url representation of
the directory containing the installed package description. For ghc this
will be the dir containing the package.conf db, for hugs/nhc for each
package there is a specific installed package description file, and
${pkgroot} is thus the directory containing that file. The syntax of the
string representing this directory is as a valid file url including the
file:// prefix e.g.
windows: file:///c:/ghc/ghc-6.12.1
unix:    file:///opt/ghc-6.12.1

This is similar to how relative paths in .cabal files are interpreted
relative to the directory containing the .cabal file, however in this
case we mark relative paths more explicitly using a variable.

So in the original example

library-dirs: ${pkgroot}/foo-1.0
haddock-html: ${pkgrooturl}/doc/foo-1.0

If we assume this installed package description is at c:\ghc\ghc-6.12.1
\package.conf on windows or /opt/ghc-6.12.1/package.conf on unix then
the compiler and other tools would interpret these as

library-dirs: c:\ghc\ghc-6.12.1/foo-1.0
haddock-html: file:///c:/ghc/ghc-6.12.1/doc/foo-1.0

or on unix:

library-dirs: /opt/ghc-6.12.1/foo-1.0
haddock-html: file:///opt/ghc-6.12.1/doc/foo-1.0


Tools
-----

Tools which process the installed package description format will be
expected to interpret these relative paths. This requires that they can
discover the path for the ${pkgroot}. How they discover this is
dependent on the Haskell implementation. Some implementations use
separate files for each installed package description, some embed them
in library package files, some use databases of installed package
descriptions. Haskell implementations should provide a mechanism to
discover the path for an installed package description.


Duncan