-*- mode:text; fill-column:100 -*-

File System Layout

We aim for compatibility with the following standards for file system layout:

   Filesystem Hierarchy Standard    http://www.pathname.com/fhs/
   Fink				    http://fink.sourceforge.net/doc/packaging/fslayout.php

The main conflict between fink and fhs is that fhs prefers /usr/man and fink prefers /usr/share/man,
so we choose the latter.

See also http://cr.yp.to/unix.html, the section on "Filesystem layout", for another way, which
we'll support eventually, too, as an option.

The paths in the chart below are relative to ".".  When the files are installed by the system
administrator, then "." is usually /usr, /usr/local, or /sw.  The environment variable PREFIX is set
to the latter directory in the script "M2" so Macaulay2 can find the files of the packages, which
are installed independently.

When the files are packaged into a tar file by the package author, then the name of the tar file
should be PACKAGE-RELEASE.tar.gz, where PACKAGE is the package name, e.g., "Macaulay2" or
"D-modules", and RELEASE is the version number, containing no hyphens, e.g. 0.9.4 or 1.0.  Tar files
contain exactly the paths below, with "." replaced by PACKAGENAME-RELEASENUMBER, e.g,
Macaulay2-0.9.4, or D-modules-1.0.  The name of the tarfile should be
PACKAGENAME-RELEASENUMBER-ARCH.tar.gz, where ARCH is a string that gives information about the
architecture for which Macaulay2 has been compiled.

The tar file may also contain ordinary files in the directory PACKAGENAME-RELEASENUMBER, and the
installer should *not* copy them to /usr or to /sw.  Examples include README, encapinfo,
postinstall.

A typical package is distributed independently - in the layout below we illustrate the method with
the package "D-modules".

    ./
      bin/
	  M2
      lib/
	  Macaulay2/0.9.4/
			  setup
			  libexec/
				  Macaulay2
			  cache/
				Macaulay2-i686-data	(machine generated)
				Macaulay2-doc
      share/
	    man/
		man1/
		     *.1
		man3/
		     M2::*.3				( man pages for Macaulay 2 subroutines )
	    emacs/site-lisp/
			    M2.el
			    M2-*.el
	    Macaulay2/
		      currentVersion			( a symbolic link to 0.9.4 )
		      0.9.4/
			    m2/
			       *.m2
		      packages/
			       D-modules.m2
			       D-modules/
					 *.m2
	    doc/
		Macaulay2/
			  index.html                    (machine generated)
		          currentVersion		( a symbolic link to 0.9.4 )
			  0.9.4/
				COPYING
				LICENSE
				README
				images/
				       *.gif
				       *.jpg
				html/index.html
				     *.html
				emacs/*
			  packages/
				   D-modules/
					     COPYING
					     LICENSE
					     README
					     images/
						    *.gif
						    *.jpg
					     html/index.html
						  *.html
					     examples/
						      *.m2
						      *.out

This file may get obsolete: the official layout is prescribed in configure.ac at compile time, and
in the hash table LAYOUT at run time.  Here is how to look at the layout inside Macaulay2:

    i2 : LAYOUT

    o2 = HashTable{bin => bin/                                           }
		   cache => lib/Macaulay2/Core/cache/
		   data => share/
		   datam2 => share/Macaulay2/
		   doc => share/doc/
		   docm2 => share/doc/Macaulay2/
		   docm2rel => share/doc/Macaulay2/Core/
		   docpackages => share/doc/Macaulay2/
		   emacs => share/emacs/site-lisp/
		   emacsdoc => share/doc/Macaulay2/Core/emacs/
		   images => share/doc/Macaulay2/Core/images/
		   info => share/info/
		   lib => lib/
		   libm2 => lib/Macaulay2/Core/
		   libraries => lib/Macaulay2/libraries/
		   m2 => share/Macaulay2/Core/m2/
		   man => share/man/
		   man1 => share/man/man1/
		   man3 => share/man/man3/
		   packagecache => --Function[layout.m2:24:36-24:67]--
		   packagedoc => --Function[layout.m2:20:34-20:71]--
		   packageexamples => --Function[layout.m2:25:39-25:76]--
		   packagehtml => --Function[layout.m2:23:35-23:72]--
		   packageimages => --Function[layout.m2:21:37-21:74]--
		   packages => share/Macaulay2/
		   packagesrc => --Function[layout.m2:19:34-19:67]--
		   packagetests => --Function[layout.m2:22:36-22:73]--
		   share => share/Macaulay2/Core/
		   style => share/doc/Macaulay2/Core/style/

    o2 : HashTable

To apply those functions to a sample package name, do this:

    i1 : applyValues(LAYOUT,f -> if instance(f,Function) then f " {* PACKAGE *} " else f)

    o1 = HashTable{bin => bin/                                                     }
		   cache => lib/Macaulay2/Core/cache/
		   data => share/
		   datam2 => share/Macaulay2/
		   doc => share/doc/
		   docm2 => share/doc/Macaulay2/
		   docm2rel => share/doc/Macaulay2/Core/
		   docpackages => share/doc/Macaulay2/
		   emacs => share/emacs/site-lisp/
		   emacsdoc => share/doc/Macaulay2/Core/emacs/
		   images => share/doc/Macaulay2/Core/images/
		   info => share/info/
		   lib => lib/
		   libm2 => lib/Macaulay2/Core/
		   libraries => lib/Macaulay2/libraries/
		   m2 => share/Macaulay2/Core/m2/
		   man => share/man/
		   man1 => share/man/man1/
		   man3 => share/man/man3/
		   packagecache => lib/Macaulay2/ {* PACKAGE *} /cache/
		   packagedoc => share/doc/Macaulay2/ {* PACKAGE *} /
		   packageexamples => share/doc/Macaulay2/ {* PACKAGE *} /examples/
		   packagehtml => share/doc/Macaulay2/ {* PACKAGE *} /html/
		   packageimages => share/doc/Macaulay2/ {* PACKAGE *} /images/
		   packages => share/Macaulay2/
		   packagesrc => share/Macaulay2/ {* PACKAGE *} /
		   packagetests => share/doc/Macaulay2/ {* PACKAGE *} /tests/
		   share => share/Macaulay2/Core/
		   style => share/doc/Macaulay2/Core/style/

    o1 : HashTable