Proposed policy for stellar astronomy data packages and programs in Debian ----------------------------------------------------------------------- Rationale: Debian provides a number of astronomy related packages that make use of sometimes overlapping stardata catalogues. However, in some situations, the data format in use differs between them. The goal of the stardata-common framework is to provide package maintainers an infrastructure that can be used by astronomy packages and stardata catalogs in order to allow for a tighter integration between them. This allows catalogs to be removed from astronomy packages to avoid redundancy and inclusion of architecture-independent data in binary packages. Since some star data catalogs are non-free, this separation also provides a way to have packages that can make use of that data (but do not depend on an explicit catalog being available) available in the main archive. -- Kevin McCarty Francisco García Javier Fernández-Sanguino Peña 29 Jul 2005 1. stardata-common package -------------------------- It is assumed that there exists a stardata-common Debian package, containing this policy and a program /usr/sbin/register-stardata. The register-stardata program accepts arguments in the format register-stardata where is one of {install,remove}, is the name of a stardata catalog, or "all" for all the stardata available, and is the name of a astronomy package, or "all". Both and may not be "all" simultaneously. The stardata-common package also contains a directory /usr/lib/stardata-common which will be populated with executable scripts by astronomy program packages (see section 3 below). - When neither nor is "all", register-stardata executes the script /usr/lib/stardata-common/ with the arguments . - When is "all", register-stardata executes every script in the directory /usr/lib/stardata-common with arguments . - When is "all", register-stardata executes the script /usr/lib/stardata-common/ with the arguments repeatedly for each in the /usr/share/stardata directory. 2. Star data packages --------------------- A. Package relationships Each star data package should be named stardata-, e.g., stardata-gliese, to make it easy for users to find them. (This need only apply to the binary Debian package name, not the source package.) Each data package should at least Suggest the package stardata-common. Each data package should be in the appropriate section: one of science, contrib/science, non-free/science. B. Installation scripts The postinst of each star data package, when called with "install" or "upgrade", must execute the line /usr/sbin/register-stardata install all The prerm, when called with "remove", "upgrade", or "deconfigure", must execute the line /usr/sbin/register-stardata remove all If the package only Suggests or Recommends stardata-common, then the line must be protected by surrounding it with if [ -x /usr/sbin/register-stardata ] ; then ... fi C. Package contents The actual ASCII data file must be named /usr/share/stardata//catalog.dat (with a symlink, if desired). If there are multiple data catalogs with the same format, for instance one catalog for each hour of right ascension, they must be named such that the glob /usr/share/stardata//catalog*.dat expands into the name of all catalogs in the correct order. The recommended naming scheme is catalog1.dat ... catalog9.dat (for two to nine catalogs) catalog01.dat ... catalog99.dat (for 10 to 99 catalogs) etc. Again, this may be done via symlinks if desired. Note that this naming scheme permits the use of catalogue.dat instead of catalog.dat if desired :-) Each star data package should put any additional upstream materials in /usr/share/stardata// or subdirectories thereof (for data and descriptions of data format); or in /usr/share/doc// (for READMEs, copyrights, etc.) Star data packages should not include or rely upon any scripts specific to a single astronomy software package; those scripts should instead be included in the software package. 3. Stellar astronomy software packages -------------------------------------- A. Package relationships Each program that can use a star data catalog must at least Suggest stardata-common. Each program that can use a star data catalog must at least Suggest the appropriate data package. If the program fails to run when the data catalog is not found, of course it must use the Depends relationship. Therefore any program that requires a non-free data file to run must itself be in contrib or non-free. Each program should be in the appropriate section: one of science, contrib/science, non-free/science. B. Installation scripts The postinst of each astronomy software package, when called with "install" or "upgrade", must execute the line register-stardata install all The prerm, when called with "remove", must similarly execute the line register-stardata remove all If the package only Suggests or Recommends stardata-common, then the line must be protected by surrounding it with if [ -x /usr/sbin/register-stardata ] ; then ... fi C. Software use of data files Each policy-conforming program must ship with an executable script /usr/lib/stardata-common/, conforming to the following: 1) If called with the arguments "install ", the script must do whatever is necessary to convert the file(s) /usr/share/stardata//catalog*.dat into a form that can be used by the program with as little configuration as possible required by the local user or admin. a) If the program can use the data file directly, the script should drop a symlink into the location where the program normally looks for data files, pointing at the file in question. b) If the program can use the data file only after some preprocessing, the script should store the post-processed output into some appropriate location, e.g., /var/lib//., where is a program-dependent suffix. The script may print some output indicating what it is doing. The script should also drop a symlink into the location where the program normally looks for data files, pointing at the post-processed file in question. The software package must include any related programs and data used by the script. In the case of starplot, for instance, this includes the starconvert binary and any *.spec files used by it. c) If the program cannot use the data file (for instance, no post- processing script has been written for it yet), or if no files matching the pattern /usr/share/stardata//catalog*.dat exist, the script must do nothing and exit normally (with 0 exit status). 2) If called with the arguments "remove ", the script must revert all changes made by calling it with the arguments "install ". That is, it must delete all created symlinks and post-processed files related to the given catalog, even if the star data package itself is no longer installed. If the program cannot use the specified catalog, the script must do nothing and exit normally. 3) The script must be idempotent: calling it a second time with the same arguments must result in no non-trivial changes occurring.