smalltalkCI

Community-supported framework for testing Smalltalk projects on Linux & OS X and on Travis CI.

It is inspired by builderCI and aims to provide a uniform and easy way to load and test Smalltalk projects.

Table Of Contents

• Features
• How to enable Travis CI for your Smalltalk project
• How to test your Smalltalk project locally
• List Of Supported Images
• Templates
• Further Configuration
• Contributing
• Projects using smalltalkCI

Features

• Simple configuration via .travis.yml and .smalltalk.ston (see below for templates)
• Compatible across different Smalltalk dialects (Squeak, Pharo, GemStone)
• Runs on Travis' container-based infrastructure ("Builds start in seconds")
• Supports Linux and OS X and can be run locally for debug purposes
• Exports test results in the JUnit XML format as part of the Travis build log
• Supports coverage testing and publishes results to coveralls.io

## How To Enable Travis CI For Your Smalltalk Project

1. Export your project in a compatible format.
2. Enable Travis CI for your repository.
3. Create a .travis.yml and specifiy the Smalltalk image(s) you want your project to be tested against.
4. Create a .smalltalk.ston (see below for templates) and specify how to load and test your project.
5. Push all of this to GitHub and enjoy your fast Smalltalk builds!

## How To Test Your Smalltalk Project Locally

You can use smalltalkCI to run your project's tests locally. Just clone or download smalltalkCI and then you are able to initiate a local build in headfull-mode like this:

/path/to/smalltalkCI/run.sh --headfull /path/to/your/projects/.smalltalk.ston

IMAGE can be one of the supported images. You may also want to have a look at all supported options.

Please note: All builds will be stored in _builds within smalltalkCI's directory. You may want to delete single or all builds if you don't need them as they can take up a lot of space on your drive.

## List Of Supported Images

Squeak	Pharo	GemStone	Others
Squeak-trunk	Pharo-alpha	GemStone-3.3.x	Moose-6.0
Squeak-5.0	Pharo-stable	GemStone-3.2.x
Squeak-4.6	Pharo-6.0	GemStone-3.1.0.x
Squeak-4.5	Pharo-5.0	Gemstone-2.4.x
	Pharo-4.0
	Pharo-3.0

## Templates

.travis.yml Template

language: smalltalk
sudo: false

# Select operating system(s)
os:
  - linux
  - osx

# Select compatible Smalltalk image(s)
smalltalk:
  - Squeak-trunk
  - Squeak-5.0
  - Squeak-4.6
  - Squeak-4.5

  - Pharo-alpha
  - Pharo-stable
  - Pharo-6.0
  - Pharo-5.0
  - Pharo-4.0
  - Pharo-3.0

  - GemStone-3.3.0
  - GemStone-3.2.12
  - GemStone-3.1.0.6

# Uncomment to enable dependency caching - especially useful for GemStone builds (3x faster)
#cache:
#  directories:
#    - $SMALLTALK_CI_CACHE

.travis.yml Template With Multiple Configurations

language: smalltalk
sudo: false

# Select operating system(s)
os: linux

# Select compatible Smalltalk image(s)
smalltalk:
  - Pharo-alpha
  - Pharo-stable

# Loads `.smalltalk.ston` (if it exists), `myconfig1.ston` and `myconfig2.ston`
# **for each build step defined above**:
smalltalk_config:
  - myconfig1.ston
  - myconfig2.ston

.travis.yml Template With Matrix Configuration

language: smalltalk
sudo: false

# Select operating system(s)
os: linux

# Select compatible Smalltalk image(s)
smalltalk:
  - Pharo-alpha
  - Pharo-stable

# Add two **additional** build steps.
# The build steps from above will be run as before with `.smalltalk.ston`.
# See https://docs.travis-ci.com/user/customizing-the-build/#Build-Matrix.
# Loads `.bleedingEdge.ston ` only:
matrix:
  include:
    - smalltalk: Pharo-alpha
      smalltalk_config: .bleedingEdge.ston
      os: linux
    - smalltalk: Pharo-alpha
      smalltalk_config: .bleedingEdge.ston
      os: osx
  allow_failures:
    - smalltalk_config: .bleedingEdge.ston

Minimal .smalltalk.ston Template

The following SmalltalkCISpec will load BaselineOfMyProject using Metacello/FileTree from the ./packages directory in Squeak, Pharo and GemStone.

SmalltalkCISpec {
  #loading : [
    SCIMetacelloLoadSpec {
      #baseline : 'MyProject',
      #directory : 'packages',
      #platforms : [ #squeak, #pharo, #gemstone ]
    }
  ]
}

### Complete `.smalltalk.ston` Template

Please note that the .smalltalk.ston must be a valid STON file. The file can also be called just smalltalk.ston

SmalltalkCISpec {
  #loading : [
    /*
    A list of one or more supported loading specifications (see below).
    */
  ],
  #testing : {
    /*
    By default, smalltalkCI will determine the tests to run from the given LoadSpecs. If this is not
    sufficient, it is possible to define the tests on category-level or class-level in here. With
    `#categories` it is possible to define category names or category prefixes (end with `*`),
    `#classes` expects a list of class name symbols. Both can be specified explicitly (ignore tests
    determined from LoadSpecs completely). If you only want to include or exclude tests from the
    default or `#'*'` case , you can use `#include` or `#exclude`.
    */
    #categories : [ 'MyProject-*' ],                          // Define categories to test explicitly
    #classes : [ #MyProjectTestCase ],                        // Define classes to test explicitly
    #packages : [ 'MyProject.*' ],                            // Define packages to test (Pharo and GemStone)
    #projects : [ 'MyProject' ],                              // Define projects to test (GemStone)
    #'*' : [],                                                // Run all tests in image (GemStone)
    #include : {
      #categories : [ 'AnotherProject-Tests' ],               // Include categories to test
      #classes : [ #AnotherProjectTestCase ],                 // Include classes to test
      #packages : [ 'AnotherProject.*' ],                     // Include packages to test (Pharo and GemStone)
      #projects : [ 'MyProject' ],                            // Include projects to test (GemStone)
    },
    #exclude : {
      #categories : [ 'AnotherProject-Tests' ],               // Exclude categories from testing
      #classes : [ #AnotherProjectTestCase ],                 // Exclude classes from testing
      #packages : [ 'AnotherProject.*' ],                     // Exclude packages from testing (Pharo and GemStone)
      #projects : [ 'MyProject' ]                             // Exclude projects from testing (GemStone)
    }
  }
}

## Compatible Project Loading Specifications smalltalkCI supports different mechanisms for loading a projects. One or more of those loading specifications have to be provided in the `#loading` list as part of a [`SmalltalkCISpec`](#SmalltalkCISpec). smalltalkCI will load all specifications that are compatible with the selected Smalltalk image (specified via `#platforms`).

SCIMetacelloLoadSpec

A SCIMetacelloLoadSpec loads a project either via the specified Metacello #baseline or the Metacello #configuration. If a #directory is specified, the project will be loaded using FileTree/Metacello from the given directory. Otherwise, it will be loaded from the specified #repository.

SCIMetacelloLoadSpec {
  #baseline : 'MyProject',                            // Define MC Baseline
  #configuration : 'MyProject',                       // Alternatively, define MC Configuration
  #directory : 'packages',                            // Path to packages if FileTree is used
  #repository : 'http://smalltalkhub.com/mc/...',     // Alternatively, define MC repository
  #onWarningLog : true,                               // Handle Warnings and log message to Transcript
  #load : [ 'default' ],                              // Define MC load attributes
  #platforms : [ #squeak, #pharo, #gemstone ],        // Define compatible platforms
  #version : '1.0.0'                                  // Define MC version (for MC
                                                      // Configurations only)
}

SCIMonticelloLoadSpec

A SCIMonticelloLoadSpec loads a project with Monticello. It is possible to load the latest version of packages from a remote repository (#packages) or specific versions (#versions).

SCIMonticelloLoadSpec {
  #url : 'http://ss3.gemtalksystems.com/ss/...',      // Define URL for repository
  #packages : ['MyProject-Core', 'MyProject-Tests'],  // Load packages and/or
  #versions : ['MyProject-Core-aa.12'],               // Load specific versions
  #platforms : [ #squeak, #pharo, #gemstone ]         // Define compatible platforms
}

SCIGoferLoadSpec

A SCIGoferLoadSpec works similar to a SCIMonticelloLoadSpec, but uses Gofer on top of Monticello to load a project.

SCIGoferLoadSpec {
  #url : 'http://smalltalkhub.com/mc/...',            // Define URL for repository
  #packages : ['MyProject-Core', 'MyProject-Tests'],  // Load packages and/or
  #versions : ['MyProject-Core-aa.12'],               // Load specific versions
  #platforms : [ #squeak, #pharo, #gemstone ]         // Define compatible platforms
}

Further Configuration

Command Line Options

smalltalkCI has a couple of command line options that can be useful for debugging purposes or when used locally:

USAGE: run.sh [options] /path/to/project/your_smalltalk.ston

This program prepares Smalltalk images/vms, loads projects and runs tests.

OPTIONS:
  --clean             Clear cache and delete builds.
  -d | --debug        Enable debug mode.
  -h | --help         Show this help text.
  --headfull          Open vm in headfull mode and do not close image.
  --install           Install symlink to this smalltalkCI instance.
  -s | --smalltalk    Overwrite Smalltalk image selection.
  --uninstall         Remove symlink to any smalltalkCI instance.
  -v | --verbose      Enable 'set -x'.

EXAMPLE:
  run.sh -s "Squeak-trunk" --headfull /path/to/project/.smalltalk.ston

Travis-specific Options

Jobs on Travis CI timeout if they don't produce output for more than 10 minutes. In case of long running tests, it is possible to increase this timeout by setting $SMALLTALK_CI_TIMEOUT in your .travis.yml to a value greater than 10:

env:
- SMALLTALK_CI_TIMEOUT=30

The above sets the timeout to 30 minutes. Please note that Travis CI enforces a total build timeout of 50 minutes.

Using A Different smalltalkCI Branch Or Fork

By default, the smalltalkCI master branch is used to perform a build. It is possible to select a different smalltalkCI branch or fork for testing/debugging purposes by adding the following to the .travis.yml:

smalltalk_edge:
  source: hpi-swa/smalltalkCI
  branch: dev

Contributing

Please feel free to open issues or to send pull requests if you'd like to discuss an idea or a problem.

Projects Using smalltalkCI

In alphabetical order:

• @Cormas: Cormas.
• @dalehenrich: obex, tode.
• @dynacase: borm-editor, borm-model, borm-persistence, class-editor, demo-editor, dynacase, dynacase-model, fsm-editor.
• @HPI-BP2015H: squeak-parable.
• @HPI-SWA-Teaching: Algernon-Launcher.
• @hpi-swa: animations, Ohm-S, vivide.
• @marianopeck: OSSubprocess, FFICHeaderExtractor.
• @pharo-project: pharo-project-proposals.
• @PolyMathOrg: PolyMath.
• @SeasideSt: Grease.
• @SergeStinckwich: PlayerST.
• @theseion: Fuel.
• @Uko: GitHubcello, QualityAssistant, Renraku.
• @UMMISCO: Kendrick.
• @zecke: osmo-smsc.
• More Projects...

Feel free to send a PR to add your Smalltalk project to the list. Please add [ci skip] to your commit message.