HPI-BP2015H / smalltalkCI

Community-supported framework for building Smalltalk projects on Travis CI (continuous integration) infrastructure.

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
• Compatible Project Loading Formats
• 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 like this:

/path/to/smalltalkCI/run.sh --headfull -s IMAGE /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
Squeak-trunk	Pharo-alpha	GemStone-3.3.0
Squeak-5.0	Pharo-stable	GemStone-3.2.12
Squeak-4.6	Pharo-5.0	GemStone-3.1.0.6
Squeak-4.5	Pharo-4.0
	Pharo-3.0

## Compatible Project Loading Formats

• FileTree/Metacello Baseline or Configuration (Git-compatible)
• More to follow...

## 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-5.0
  - Pharo-4.0
  - Pharo-3.0

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

# Uncomment to specify one or more custom smalltalkCI configuration files (.smalltalk.ston by default)
#smalltalk_config: .myconfig.ston
#  or
#smalltalk_config:
#  - myconfig1.ston
#  - myconfig2.ston

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

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 : [
    /*
    There can be multiple LoadSpecs in `#loading`. `smalltalkCI` will load all LoadSpecs 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`.
      */
      #baseline : 'MyProject',                                // Define MC Baseline
      #configuration : 'MyProject',                           // Alternatively, define MC Configuration
      #directory : 'tests',                                   // Path to packages if FileTree is used
      #repository : 'http://ss3.gemtalksystems.com/ss/...',   // 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)
    }
  ],
  #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)
    }
  }
}

Further Configuration

smalltalkCI supports a couple of 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

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.
• @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.