[Stardata-common-devel] stardata-common policy
Kevin B. McCarty
kmccarty at Princeton.EDU
Fri Jul 29 17:42:15 UTC 2005
I was going to just edit for typos in the stardata-common policy, but I
found some more substantial things that I thought needed to be changed
based on the final register-stardata implementation. Attached please
find a revised version as well as a wdiff from the last version to my
suggested revisions.
Please let me know your thoughts.
--
Kevin B. McCarty <kmccarty at princeton.edu> Physics Department
WWW: http://www.princeton.edu/~kmccarty/ Princeton University
GPG: public key ID 4F83C751 Princeton, NJ 08544
-------------- next part --------------
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.
-- Francisco GarcÃa
Kevin McCarty
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 <action> <catalog> <program>
where <action> is one of {install,remove}, <catalog> is the name of
a stardata catalog, or "all" for all the stardata available, and <program>
is the name of a astronomy package, or "all". Both <program> and <catalog>
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 <catalog> nor <program> is "all", register-stardata executes
the script /usr/lib/stardata-common/<program> with the arguments
<action> <catalog>.
- When <program> is "all", register-stardata executes every script in
the directory /usr/lib/stardata-common with arguments <action> <catalog>.
- When <catalog> is "all", register-stardata executes the script
/usr/lib/stardata-common/<program> with the arguments <action> <datadir>
repeatedly for each <datadir> in the /usr/share/stardata directory.
2. Star data packages
---------------------
A. Package relationships
Each star data package should be named stardata-<catalog>, 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 <catalog> all
The prerm, when called with "remove", "upgrade", or "deconfigure", must
execute the line
/usr/sbin/register-stardata remove <catalog> 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>/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>/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/<catalog>/ or subdirectories thereof (for data and
descriptions of data format); or in /usr/share/doc/<packagename>/
(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 <astronomy-package>
The prerm, when called with "remove", must similarly execute the line
register-stardata remove all <astronomy-package>
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/<program>, conforming to the following:
1) If called with the arguments "install <catalog>", the script must do
whatever is necessary to convert the file(s)
/usr/share/stardata/<catalog>/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/<program>/<catalog>.<ext>, where <ext> 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>/catalog*.dat exist, the script
must do nothing and exit normally (with 0 exit status).
2) If called with the arguments "remove <catalog>", the script must
revert all changes made by calling it with the arguments "install <catalog>".
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.
-------------- next part --------------
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 [-infraestructure-] {+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.
{+-- Francisco GarcÃa
Kevin McCarty
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 <action> <catalog> <program>
where <action> is one of {install,remove}, <catalog> is the name of
a stardata catalog, or "all" for all the stardata available, and <program>
is the name of a astronomy package, or "all". {+Both <program> and <catalog>
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). [-Except that it may also do argument
validation,-]
{+- When neither <catalog> nor <program> is "all", register-stardata executes
the script /usr/lib/stardata-common/<program> with+} the {+arguments
<action> <catalog>.
- When <program> is "all",+} register-stardata [-program should be functionally equivalent
to a-] {+executes every+} script [-whose contents are:
#!/bin/sh
exec run-parts --arg="$1" --arg="$2"-] {+in
the directory+} /usr/lib/stardata-common {+with arguments <action> <catalog>.
- When <catalog> is "all", register-stardata executes the script
/usr/lib/stardata-common/<program> with the arguments <action> <datadir>
repeatedly for each <datadir> in the /usr/share/stardata directory.+}
2. Star data packages
---------------------
A. Package relationships
Each star data package should be named stardata-<catalog>, 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 [-Provide the virtual package stardata-catalog
and must Depend on-] {+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 <catalog> all
{+The prerm, when called with "remove", "upgrade", or "deconfigure", must
execute the line
/usr/sbin/register-stardata remove <catalog> 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>/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>/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/<catalog>/ or subdirectories thereof (for data and
descriptions of data format); or in /usr/share/doc/<packagename>/
(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 [-Depend upon or
Recommend-] {+at least Suggest+}
stardata-common.
Each program that can use a star data catalog must [-Depend upon, Recommend
or-] {+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 <astronomy-package>
The prerm, when called with "remove", must similarly execute the line
register-stardata remove all <astronomy-package>
[-The format and behavior of-]
{+If+} the [-/etc/stardata.d/<program> script are
described below.-] {+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
[-/etc/stardata.d/<program>,-]
{+/usr/lib/stardata-common/<program>,+} conforming to the following:
1) [-Since it is a conffile, it must deal with the case when its owning
package has been uninstalled by immediately exiting with normal (zero)
status. For instance, "test -x /usr/bin/starplot || exit 0".
2)-] If called with the arguments "install <catalog>", the script must do
whatever is necessary to convert the file(s)
/usr/share/stardata/<catalog>/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/<program>/<catalog>.<ext>, where <ext> 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>/catalog*.dat exist, the script
must do nothing and exit normally (with 0 exit status).
2) If called with the arguments "remove <catalog>", the script must
revert all changes made by calling it with the arguments "install <catalog>".
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.
More information about the Stardata-common-devel
mailing list