smalltalkCI

[![GitHub Workflow Status][github_action_b]][github_action_url] [![Coverage Status][coveralls_b]][coveralls_url]

Community-supported framework for testing Smalltalk projects on Linux, OS X, and Windows with built-in support for [GitHub Actions][github_action], [GitLab CI/CD][gitlab_ci_cd], [Travis CI][travisCI], and [AppVeyor][appveyor].

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

[![ESUG][esug_logo]][esug] [![13th Innovation Technology Awards][esug_ita16_b]][esug_ita16]

Table Of Contents

• Features
• How to set up Continuous Integration for your Smalltalk project
• How to test your Smalltalk project locally
• List of Supported Images
• Templates
• Further Configuration
• Contributing
• Projects using smalltalkCI

Features

• Compatible across different Smalltalk dialects (Squeak, Pharo, GemStone)
• Runs on GitHub Actions, GitLab CI, Travis CI, AppVeyor, and other CI services
• Simple configuration via .smalltalk.ston, [setup-smalltalkCI action][github_action], .gitlab-ci.yml, .travis.yml, and appveyor.yml
• Supports Linux, macOS, and Windows and can be run locally (e.g. for debugging purposes)
• Supports [coverage testing][coverage_docs]
• Exports test results in the JUnit XML format as part of the build log

<a name="how-to-ci"/>How To Set Up Continuous Integration For Your Smalltalk Project

1. Export your project in a compatible format (e.g., [Tonel][tonel] or [FileTree][filetree]).
2. Enable a CI service for your repository (e.g., [GitHub Actions][github_actions]).
3. Create a config file for your CI service (see below for templates) and specify the Smalltalk image(s) you want your project to be tested against.
4. Create a .smalltalk.ston file and specify how to load and test your project.
5. Push all of this to your repository and enjoy your fast Smalltalk builds!

<a name="how-to-local"/>How To Test Your Smalltalk Project Locally

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

bin/smalltalkci -s <IMAGE> --headful /path/to/your/project/.smalltalk.ston

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

On Windows, you need to run smalltalkCI from a Bash shell such as [Git Bash][git_bash] or Cygwin, MinGW, or MSYS2.

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.

<a name="images"/>List of Supported Images

| [Squeak][squeak] | [Pharo][pharo] | [GemStone][gemstone] | [Moose][moose] | [GToolkit][gtoolkit] | | ---------------- | ---------------- | -------------------- | --------------- | -------------------- | | Squeak64-trunk | Pharo64-alpha | GemStone64-3.7.x | Moose64-trunk | GToolkit64-release | | Squeak64-6.0 | Pharo64-stable | GemStone64-3.6.x | Moose64-13 | | | Squeak64-5.3 | Pharo64-14 | GemStone64-3.5.8 | Moose64-12 | | | Squeak64-5.2 | Pharo64-13 | GemStone64-3.5.7 | Moose64-11 | | | Squeak64-5.1 | Pharo64-12 | GemStone64-3.5.6 | Moose64-10 | | | Squeak32-trunk | Pharo64-11 | GemStone64-3.5.5 | Moose64-9.0 | | | Squeak32-6.0 | Pharo64-10 | Gemstone64-3.5.4 | Moose64-8.0 | | | Squeak32-5.3 | Pharo64-9.0 | GemStone64-3.5.3 | | | | Squeak32-5.2 | Pharo64-8.0 | | | | | Squeak32-5.1 | Pharo64-7.0 | | | | | Squeak32-5.0 | Pharo64-6.1 | | | | | Squeak32-4.6 | Pharo64-6.0 | | | | | Squeak32-4.5 | Pharo32-alpha | | | | | | Pharo32-stable | | | | | | Pharo32-14 | | | | | | Pharo32-13 | | | | | | Pharo32-12 | | | | | | Pharo32-11 | | | | | | Pharo32-10 | | | | | | Pharo32-9.0 | | | | | | Pharo32-8.0 | | | | | | Pharo32-7.0 | | | | | | Pharo32-6.1 | | | | | | Pharo32-6.0 | | | | | | Pharo32-5.0 | | | | | | Pharo32-4.0 | | | | | | Pharo32-3.0 | | | |

