The Cog VM generates its own C from a Smalltalk simulator

The core VM is Smalltalk, the repository holds generated C

The overview section explains the arrangement, and it is the single most important thing to understand before reading any code here. 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, along with 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, and should be developed using Smalltalk. The source repository for the VM is at source.squeak.org/VMMaker.html, and the image directory in this repository holds scripts to build a Smalltalk image in which to do core VM development. Cog itself is described as an evolution of the Squeak Back-to-the-future virtual machine, and the Slang component translates the Smalltalk framework comprising the various Cog VMs into C, which is then combined with platform-specific support sources and compiled by a C compiler to obtain a fast production VM. That translation step is what makes this repository read oddly to a C programmer, and it is also why it is such a good thing to read.

Support for other dialects was dropped in August 2025

There is a note in the overview that is easy to skim and expensive to miss. The project dropped support for Newspeak and Pharo VM flavors in August 2025, and the last working sources can be found in the tags last-support-newspeak and last-support-pharo. So the repository you are reading is the Squeak and Cuis VM, and it was previously the home for Pharo's VM as well. If you arrive from Pharo, the practical consequences are that a recent Pharo release will not be served by this tree, that any documentation or build instructions referring to Pharo configurations are historical, and that the two tags are the only route back to the older code. The README also separates the support channels, pointing issues about Squeak and Cuis themselves, rather than the VM, at the Cuis and Squeak community forums. That distinction is reasonable for a project whose scope is the VM, and it is worth knowing before you file an issue about a dialect behaviour that is not the VM's fault.

The first command after cloning is not optional

There is a section headed Important notice for Developers, and it describes the one step that a new contributor will hit immediately. The project relies on source file substitutions in the src tree, specifically that any sq*SCCSVersion.h files anywhere in the tree are processed to replace $Rev$, $Date$ and $URL$ with the current revision, the human readable date of that commit, and the url of the origin repository. The revision is defined as a timestamp of the form %Y%m%d%H%M of the latest commit. The first time you clone the repository you must run:

./scripts/updateSCCSVersions

That installs filters plus post-commit and post-merge hooks so the files are updated whenever you commit or merge. The hooks are installed rather than run once, which is the point, because a version stamp that is correct at clone time and stale at commit time is worse than no stamp at all. The README also points at the scripts/gitci and scripts/gitciplugins scripts for committing changes to this branch and to the Cross and win32 plugins, which are shared with the old Squeak interpreter trunk, and warns that if you do not use those scripts you should still run updateSCCSVersions after a git-reset or git-checkout, because failing to do so results in incorrect version stamps in your compiled VMs.

CI builds every platform and every VM flavour

The badges at the top of the README show the build matrix, and it is wide. There are workflows for macOS on x86 and on ARM, for Windows on x86 and on ARM, for Linux on x86, Linux on ARM and Linux on ARMv8, each as a separate GitHub Actions workflow with its own badge. Builds are tested automatically on each commit for Windows, macOS and Linux, and Windows and Linux also have 32-bit targets. The variants multiply the matrix further, since the Squeak and Pharo VMs are built with and without JIT, with and without Spur, and with and without Sista, as available per platform. Two behaviours of the CI are worth knowing as a contributor. All build artifacts remain accessible for 90 days for each workflow run, and the latest artifacts are uploaded to a dedicated release tag such as latest-build, overwritten with each successful run, with separate tags for the assert and debug build variants. And a commit that should not trigger a build, for example a documentation-only edit, can skip the workflow entirely by adding [ci skip] somewhere in the commit message.

Variants and the shape of the source tree

The README warns that the Cog VM comes in a bewildering variety of forms, and the first distinction it names is between the Stack, Cog and Sista VMs. The variants section continues past the point where the excerpt ends, so the full list is in the repository rather than in the summary here, but the naming gives you the axes: a Stack VM is the simplest, Cog adds the JIT and the newer object memory, and Sista is the variant with the different memory management model. The repository layout mirrors the structure of the system. There is a src/ directory holding the generated VM sources, platforms/ for the platform-specific support code, processors/ for the processor specific parts, include/ for headers, cmake/ and a top level CMakeLists.txt for the build, building/ for build directories, deploy/ for deployment, specs/ for the VM specifications, tests/, third-party/ and scripts/, plus an image/ directory for the Smalltalk development image and Boundaries, mkNamedPrims.sh and the git_filters directory for the source stamping machinery. The C is the primary language of the repository because the compiler consumes it, not because a human maintains it.

Why the arrangement is worth learning from

The closing paragraph of the overview makes the case for the approach in a way that is easy to underrate. The VMs are developed in Smalltalk, using all the dynamic and reflective facilities of the Squeak Smalltalk system, and as such developing in Cog is a delight. The point is not only that the language is pleasant but that the language is the same one the system is written in, so the people writing the VM have the whole Squeak environment, its inspectors and its tooling, available to them while doing it. A Smalltalk implementation is small enough that the people who wrote it can still understand it, and a VM implementation is small enough for the same to be true, which is why the VM can be developed in itself. That is the design decision that makes the whole repository coherent, and it is also why the generated C in src/ is a poor place to start reading if you want to understand how the VM works, and why the image directory is where the real source lives.

Editorial conclusion

Adopt this repository when you want to build, run or modify a Squeak or Cuis Smalltalk VM, or when you want to study how a modern Smalltalk VM is put together. Do not expect it to be a general purpose Smalltalk VM for every dialect, since support for the Newspeak and Pharo VM flavors was dropped in August 2025 and the last working sources live in separate tags. Verify first that you have the Smalltalk toolchain and a C compiler as the build documentation describes, that you run the version stamping script after cloning, and that you are working in the image directory workflow rather than editing the generated C in src/.

Frequently asked questions

Official sources

1. Issues
2. OpenSmalltalk/opensmalltalk-vm on GitHub
3. Project website
4. README
5. Releases