smalltalkci
Run Smalltalk Continuous Integration builds
TLDR
Run tests for a configuration file
Run tests for the .smalltalk.ston configuration in the current directory
Debug tests in headful mode (show VM window)
Download and prepare a well-known smalltalk image for the tests
Specify a custom Smalltalk image and VM
Clean up caches and delete builds
SYNOPSIS
smalltalkci [global_options] command [command_options]
smalltalkci test [--image IMAGE_NAME] [--baseline BASELINE_NAME] [--dir PATH] ...
smalltalkci build [--image IMAGE_NAME] [--baseline BASELINE_NAME] [--dir PATH] ...
smalltalkci install [--image IMAGE_NAME] [--dir PATH] ...
smalltalkci load [--image IMAGE_NAME] [--baseline BASELINE_NAME] [--dir PATH] ...
smalltalkci run [--image IMAGE_NAME] [--script SCRIPT_PATH] [--dir PATH] ...
PARAMETERS
--image
Specifies the Smalltalk image name and version to use (e.g., Pharo-8.0).
--headless
Runs the Smalltalk VM in headless (non-GUI) mode, suitable for CI environments.
--baseline
Defines the Metacello baseline to load or test within the Smalltalk image.
--dir
Sets the working directory for the Smalltalk project. Defaults to the current directory.
--cache-dir
Specifies the directory where Smalltalk images and VMs are cached.
--vm
Provides an explicit path to the Smalltalk VM executable.
--fail-on-warnings
Causes the command to exit with an error code if warnings are encountered during execution.
--ci
Enables CI-specific behaviors, often suppressing interactive prompts.
--version
Displays the smalltalkci tool's version information.
--verbose
Increases the verbosity of the output, showing more details about the execution.
--no-cache
Prevents the use of cached images or VMs, forcing a fresh download.
--github-token
Provides a GitHub token for accessing private repositories or increasing API limits.
DESCRIPTION
smalltalkci is a command-line interface (CLI) tool designed to streamline the continuous integration (CI) and build processes for Smalltalk projects. It automates common tasks such as running tests, loading project code, and managing Smalltalk virtual machine (VM) images. By providing a unified interface for various Smalltalk dialects (primarily Pharo, Squeak, and GemStone/S), it allows developers to integrate Smalltalk development seamlessly into CI pipelines like GitHub Actions, Travis CI, Jenkins, and GitLab CI. The tool handles the complexities of downloading and caching Smalltalk images and VMs, loading project baselines (often via Metacello), executing tests, and producing consistent results, making it an essential utility for modern Smalltalk development teams adopting automated testing and deployment workflows. It simplifies the setup required for testing across different Smalltalk versions and environments.
CAVEATS
Requires an internet connection for initial image/VM downloads.
Relies on Metacello for project loading; projects must be properly configured.
Can consume significant disk space due to cached images and VMs.
VM and image compatibility: Ensure the specified Smalltalk image is compatible with the underlying VM.
SUPPORTED SMALLTALK DIALECTS
smalltalkci primarily supports Pharo, Squeak, and GemStone/S Smalltalk images. Users specify the desired image via the --image option (e.g., Pharo-10.0, Squeak-5.3). The tool intelligently downloads and manages the appropriate VM and image for the specified dialect and version.
CONFIGURATION FILES
While smalltalkci is primarily controlled via command-line arguments, some advanced configurations or default settings can be managed through environment variables or a .smalltalkci configuration file in the project's root directory, allowing for project-specific overrides.
EXIT CODES
smalltalkci returns standard Unix-like exit codes: 0 for success, non-zero for failures. Specific non-zero codes often indicate different types of errors, such as test failures, build errors, or configuration issues, which is crucial for CI pipeline integration.
HISTORY
smalltalkci emerged from the need to standardize and simplify the continuous integration process for Smalltalk projects. Prior to its development, setting up CI for Smalltalk often involved complex shell scripts tailored to specific Smalltalk dialects and CI systems. It was primarily developed by members of the Hasso Plattner Institute (HPI) Software Architecture Group (SWA) and the Pharo community, aiming to provide a robust, cross-platform solution. Its design principles emphasize ease of use, caching, and compatibility with popular CI services, addressing common challenges like managing different Smalltalk image versions and ensuring consistent test environments. It gained prominence as Smalltalk development embraced modern CI/CD practices.