3 Packages

GNU Smalltalk includes a packaging system which allows one to file in components (often called goodies in Smalltalk lore) without caring of whether they need other goodies to be loaded first.

The packaging system is implemented by a Smalltalk class, PackageLoader, which looks for information about packages in various places:

• the kernel directory’s parent directory; this is where an installed packages.xml resides, in a system-wide data directory such as /usr/local/share/smalltalk;
• the above directory’s site-packages subdirectory, for example /usr/local/share/smalltalk/site-packages;
• in the file .st/packages.xml, hosting per-user packages;
• finally, there can be a packages.xml in the same directory as the current image.

Each of this directories can contain package descriptions in an XML file named (guess what) packages.xml, as well as standalone packages in files named *.star (short for Smalltalk archive). Later in this section you will find information about gst-package, a program that helps you create .star files.

There are two ways to load something using the packaging system. The first way is to use the PackageLoader’s fileInPackage: and fileInPackages: methods. For example:

    PackageLoader fileInPackages: #('DBD-MySQL' 'DBD-SQLite').
    PackageLoader fileInPackage: 'Sockets'.

The second way is to use the gst-load script which is installed together with the virtual machine. For example, you can do:

    gst-load DBD-MySQL DBD-SQLite DBI

and GNU Smalltalk will automatically file in:

• DBI, loaded first because it is needed by the other two packages
• Sockets and Digest, not specified, but needed by DBD-MySQL
• DBD-MySQL
• DBD-SQLite

Notice how DBI has already been loaded.

Then it will save the Smalltalk image, and finally exit.

gst-load supports several options:

-I

--image-file

Load the packages inside the given image.

-i

--rebuild-image

Build an image from scratch and load the package into it. Useful when the image specified with -I does not exist yet.

-q

--quiet

Hide the script’s output.

-v

--verbose

Show which files are loaded, one by one.

-f

--force

If a package given on the command-line is already present, reload it. This does not apply to automatically selected prerequisites.

-t

--test

Run the package testsuite before installing, and exit with a failure if the tests fail. Currently, the testsuites are placed in the image together with the package, but this may change in future versions.

-n

--dry-run

Do not save the image after loading.

--start[=ARG]

Start the services identified by the package. If an argument is given, only one package can be specified on the command-line. If at least one package specifies a startup script, gst-load won’t exit.

To provide support for this system, you have to give away with your GNU Smalltalk goodies a small file (usually called package.xml) which looks like this:

<package>
  <name>DBD-SQLite</name>
  <namespace>DBI.SQLite</namespace>

  <!-- The prereq tag identifies packages that
       must be loaded before this one. -->
  <prereq>DBI</prereq>

  <!-- The module tag loads a dynamic shared object
       and calls the gst_initModule function in it.  Modules
       can register functions so that Smalltalk code can call them,
       and can interact with or manipulate Smalltalk objects. -->
  <module>dbd-sqlite3</module>

  <!-- A separate subpackage can be defined for testing purposes.
       The SUnit package is implicitly made a prerequisite of the
       testing subpackage, and the default value of namespace
       is the one given for the outer package. -->
  <test>
    <!-- Specifies a testing script that gst-sunit (see SUnit)
         will run in order to test the package.  If this is specified outside
         the testing subpackage, the package should list SUnit among
         the prerequisites. -->
    <sunit>DBI.SQLite.SQLiteTestSuite</sunit>
    <filein>SQLiteTests.st</filein>
  </test>

  <!-- The filein tag identifies files that
       compose this package and that should be loaded in the
       image in this order. -->
  <filein>SQLite.st</filein>
  <filein>Connection.st</filein>
  <filein>ResultSet.st</filein>
  <filein>Statement.st</filein>
  <filein>Row.st</filein>
  <filein>ColumnInfo.st</filein>
  <filein>Table.st</filein>
  <filein>TableColumnInfo.st</filein>

  <!-- The file tag identifies extra files that
       compose this package’s distribution. -->
  <file>SQLiteTests.st</file>
  <file>ChangeLog</file>
</package>

Other tags exist:

url

Specifies a URL at which a repository for the package can be found. The repository, when checked out, should contain a package.xml file at its root. The contents of this tag are not used for local packages; they are used when using the --download option to gst-package.

library

Loads a dynamic shared object and registers the functions in it so that they can all be called from Smalltalk code. The GTK package registers the GTK+ library in this way, so that the bindings can use them.

callout

Instructs to load the package only if the C function whose name is within the tag is available to be called from Smalltalk code.

start

Specifies a Smalltalk script that gst-load and gst-remote will execute in order to start the execution of the service implemented in the package. Before executing the script, %1 is replaced with either nil or a String literal.

stop

Specifies a Smalltalk script that gst-remote will execute in order to shut down the service implemented in the package. Before executing the script, %1 is replaced with either nil or a String literal.

dir

Should include a name attribute. The file, filein and built-file tags that are nested within a dir tag are prepended with the directory specified by the attribute.

test

Specifies a subpackage that is only loaded by gst-sunit in order to test the package. The subpackage may include arbitrary tags (including file, filein and sunit) but not name.

provides

In some cases, a single functionality can be provided by multiple modules. For example, GNU Smalltalk includes two browsers but only one should be loaded at any time. To this end, a dummy package Browser is created pointing to the default browser (VisualGST), but both browsers use provides so that if the old BLOX browser is in the image, loading Browser will have no effect.

To install your package, you only have to do

    gst-package path/to/package.xml

gst-package is a Smalltalk script which will create a .star archive in the current image directory, with the files specified in the file, filein and built-file tags. By default the package is placed in the system-wide package directory; you can use the option --target-directory to create the .star file elsewhere.

Instead of a local package.xml file, you can give:

• a local .star file or a URL to such a file. The file will be downloaded if necessary, and copied to the target directory;
• a URL to a package.xml file. The url tag in the file will be used to find a source code repository (git or svn) or as a redirect to another package.xml file.

There is also a short form for specifying package.xml file on GNU Smalltalk’s web site, so that the following two commands are equivalent:

    gst-package http://smalltalk.gnu.org/project/Iliad/package.xml
    gst-package --download Iliad

When downloading remote package.xml files, gst-package also performs a special check to detect multiple packages in the same repository. If the following conditions are met:

• a package named package has a prerequisite package-subpackage;
• there is a toplevel subdirectory subpackage in the repository;
• the subdirectory has a package.xml file in it

then the subpackage/package.xml will be installed as well. gst-package does not check if the file actually defines a package with the correct name, but this may change in future versions.

Alternatively, gst-package can be used to create a skeleton GNU style source tree. This includes a configure.ac that will find the installation path of GNU Smalltalk, and a Makefile.am to support all the standard Makefile targets (including make install and make dist). To do so, go in the directory that is to become the top of the source tree and type.

    gst-package --prepare path1/package.xml path2/package.xml

In this case the generated configure script and Makefile will use more features of gst-package, which are yet to be documented. The GNU Smalltalk makefile similarly uses gst-package to install packages and to prepare the distribution tarballs.

The rest of this chapter discusses some of the packages provided with GNU Smalltalk.