Introduction
Building a product like Squeak, indeed any product of team effort, is as much an exercise in social engineering as it is a technical challenge. Many teams simply use a shared file system, using traditional meetings, documents and emails for communication.
The first challenge of all appears to be getting others to understand what on earth this is all about. There are two possible approaches to doing this, the top down or bottom up.
Top Down
We have a system, which I have called, for want of a better name, 'auto-build'. What does it do, well it watches a website, and when you change a page it notices by watching the rss feed from that site, and runs a script. That script does some stuff. The stuff could be anything, but we want it to give us a fully tested and working squeak image.
Auto
Lets look at an example, here is a page, Make 391 if you edit it, the 'auto-build' server will notice and 'do some stuff'. What stuff does it do? Well in this case, 'auto-build' hunts through its available scripts and finds two which are appropriate for Make 391, it runs both.
- each.page.action.rb
- make(any).action.rb
each.page.action.rb simply collects every page that changes and keeps a local copy in its site-mirror folder so that the 'auto-build' server has at its disposal a snapshot of the current state of the website. You can write your own scripts to do whatever you want, each.page.action is a simple one, its code reads:
($site_mirror / $thisPage.title + '.html') < $thisPage.content
So thats how the 'auto' part in the 'auto-build' works. You edit a page, and 'auto' runs a script.
Build
So what about the other script, make(any).action.rb, this runs whenever you change a page prefixed 'make'. This script does 'stuff' too, but it does stuff with Squeak.
In order to know what 'stuff' to do, it grabs the raw text of the page that you edited (An Example) and uses that to obtain its build instructions.
It prepares a working area, obtains a squeak image, finds the requested vm, and runs squeak from the command-line with the parameters listed, and when complete, it copies any useful files to the designated output folder on the webserver... bob is your uncle.
The details of format and content of the instructions that 'make' uses can be found on its documentation page Make(any)-action.
Squeak
When Make(any)-action runs it passes parameters on the command-line to squeak to do its 'stuff'. This is the point where the 'top down' explanation meets the bottom up explanation...
Installing With Installer
Many of the tools in Squeak used for installing packages, and changesets, are far from simple. Each has its own way of working. Installer is just a front end to the other tools, but it has some useful features of its own. Installer's key features are:
- Installing monticello packages
- Installing squeakmap packages
- Installing changesets uploaded to mantis bug reports
- Running scripts embedded in web page documentation
Installer accesses its scripts via a url, and so it can perform actions defined in local files too, via a file: url.
The point being that Installer can refer back to the wiki that we started from, and find its instructions there, as in the Make 391 example which begins at From39To391.
Installer is instucted where to look and where to begin, by the information in the original Make 391 page that was edited. A detailed explanation follows:
Feeding Make(any)-action
We tell Make(any)-action about the deliverable, and how it is to be created using a make_info_file containing a simple record format based upon yaml, a minimal and readable markup syntax.
A typical make_info_file with information for make is shown below. This example contains a series of key-value pairs, and one list with three items:
The example contains two records, for two builds, the second record inherits all of its data from the first record, only the data which has changed need be provided in subsequent records. The build number is incremented automatically, unless overriden.
This example shows some clever features of Make(any)-action, it can obtain the starting image from the url of any zip file it is given, caching the obtained image in its local collection.
Of course the really clever, actually useful, thing is that Make(any)-action invokes Squeak with whatever parameters you supply in the make_info_file. This means that you can install things with Installer, test things with TestRunner, and generate reports from SystemNavigation, or any other task/class that you can come up with and give a #launchWith: method.
Make(any)-action from the commandline
Make(any)-action] can also be run from the commandline
e.g.
#./action.scripts/make(any).action.rb url make_info_file.yaml
As you can see, Make(any)-action can obtain its instructions from a local file, or any remote web page it is pointed at. e.g.
#./action.scripts/make(any).action.rb url "http://squeak310.pbwiki.com/Make 391?raw=2"
Testing With Tester
TestRunner and TextRunner (TextRunner is a simpler text-only limited UI version of TestRunner) provide our testing tools. All we have to do is tell them which suites of tests to run. They can produce their results in a log file, which can be subsequently viewed or processed further. Of course a complete test run may take some time, so it may be useful to categorise the tests so that those results required fastest are run first.
To do this we can add the following to the make parameters
When processing the parameter list from the command line, or via Make(any)-action's make_info_file, SmalltalkImage provides a simple interface to instruct squeak to save the image at strategic points, as requested, or simply to quit. The default behaviour is to save and quit, to override this place the following in the parameters
Generate a report on an image contents, then you can use standard command-line diff tools to see what has changed between images of any origin, from one build to the next, or one release to the next. To invoke this from 'make' add the following to the parameters
- SystemNavigation
- report=imageContents
- to=contents.txt
Logging With Logger
Squeak has no standard Logging system as yet. But if it were present you would be able to configure it from the off like so:
Running A Server
When images are to be used as a server. The users have to start the server manually, save the image, and then restart the image with the server already running. Simply adding launchWith: to a server class such as WAKom, enables the server to be started from the commandline on the port of choice. When building an image in which you wish the server to be pre-started, add the following to the 'make' parameters.
Conclusion
The 'auto-build' system is specifically designed as a loose assembly of useful tools. Like pen and paper, each of which have little in common, when combined can achieve greater things.
The system is not prescriptive, of form or process, it simply provides enough interworking between all of the pieces to get stuff done. What stuff you do, and how you do it, is up to you.
-- Keith
Comments (0)
You don't have permission to comment on this page.