LinuxCommandLibrary

smalltalkci

Run Smalltalk Continuous Integration builds

TLDR

Run tests for a configuration file

$ smalltalkci [path/to/.smalltalk.ston]
copy

Run tests for the .smalltalk.ston configuration in the current directory
$ smalltalkci
copy

Debug tests in headful mode (show VM window)
$ smalltalkci --headful
copy

Download and prepare a well-known smalltalk image for the tests
$ smalltalkci --smalltalk [Squeak64-Trunk]
copy

Specify a custom Smalltalk image and VM
$ smalltalkci --image [path/to/Smalltalk.image] --vm [path/to/vm]
copy

Clean up caches and delete builds
$ smalltalkci --clean
copy

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.

SEE ALSO

git(1), make(1), travis(1), gh(1)

Copied to clipboard