Unix Squeak - Development
[ home | download/install | problems/bugs | developers | archives | goodies | resources | site stats | more stats ]

1   Building the Virtual Machine from Source Code
    1.1   Configuring the Build Environment
    1.2   Building and Installing

2   Pre-loaded VMMaker Image

3   Writing Your Own Plugins
    3.1   Plugins Written in Squeak
    3.2   Plugins Written by Hand
    3.3   External Plugins
    3.4   Specialising configure and/or Makefile

 1. Building the Virtual Machine from Source Code

If you want to compile the Squeak VM for yourself (or add plugin modules containing your own ``named primitives'') then you need to download the sources for the virtual machine. The sources change with each minor release. They are provided in a single tar file that when extracted will place the sources in a subdirectory named simply by the Squeak version number to which they correspond:

Squeak-3.11.3.2135-src.tar.gz
After extracting this archive you should have a source tree which looks like this: 
Squeak-3.11.3.2135/
  src/              sources generated by VMMaker
    vm/             sources needed by the ``core'' virtual machine
    plugins/        sources needed by individual plugins
  platforms/        hand-written platform support code
    Cross/          code common to all architectures
      vm/           sources needed by the ``core'' virtual machine
      plugins/      sources needed by individual plugins
    unix/           code specific to the Unix platform
      cmake/        files related to configuration and build
      vm/           sources needed by the ``core'' virtual machine
      plugins/      sources needed by individual plugins
      doc/          documentation

1.1. Configuring the Build Environment

``Configuring'' refers to the detection of your platform's characteristics (byte order, header files, libraries, install locations, etc.). This is done automatically by a script called `configure' which is located in the platforms/unix/cmake directory. You run this script from the directory in which you want to perform the actual build. (This ``build directory'' should not be one of the above source directories. Although there's nothing in the build process that prevents this from working, you'll have a hard time cleaning up afterwards if you build in one of the source dirs directly.)

A typical archive extraction and configuration might look like this: 

$ gzip -dc Squeak-3.11.3.2135.tar.gz | tar xfBp -
$ cd Squeak-3.11.3.2135
$ mkdir build
$ cd build
$ ../platforms/unix/cmake/configure
The configure script accepts various arguments. (Run it with the argument `--help' to see the complete list.) The most useful argument is `-prefix path' which tells configure that you want to install everything under path instead of the default /usr/local.

1.2. Building and Installing

To build everything just run: 

make
If you want to build only the VM, run: 
make squeak
If you want to build only the external plugins, run: 
make plugins

Once built you can install the VM and/or external plugins like this: 

$ make install            install everything

 2. Pre-loaded VMMaker Image

Several people seem to be having problems creating an image capable of generating a reliable set of interp/plugin sources. This is more than understandable since it is necessary to load half a dozen packages and several non-packaged changesets to arrive at a healthy VM-generating image.

As a service to homebrew VM hackers I've decided to make available the image from which I generate the official Unix VM source and binary releases.

unix-3.11.3.2135-vmm.tar.gz

Once you've fixed the paths in the VMMakerTool window you should be able to hit "generate all" to reproduce verbatim the contents of the "src" subdirectory that is in my source release.

 3. Writing Your Own Plugins

The build environment tries to handle plugins automagically. In the vast majority of cases, all you'll need to do is to add the relevant .c files in the right place.

3.1. Plugins Written in Squeak

If your plugin is written entirely in Squeak and then translated by VMMaker, all you have to do is generate the sources for it and then rerun the Unix `configure' script (once, after you generate the plugin source for the very first time) followed by `make' (each time you regenerate the source, obviously).

3.2. Plugins Written by Hand

If your plugin requires no special configuration information (tests for libraries, etc.) and no special treatment in its Makefile then just placing the hand-written .c and .h files in the platforms/Cross/YourPlugin directory should cause a suitable Makefile to be generated for it automatically.

Note: you will also have to create a ``stub'' plugin class in the image (giving the Squeak-side interface to the primitives) and then generate source for the stubs with VMMaker. After doing this for the first time you will have to rerun `configure' (or just rerun `config.status') so that the build process notices the existence of the new plugin.

3.3. External Plugins

If you configure (in VMMaker) your plugin as ``external'' then you don't have to recompile the entire VM to build the corresponding library. After following the appropriate steps as described above, type 

make plugins
to build just the external plugins.

To test the new plugin (without installing it) you will have to tell the VM where to look for it. Relative to the build directory, plugins are built as: 

PluginName/.libs/PluginName.so
The VM will add the final PluginName.so by itself, but it doesn't know to add the PluginName and .libs prefixes. The command-line option 
-plugins path
tells it to do this. path is a path (absolute or relative) to the directory in which the VM should look for plugins. All occurences of ``%n'' within path are replaced with the name of the plugin being loaded. For example, runing Squeak from within the build directory, you will have to use something like this: 
squeak -plugins '%n/.libs' pathToImage
(Prepend additional path components as appropriate if you launch Squeak from outside the build directory.)

3.4. Specialising configure and/or Makefile

A plugin can add configuration steps to configure and/or modify the Makefile that is generated for it. A full treatment of the build process and the ``personalisation'' mechanisms available to plugins are described in the separate document ``How to Build from Source''.

[ home | download/install | problems/bugs | developers | archives | goodies | resources | site stats | more stats ]