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 section 3.7 The SUnit testing package) 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.

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.

3.1 GTK and VisualGST
3.2 The Smalltalk-in-Smalltalk library
3.3 Database connectivity
3.4 Internationalization and localization support
3.5 The Seaside web framework
3.6 The Swazoo web server
3.7 The SUnit testing package
3.8 Sockets, WebServer, NetClients
3.9 An XML parser and object model for GNU Smalltalk
3.10 Other packages