Framework for testing Smalltalk projects with GitHub Actions, GitLab CI, Travis CI, AppVeyor, and others.
# 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](#features)
- [How to set up Continuous Integration for your Smalltalk project](#how-to-ci)
- [How to test your Smalltalk project locally](#how-to-local)
- [List of Supported Images](#images)
- [Templates](#templates)
- [Further Configuration](#further-configuration)
- [Contributing](#contributing)
- [Projects using smalltalkCI](#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`](#minimal-smalltalkston-template),
[`setup-smalltalkCI` action][github_action],
[`.gitlab-ci.yml`](#gitlab-ci-template),
[`.travis.yml`](#travis-ci-template), and
[`appveyor.yml`](#appveyor-template)
- 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](#load-specs) (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](#templates)) and specify the [Smalltalk image(s)](#images) you want your project to be tested against.
4. Create a [`.smalltalk.ston` file](#minimal-smalltalkston-template) 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:
```bash
bin/smalltalkci -s <IMAGE> --headful /path/to/your/project/.smalltalk.ston
```
`<IMAGE>` can be one of the [supported images](#images). You may also want to
have a look at [all supported options](#further-configuration).
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)
```javascript
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>
```yml
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>
```yml
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:
```yml
language: smalltalk
sudo: false
smalltalk:
- Squeak64-trunk
- Pharo64-alpha
smalltalk_config:
- .smalltalk.ston
- .bleedingEdge.ston
```
The `.bleedingEdge.ston` configuration may look like this:
```javascript
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:
```yml
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>
```yml
# This is a 64-bit environment, so use 64-bit Cygwin
environment:
CYG_ROOT: C:\cygwin64
CYG_BA