This is the README for the Cog Git source tree: https://github.com/OpenSmalltalk/opensmalltalk-vm

Builds are tested automatically on each commit, for Windows, macOS, and Linux. Windows and Linux also have 32-bit targets. Squeak and Pharo VMs are built with and without JIT, with and without Spur, and with and without Sista, as available per platform. All build artifacts remain accessible for 90 days for each workflow run; the latest artifacts are uploaded to a dedicated release tag (e.g., "latest-build"), overwritten with each successful run. If you wish to commit without triggering a build, for example if you were to only edit this documentation, then if you add [ci skip] somewhere in your commit message, no workflow run will be started for that commit.

We rely on source file substitutions in the src tree, specifically, any sq*SCCSVersion.h files anywhere in the tree are processed to replace $Rev$, $Date$, and $URL$ with the current revision (defined as the timestamp %Y%m%d%H%M of the latest commit), the human readable date of that commit, and the url of the origin repository these sources were cloned from.

The first time you clone this repository, you must therefore run this command:

This will install filters, post-commit, and post-merge hooks to update the sq*SCCSVersion.h files anytime you commit or merge.

For easier use, we include the scripts/gitci and scripts/gitciplugins scripts to commit changes to this branch and changes to the Cross and win32 plugins (which are shared with the old Squeak interpreter trunk). If you decide not to use these scripts for checking in sources, you should also run the updateSCCSVersions script anytime you decide to use git-reset or git-checkout to make sure the stamps are updated correctly. Failing to do so will result in incorrect version stamps in your compiled VMs.

• Overview
• Variants
• VM source directories
• Platform build directories
• Other directories (platforms, processors, deployment, image)

First, opensmalltalk-vm (a.k.a. the Cog VM) is the virtual machine beneath the Cuis and Squeak Smalltalk dialects. For issues related to these systems that are unrelated to the VM itself, please use their forums:

• https://cuis.st/community
• https://squeak.org/community

Note that we dropped support for Newspeak and Pharo VM flavors in August 2025. The last working sources can be found in the tags last-support-newspeak and last-support-pharo.

Second, the core VM, which comprises the execution engine and garbage collector, and the core plugins, is developed in Smalltalk, using the VM Simulator. This repository contains the code generated by the Simulator, and the platform support code for the entire VM, its CI infrastructure and so on. The core VM should not be developed by editing the generated code. The core VM should be developed using Smalltalk. The source code repository for the VM is
http://source.squeak.org/VMMaker.html.
You can find scripts to build a Smalltalk image in which to do core VM development in the image directory in this repository. You can read about the Simulator here:

• https://www.researchgate.net/publication/328509577_Two_Decades_of_Smalltalk_VM_Development_Live_VM_Development_through_Simulation_Tools

Cog is an evolution of the Squeak Back-to-the-future Smalltalk virtual machine that provides a number of different Smalltalk virtual machines. The VMs are developed in Smalltalk, using all the dynamic and reflective facilities of the Squeak Smalltalk system. As such, developing in Cog is a delight. The Smalltalk framework comprising the various Cog VMs is translated into C by its Slang component to produce VM source that is combined with platform-specific support sources and compiled via a C compiler to obtain a fast production VM. This directory tree includes the output of Slang for various configurations of "Cog VM" along with the associated platform support code, plus build directories that can be used to produce production VMs.

This directory tree also includes a directory containing scripts that can be used to create an instance of the Smalltalk Cog development system, suitable for developing the VM in Smalltalk, and for generating new VM sources. See the image subdirectory, described below.

The "Cog VM" comes in a bewildering variety of forms. The first distinction is between Stack, Cog and Sista VMs. Stack VMs are those with context-to-stack mapping that optimise message sending by keeping method activations on a stack instead of in contexts. These are pure interpreters but are significantly faster than the standard context-based Interpreter VM. Cog VMs add a JIT to the mix, compiling methods used more than once to machine code on the fly. Sista VMs, as yet unrealised and in development, add support for adaptive optimization that does speculative inlining at the bytecode-to-bytecode level.

Another distinction is between "v3" VMs and Spur VMs. "v3" is the original object representation for Squeak as described in the back-to-the-future paper. Spur, as described on the www.mirandabanda.org blog, and in the paper "A partial read barrier for efficient support of live object-oriented programming" by Miranda & Bera, is a faster object representation which uses generation scavenging, lazy forwarding for fast become, a single object header format common to 32 and 64 bit versions, and a segmented heap that can grow and shrink, releasing memory back to the host OS. Squeak 5.0, Cuis 5 and Pharo 5 and subsequent releases use Spur.

Another distinction is between normal single-threaded VMs that schedule "green" Smalltalk light-weight processes above a single-threaded VM, and multi-threaded VMs that share the VM between any number of native threads such that only one native thread owns the VM at any one time, switching between threads on FFI calls and callbacks or on Smalltalk process switches when Smalltalk processes are owned by threads. This architecture offers non-blocking FFI calls and interoperability with multiple native threads, but does /not/ provide true concurrency. This multi-threaded support is as yet experimental.

The Slang output of the various VMs are kept in "vm source" directories. These C sources define the core VM (the Smalltalk execution engine and the memory manager), and a substantial set of "plugins" that provide interfaces to various external facilities via Smalltalk primitive methods. Each vm source directory is specific to a particular VM, be it Squeak Cog Spur, or V3 Stack, etc. The plugins can be shared between VMs, choosing the set of plugins to include in a VM at build time (see plugins.int & plugins.ext in build directories).

The VM source are in directories such as

All plugins are in the directory

These contain many, but not all, of the plugins available for the VM. Others can be found in Cog, or in various Monticello packages in various repositories.

Each vm source directory contains several files, a subset of the following: