10:16 p.m.
There have been some developments in the realm of gretl function
packages lately. Jack and I plan to write up a proper guide to all
this, but in the meantime here are a few notes to be going on with.
(References to the gretl GUI below should be understood as valid for
current CVS and snapshots.)
1. The handling of function-package uploads has been revised
Up till now, uploaded packages (whether new ones or revisions of old
ones) have gone straight in to the "public area", where they're
accessible via the gretl GUI and also via the web interface at
http://ricardo.ecn.wfu.edu/gretl/cgi-bin/gretldata.cgi?opt=SHOW_FUNCS
Now, uploads will in the first instance go into a "staging"
directory for approval. When an upload is received, a notification
email gets sent to me. (Once this is tested a bit more I'll put some
more people on the notification list.) Right now, "approval" will
basically just be a matter of checking that the package's sample
script meets the requirements set out in
http://ricardo.ecn.wfu.edu/~cottrell/gretl/gfn-requirements.pdf and
should not take long. The process may be made somewhat more rigorous
in future.
Note that you can see what's in "staging" at
http://ricardo.ecn.wfu.edu/gretl/staging_fnfiles/
2. Packages can now be uploaded in zip-file form
Until recently all regular packages (as opposed to "addons") had to
take the form of simple gfn (XML) files. Now they can be zip files,
allowing the possibility of including extra material in the package.
Examples on the server: HIP.zip (Jack Lucchetti and Claudia Pigini)
and almonreg.zip (not very exciting, written by me as a test case).
The "extra material" we have in mind may include
* PDF documentation
* Zero or more data files (gdt or gdtb)
* Zero or more matrix files
* Zero or more bundle (XML) files
If you include a data file with your package this can be opened in
your sample script using the new --frompkg option to "open", which
requires the name of the package as a parameter; for example
open almon.gdt --frompkg=almonreg
If you include a matrix file (perhaps to hold a bunch of critical
values for a specialized test) you can open it in your function code
using the built-in $pkgdir string variable, as in
string mname = sprintf("%s/critvals.mat", $pkgdir)
matrix C = mread(mname)
A zip-file package must have a definite structure. Let pkgname be a
variable representing the name of your package (e.g. pkgname =
"HIP", pkgname = "almonreg"), and suppose you're including PDF doc
and a data file. The structure must then look like this:
pkgname/pkgname.gfn
pkgname/pkgname.pdf
pkgname/mydata.gdt
That is, all the files must be contained in a directory that bears
the name of your package. The name of the gfn file must be
pkgname.gfn, and the name of the PDF file (if present) must be
pkgname.pdf. Data and matrix files, however, can be named as you
like.
The creation of a suitable zip file is handled by the package editor
in the gretl GUI. (There's also a non-interactive shell-based way of
doing this and uploading the file, but I won't get into that here.)
The trigger for creating a zip file to upload (when you check the
box "Upload package to server on save") is that you have (a)
specified PDF documentation by typing "pdfdoc:pkgname.pdf" into the
Help area in the package editor and/or (b) added the names of some
extra files to include, using the new "Data files" tab in the dialog
which appears when you click the "Extra properties" button in the
package editor.
If you're building your package via a .spec file, the appropriate
magic to put into that file is (illustrating via almonreg):
help = almonreg.pdf
data-files = almon.gdt
(The "data-files" line can accommodate more than one filename,
separated by spaces.)
3. Easier access to sample scripts
In the gretl GUI, there's now an easy way for the "consumer" of a
given function package to bring up and execute its sample script.
When you open the listing of packages on the local machine, there's
both a toolbar button and a right-click (context) menu item, "Sample
script". In the first instance this opens the sample script as
executable but not editable. To make it editable, use the "Save
as..." button and give it a name of your choosing.
Allin