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 files that
compose this package's distribution. -->
<file>SQLite.st</file>
<file>Connection.st</file>
<file>ResultSet.st</file>
<file>Statement.st</file>
<file>Row.st</file>
<file>ColumnInfo.st</file>
<file>Table.st</file>
<file>TableColumnInfo.st</file>
<!-- Test files or extra files can also be included. -->
<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
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 to download a `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.
This document was generated
on August, 19 2010
using texi2html