Templates

<a name="minimal-smalltalkston-template"/>Minimal .smalltalk.ston Template

The following SmalltalkCISpec will load BaselineOfMyProject using Metacello/FileTree from the ./packages directory in Squeak, Pharo, and GemStone. See below how you can customize your SmalltalkCISpec.

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

GitHub Action Templates

For GitHub Action templates, please refer to the Marketplace listing of the [setup-smalltalkCI action][github_action].

GitLab CI Template

<details> <summary><code>.gitlab-ci.yml</code></summary>

image: hpiswa/smalltalkci

Squeak64Trunk:
  script: smalltalkci -s "Squeak64-trunk"

Squeak325.1:
  script: smalltalkci -s "Squeak32-5.1"

Pharo64Alpha:
  script: smalltalkci -s "Pharo64-alpha"

Pharo327.0:
  script: smalltalkci -s "Pharo32-7.0"

# ...

</details>

Travis CI Templates

<details> <summary><code>.travis.yml</code></summary>

language: smalltalk
sudo: false

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

# Select compatible Smalltalk image(s)
smalltalk:
  - Squeak64-trunk
  - Squeak64-5.1
  - Squeak32-4.6
  - Squeak32-4.5
  # ...
  - Pharo64-alpha
  - Pharo64-stable
  - Pharo64-7.0
  - Pharo64-6.1
  # ...
  - Pharo32-alpha
  - Pharo32-stable
  - Pharo32-6.1
  # ...
  - GemStone64-3.5.3
  - GemStone64-3.6.0
  - GemStone64-3.6.5
  # ...

# Override `script` to customize smalltalkCI invocation, e.g.:
#script:
#  - smalltalkci .mysmalltalk1.ston
#  - travis_wait smalltalkci .mysmalltalk2.ston

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

</details> <details> <summary><code>.travis.yml</code> with multiple smalltalkCI configurations</summary>

The build matrix can be expanded with multiple smalltalkCI configuration files using the smalltalk_config key:

language: smalltalk
sudo: false

smalltalk:
  - Squeak64-trunk
  - Pharo64-alpha

smalltalk_config:
  - .smalltalk.ston
  - .bleedingEdge.ston

The .bleedingEdge.ston configuration may look like this:

SmalltalkCISpec {
  #loading : [
    SCIMetacelloLoadSpec {
      ...
      #load : [ 'CoreWithExtras' ],
      #version : #bleedingEdge
    }
  ],
  ...
}

Resulting build matrix

| Smalltalk | Config | OS | | ---------------- | -------------------- | ----- | | Squeak64-trunk | .smalltalk.ston | Linux | | Squeak64-trunk | .bleedingEdge.ston | Linux | | Pharo64-alpha | .smalltalk.ston | Linux | | Pharo64-alpha | .bleedingEdge.ston | Linux |

</details> <details> <summary><code>.travis.yml</code> with additional jobs</summary>

It is possible to add additional jobs to the [build matrix][build_matrix_travis] using the smalltalk_config key:

language: smalltalk
sudo: false

os: osx

smalltalk:
  - Squeak32-5.1
  - Pharo32-6.0

matrix:
  include:
    - smalltalk: Squeak64-trunk
      smalltalk_config: .bleedingEdge.ston
    - smalltalk: Pharo64-alpha
      smalltalk_config: .bleedingEdge.ston
  allow_failures: # Allow bleeding edge builds to fail
    - smalltalk_config: .bleedingEdge.ston

Resulting build matrix

| Smalltalk | Config | OS | | ---------------- | -------------------- | ----- | | Squeak32-5.1 | .smalltalk.ston | macOS | | Pharo32-6.0 | .smalltalk.ston | macOS | | Squeak64-trunk | .bleedingEdge.ston | macOS | | Pharo64-alpha | .bleedingEdge.ston | macOS |

</details>

AppVeyor Templates

<details> <summary><code>appveyor.yml</code></summary>

# This is a 64-bit environment, so use 64-bit Cygwin
environment:
  CYG_ROOT: C:\cygwin64
  CYG_BA