PACKAGE metafiles

From ASCEND
Jump to: navigation, search
This page documents an experimental feature. Please tell us if you experience any problems.
This article is about planned development or proposed functionality. Comments welcome.

If you have a folder in the ModelLibrary (ie you're a developer of ASCEND) then you can add a special file called PACKAGE 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 PACKAGE file in that folder, then all files in that folder will be distributed in our binary distributions.
  • If you do include a PACKAGE 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 .svn and CVS 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:

models/PACKAGE