{"id":15001734,"url":"https://github.com/opensmalltalk/opensmalltalk-vm","last_synced_at":"2026-04-02T18:02:43.509Z","repository":{"id":38714376,"uuid":"59481716","full_name":"OpenSmalltalk/opensmalltalk-vm","owner":"OpenSmalltalk","description":"Cross-platform virtual machine for Squeak, Pharo, Cuis, and Newspeak.","archived":false,"fork":false,"pushed_at":"2025-04-09T17:44:13.000Z","size":623886,"stargazers_count":580,"open_issues_count":130,"forks_count":112,"subscribers_count":40,"default_branch":"Cog","last_synced_at":"2025-04-09T18:48:32.507Z","etag":null,"topics":["armv7","armv8","cuis","garbage-collector","ios","jit","linux","macos","mips32","newspeak","pharo","raspberry-pi","scavenger","smalltalk","squeak","vm","win","x86-32","x86-64"],"latest_commit_sha":null,"homepage":"http://opensmalltalk.org/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenSmalltalk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-23T12:40:27.000Z","updated_at":"2025-04-09T17:44:19.000Z","dependencies_parsed_at":"2024-11-25T17:37:46.089Z","dependency_job_id":null,"html_url":"https://github.com/OpenSmalltalk/opensmalltalk-vm","commit_stats":{"total_commits":4856,"total_committers":90,"mean_commits":"53.955555555555556","dds":0.5335667215815486,"last_synced_commit":"223080a356eb2981b70bccd46faa4e6aa02995b7"},"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenSmalltalk%2Fopensmalltalk-vm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenSmalltalk%2Fopensmalltalk-vm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenSmalltalk%2Fopensmalltalk-vm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenSmalltalk%2Fopensmalltalk-vm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenSmalltalk","download_url":"https://codeload.github.com/OpenSmalltalk/opensmalltalk-vm/tar.gz/refs/heads/Cog","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248837274,"owners_count":21169373,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["armv7","armv8","cuis","garbage-collector","ios","jit","linux","macos","mips32","newspeak","pharo","raspberry-pi","scavenger","smalltalk","squeak","vm","win","x86-32","x86-64"],"created_at":"2024-09-24T18:05:20.646Z","updated_at":"2026-04-02T18:02:43.501Z","avatar_url":"https://github.com/OpenSmalltalk.png","language":"C","readme":"The Cog VM source tree\n---------------------\nThis is the README for the Cog Git source tree:\n\thttps://github.com/OpenSmalltalk/opensmalltalk-vm\n\n[![Download stable](https://img.shields.io/badge/download-stable-green.svg)](https://github.com/OpenSmalltalk/opensmalltalk-vm/releases/latest)\n[![Download latestBuild](https://img.shields.io/badge/download-latest%20build-blue.svg)](https://github.com/OpenSmalltalk/opensmalltalk-vm/releases/tag/latest-build)\n[![Download latestAssertBuild](https://img.shields.io/badge/download-latest%20assert%20build-lightgrey.svg)](https://github.com/OpenSmalltalk/opensmalltalk-vm/releases/tag/latest-assert-build)\n[![Download latestDebugBuild](https://img.shields.io/badge/download-latest%20debug%20build-lightgrey.svg)](https://github.com/OpenSmalltalk/opensmalltalk-vm/releases/tag/latest-debug-build)\n\n[![Build for macOS (x86)](https://github.com/OpenSmalltalk/opensmalltalk-vm/actions/workflows/macos.yml/badge.svg)](https://github.com/OpenSmalltalk/opensmalltalk-vm/actions/workflows/macos.yml)\n[![Build for macOS (ARM)](https://github.com/OpenSmalltalk/opensmalltalk-vm/actions/workflows/macos-arm.yml/badge.svg)](https://github.com/OpenSmalltalk/opensmalltalk-vm/actions/workflows/macos-arm.yml)\n[![Build for Windows (x86)](https://github.com/OpenSmalltalk/opensmalltalk-vm/actions/workflows/win.yml/badge.svg)](https://github.com/OpenSmalltalk/opensmalltalk-vm/actions/workflows/win.yml)\n[![Build for Windows (ARM)](https://github.com/OpenSmalltalk/opensmalltalk-vm/actions/workflows/win-arm.yml/badge.svg)](https://github.com/OpenSmalltalk/opensmalltalk-vm/actions/workflows/win-arm.yml)\n[![Build for Linux (x86)](https://github.com/OpenSmalltalk/opensmalltalk-vm/actions/workflows/linux.yml/badge.svg)](https://github.com/OpenSmalltalk/opensmalltalk-vm/actions/workflows/linux.yml)\n[![Build for Linux (ARM)](https://github.com/OpenSmalltalk/opensmalltalk-vm/actions/workflows/linux-arm.yml/badge.svg)](https://github.com/OpenSmalltalk/opensmalltalk-vm/actions/workflows/linux-arm.yml)\n[![Build for Linux (ARMv8)](https://github.com/OpenSmalltalk/opensmalltalk-vm/actions/workflows/linux-arm64.yml/badge.svg)](https://github.com/OpenSmalltalk/opensmalltalk-vm/actions/workflows/linux-arm64.yml)\n\n[![DOI](https://zenodo.org/badge/59481716.svg)](https://zenodo.org/badge/latestdoi/59481716)\n\n\nBuilds are tested automatically on each commit, for Windows, macOS, and Linux.\nWindows and Linux also have 32-bit targets. Squeak and Pharo VMs are built with \nand without JIT, with and without Spur, and with and without Sista, as available\nper platform. All build artifacts remain accessible for 90 days for each\nworkflow run; the latest artifacts are uploaded to a dedicated release tag\n(e.g., \"latest-build\"), overwritten with each successful run. If you wish to\ncommit *without* triggering a build, for example if you were to only edit this \ndocumentation, then if you add **[ci skip]** somewhere in your commit message, \nno workflow run will be started for that commit.\n\n### Important notice for Developers:\nWe rely on source file substitutions in the src tree, specifically,\nany sq*SCCSVersion.h files anywhere in the tree are processed to replace\n`$Rev$`, `$Date$`, and `$URL$` with the current revision (defined as the\ntimestamp %Y%m%d%H%M of the latest commit), the human readable date of that\ncommit, and the url of the origin repository these sources were cloned from.\n\nThe first time you clone this repository, you *must* therefore run this command:\n```bash\n./scripts/updateSCCSVersions\n```\nThis will install filters, post-commit, and post-merge hooks to update the\nsq*SCCSVersion.h files anytime you commit or merge.\n\nFor easier use, we include the scripts/gitci and scripts/gitciplugins scripts to\ncommit changes to this branch and changes to the Cross and win32 plugins (which\nare shared with the old Squeak interpreter trunk). If you decide not to use\nthese scripts for checking in sources, you should also run the\n`updateSCCSVersions` script anytime you decide to use `git-reset` or\n`git-checkout` to make sure the stamps are updated correctly. Failing to do so\nwill result in incorrect version stamps in your compiled VMs.\n\n\n### Contents:\n - Overview\n - Variants\n - VM source directories\n - Platform build directories\n - Other directories (platforms, processors, deployment, image)\n\n\nOverview\n--------\nFirst, opensmalltalk-vm (a.k.a. the Cog VM) is the virtual machine beneath the\nCuis and Squeak Smalltalk dialects. For issues related to these systems\nthat are unrelated to the VM itself, please use their forums:\n* https://cuis.st/community\n* https://squeak.org/community\n\n*Note that we dropped support for Newspeak and Pharo VM flavors in August 2025.\nThe last working sources can be found in the tags\n[last-support-newspeak](https://github.com/OpenSmalltalk/opensmalltalk-vm/tree/last-support-newspeak) and\n[last-support-pharo](https://github.com/OpenSmalltalk/opensmalltalk-vm/tree/last-support-pharo).*\n\nSecond, the core VM, which comprises the execution engine and garbage collector,\nand the core plugins, is developed in Smalltalk, using the *VM Simulator*.  This\nrepository contains the code generated by the Simulator, and the platform support\ncode for the entire VM, its CI infrastructure and so on.  The core VM **should\nnot** be developed by editing the generated code.  The core VM should be\ndeveloped using Smalltalk.  The source code repository for the VM is  \nhttp://source.squeak.org/VMMaker.html.  \nYou can find scripts to build a Smalltalk image in which to do core VM development\nin the [image](https://github.com/OpenSmalltalk/opensmalltalk-vm/tree/Cog/image)\ndirectory in this repository.  You can read about the Simulator here:\n* https://www.researchgate.net/publication/328509577_Two_Decades_of_Smalltalk_VM_Development_Live_VM_Development_through_Simulation_Tools\n\nCog is an evolution of the Squeak Back-to-the-future Smalltalk virtual machine\nthat provides a number of different Smalltalk virtual machines.  The VMs are\ndeveloped in Smalltalk, using all the dynamic and reflective facilities of the\nSqueak Smalltalk system.  As such, developing in Cog is a delight.  The\nSmalltalk framework comprising the various Cog VMs is translated into C by its\nSlang component to produce VM source that is combined with platform-specific\nsupport sources and compiled via a C compiler to obtain a fast production VM.\nThis directory tree includes the output of Slang for various configurations of\n\"Cog VM\" along with the associated platform support code, plus build directories that\ncan be used to produce production VMs.\n\nThis directory tree also includes a directory containing scripts that can be used to\ncreate an instance of the Smalltalk Cog development system, suitable for developing\nthe VM in Smalltalk, and for generating new VM sources. See the image subdirectory,\ndescribed below.\n\nVariants\n--------\nThe \"Cog VM\" comes in a bewildering variety of forms.  The first distinction\nis between Stack, Cog and Sista VMs.  Stack VMs are those with context-to-stack\nmapping that optimise message sending by keeping method activations on a stack\ninstead of in contexts.  These are pure interpreters but are significantly\nfaster than the standard context-based Interpreter VM.  Cog VMs add a JIT to\nthe mix, compiling methods used more than once to machine code on the fly.\nSista VMs, as yet unrealised and in development, add support for adaptive\noptimization that does speculative inlining at the bytecode-to-bytecode level.\n\nAnother distinction is between \"v3\" VMs and Spur VMs.  \"v3\" is the original\nobject representation for Squeak as described in the back-to-the-future paper.\nSpur, 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 \u0026 Béra, is a faster object\nrepresentation which uses generation scavenging, lazy forwarding for fast\nbecome, a single object header format common to 32 and 64 bit versions, and a\nsegmented heap that can grow and shrink, releasing memory back to the host OS.\nSqueak 5.0, Cuis 5 and Pharo 5 and subsequent releases use Spur.\n\nAnother distinction is between normal single-threaded VMs that schedule \"green\"\nSmalltalk light-weight processes above a single-threaded VM, and multi-threaded\nVMs that share the VM between any number of native threads such that only one\nnative thread owns the VM at any one time, switching between threads on FFI\ncalls and callbacks or on Smalltalk process switches when Smalltalk processes\nare owned by threads.  This architecture offers non-blocking FFI calls and\ninteroperability with multiple native threads, but does /not/ provide true\nconcurrency.  This multi-threaded support is as yet experimental.\n\n\nVM source directories\n---------------------\nThe Slang output of the various VMs are kept in \"vm source\" directories.  These\nC sources define the core VM (the Smalltalk execution engine and the memory\nmanager), and a substantial set of \"plugins\" that provide interfaces to various\nexternal facilities via Smalltalk primitive methods.  Each vm source directory\nis specific to a particular VM, be it Squeak Cog Spur, or V3 Stack, etc.\nThe plugins can be shared between VMs, choosing the set of plugins to include\nin a VM at build time (see plugins.int \u0026 plugins.ext in build directories).\n\nThe VM source are in directories such as\n```\n\tsrc/v3.sista\t\t- Smalltalk Sista V3\n\tsrc/spur32.sista\t- Smalltalk Sista Spur\n\tsrc/spur32.cog \t\t- Smalltalk Cog Spur\n\tsrc/spur64.cog \t\t- Smalltalk Cog Spur 64-bit\n\tsrc/spur32.stack \t- Smalltalk Stack Spur\n\tsrc/spur64.stack \t- Smalltalk Stack Spur 64-bit\n\tsrc/v3.cog\t\t\t- Smalltalk Cog V3\n\tsrc/v3.stack \t\t- Smalltalk Stack V3\n```\n\nAll plugins are in the directory\n```\n\tsrc/plugins\n```\n\nThese contain many, but not all, of the plugins available for the VM.  Others\ncan be found in Cog, or in various Monticello packages in various repositories.\n\nEach vm source directory contains several files, a subset of the following:\n```\n\tcogit.c\t\t\t\t- the JIT; a Cogit cooperates with a CoInterpreter.\n                          This simply includes a processor-specific JIT file\n\tcogitIA32.c et al   - relevant processor-specific JIT, selected by cogit.c\n\tcogit.h\t\t\t\t- the Cogit's API, as used by the CoInterpreter\n\tcogmethod.h\t\t\t- the structure of a CogMethod, the output of the Cogit\n\tcointerp.c\t\t\t- the CoInterpreter's source file\n\tcointerp.h\t\t\t- the API of the CoInterpreter, as used by the Cogit\n\tcointerpmt.c\t\t- the multi-threaded CoInterpreterMT's source file\n\tcointerpmt.h\t\t- the API of the CoInterpreterMT, as used by the Cogit\n\tgcc3x-cointerp.c\t- cointerp.c massaged to interpret faster if using gcc\n\tgcc3x-cointerpmt.c\t- ditto for cointerpmt.c\n\tgcc3x-interp.c\t\t- ditto for interp.c\n\tinterp.c\t\t\t- the StackInterpreter's source file\n\tinterp.h\t\t\t- defines for the VM configuration, word size, etc\n\tvmCallback.h\t\t- the structure of the VM's VMCallbackContext\n```\n\nPlatform build directories\n--------------------------\nThe current \"official\" build directories are of the form\nbuilding/OS_WordSize_Processor, and include\n```\n\tbuilding/linux32x86   - uses autoconf, clang (or gcc), and make\n\tbuilding/linux64x64   - uses autoconf, clang (or gcc), and make\n\tbuilding/linux64ARMv8 - uses autoconf, clang (or gcc), and make\n\tbuilding/macos64x64\t  - macOS on Intel using clang and gmake (via XCode)\n\tbuilding/macos64ARMv8 - macOS on ARM using clang and gmake (via XCode)\n\tbuilding/win32x86     - uses msys2, clang, and make; supports Visual Studio Native Tools Command Prompt\n\tbuilding/win64x64     - uses msys2, clang, and make; supports Visual Studio Native Tools Command Prompt\n\tbuilding/win64ARMv8   - uses msys2, clang, and make; supports Visual Studio Native Tools Command Prompt\n```\nMore can be added as required.  In each there is a HowToBuild that describes\nthe necessary steps to compile a VM.\n\nWithin each building/OS_WordSize_Processor directory are a set of build directories\nfor specific configurations of Cog, and for support code and makefiles.  For\nexample, there exist\n```\n\tbuilding/macos64x64/squeak.cog.spur   - A Cog JIT VM with Squeak branding,\n                                         using the Spur memory manager.\n\tbuilding/macos64x64/squeak.stack.spur - A Stack interpreter VM with Squeak\n                                         branding, and the Spur memory manager.\n\tbuilding/win32x86/squeak.cog.v3     - A Cog JIT VM with Squeak branding,\n                                         using the old Squeak memory manager.\n```\n    etc.\n\nThere exist\n```\n    building/macos64x64/bochsx86 - Support libraries for the BochsIA32Plugin which\n                                is used to develop Cog itself.\n    building/macos64x64/bochsx64 - Support libraries for the BochsX64Plugin which\n                                is used to develop Cog itself.\n    building/macos64x64/gdbarm32 - Support libraries for the GdbARMPlugin which\n                                is used to develop Cog itself.\n    building/macos64x64/gdbarm64 - Support libraries for the GdbARMv8Plugin which\n                                is used to develop Cog itself.\n```\nand the intention is to add such directories to contain e.g. support code for\nthe Pharo Cairo and Freetype plugins, and anything else needed.  By placing\nsupport directories in each build directory they can be shared between various\nbranded VM builds, avoiding duplication.\n\nThere exist\n```\n\tbuilding/macos32x86/common - Gnu Makefiles for building the various branded VMs\n\tbuilding/macos64x64/common - Gnu Makefiles for building the various branded VMs\n\tbuilding/win32x86/common   - Gnu Makefiles for building the various branded VMs\n\tbuilding/win64x64/common   - Gnu Makefiles for building the various branded VMs\n```\nAnd the intention is to add building/linuxNN????/common as soon as possible to\nuse Gnu Makefiles to build all VMs on all platforms.\n\nThe scripts directory contains various scripts for validating and checking-in\ngenerated sources, packaging builds into installable artifacts (tar, msi, zip),\nand so on.  The linux builds and the packaging scripts produce outputs in the\nproducts directory tree.  The packaging scripts may choose to include Smalltalk\nsource files included in the sources directory.\n\n\nOther directories\n-----------------\nThe platforms directory contains the associated platform-specific files that\ncombine with the Slang-generated source to produce complete VMs.  The structure\nis\n```\n\tplatforms/Cross/vm\n\tplatforms/Cross/plugins\n\tplatforms/iOS/vm\n\tplatforms/iOS/plugins\n\tplatforms/unix/vm*\n\tplatforms/unix/plugins\n\tplatforms/win32/vm\n\tplatforms/win32/plugins\n```\nEach vm directory contains support for the core VM.  Each plugin directory\ncontains run-time and build-time support for various plugins.\n\nThe processors directory contains the source for various processor simulators.\nThe JIT is developed in Smalltalk by using one of these processor simulators\nto execute the code the JIT produces.  Currently x86 \u0026 x86-64 are derived from\nBochs, and ARMv6/v7 \u0026 ARMv8 are derived from gdb.\n\nCustomization of builds may be done in two main ways, by adapting an existing\nbuild directory, and by using facilities designed to be applied after the fact\nto a preexisting build.  Such facilities live in the top-level deploy directory\nand are documented there; e.g. see deploy/packaging/README.win32.\n\nFinally the image directory contains scripts that will build a \"VMMaker\" image,\na Squeak Smalltalk image containing all the packages that comprise the Cog\nsystem, suitable for developing the VM and for generating (or updating) the\nsources in the vm source directories. There is also a script for generating a\n64-bit Spur image from a 32-bit Spur image, and the VMMaker.oscog package includes\ncode for converting Spur images in either direction. Note that JIT development depends on processor simulations which are included under the top-level processors directory, Bochs providing x86 and x86-64, gdb providing ARMv6 and ARMv8. To do JIT development the processor plugins must be built. These will be built automatically if the simulator libraries are built. In several building top-level subdirectory are four directories, bochsx86, bochsx64, gdbarm32 \u0026 gdbarm64, which contain the build scripts. To build a VM suitable for full JIT simulation, first build the support code in the building subdirectory for your platform, and then build a squeak.cog.spur VM in the sibling directory.\n\nEnjoy, and give forward.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopensmalltalk%2Fopensmalltalk-vm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopensmalltalk%2Fopensmalltalk-vm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopensmalltalk%2Fopensmalltalk-vm/lists"}