View source for PACKAGE metafiles

{{experimental}}
{{task}}

If you have a folder in the [[ModelLibrary]] (ie you're a developer of ASCEND) then you can add a special file called <tt>PACKAGE</tt> to that folder. This will allow you to specify which files are ready for general consumption. This system allows us to continuously develop new models for ASCEND, while sheltering new users from seeing all the silly things we do, and confusing them with vast swathes of broken or temperamental '''model''' files.

== Specification ==

For the [[ModelLibrary]] and '''all''' its subfolders,

* If you '''don't''' include a <tt>PACKAGE</tt> file in that folder, then all files in that folder will be distributed in our binary distributions.
* If you '''do''' include a <tt>PACKAGE</tt> file in that folder, then only the files that you list will be included in our binary distributions.

The PACKAGE file has the following syntax:

* Comment lines have '#' as their first non-whitespace character, and are ignored.
* Empty (whitespace-only) lines are ignored
* All other lines are expected to contain valid filenames (without directory/path, just the name of the file).

If filenames are contained in the PACKAGE file that do not exist in the current directory, they will be ignored.

Folders named <tt>.svn</tt> and <tt>CVS</tt> are never opened/recursed into.

PACKAGE files '''are''' to be included in the distributed/installed files, as they provide an opportunity to document the contents of a folder and provide a clue to the end user as to which files are likely to be of interest, or the order in which files should be examined (through the use of '#' comment lines).

The filename is in uppercase so that it stands out from the other files. Perhaps it should be named 0PACKAGE so that it appears first in file lists? Normal ASCEND models should have filenames all in lowercase. We must be aware that Windows does not allow distinct files with names differing only in uppercase/lowercase.

== Implementation ==

Currently, the PACKAGE system only applies to Linux binary distributions (RPMs, DEBs). More work is required before it also applies to source code distributions and Windows binary distributions.

We propose to implement a system that allows 'scons installer' (NSIS/Windows only) and the 'scons dist' processes to also make use of the PACKAGE metafiles.

== Example ==

An example of a PACKAGE file is here:

{{src|models/PACKAGE}}


 [[Category:Experimental]]
[[Category:Proposed]]
[[Category:Development]]