README
¶
mvm
Mvm is a Go interpreter that compiles source to bytecode and runs it on a stack-based virtual machine. It ships as a single static binary with the full Go standard library bundled in, and embeds in Go or C host programs.
Status is alpha. Language coverage is broad but not yet complete, and the embedding API will still change. Pin a commit if you depend on it.
Features
- Fast, portable bytecode virtual machine
- Aims for full Go language compatibility
- Embeddable in Go and C host programs (see
examples/) - pure Go, zero dependency
- Integrated REPL, debugger (
trap()builtin), and test runner - One single static binary, batteries included (full stdlib)
Why mvm?
Disclosure: I (@mvertes) also created yaegi at Traefik, in addition to mvm.
There are several Go interpreters; mvm fills a different slot:
- yaegi: the most mature option, AST tree-walking, focused on plugin-style use. Mvm makes a different bet: compile once to bytecode, then run on a small VM.
- gomacro: also AST-based, with a strong REPL and macro story. Mvm has no macros and concentrates on running ordinary Go code through a compact VM.
- neugram, igo: both no longer maintained.
If you want a small, embeddable runtime that runs idiomatic Go fast enough for non-trivial programs, mvm is built for that.
mvm starts with Go, but the design points further: the scanner/parser front-end is built to host other languages, the bytecode compiler is language-agnostic, and the VM leverages the Go runtime's memory management and concurrency. Useful well beyond scripting.
Usage
Install the mvm command:
go install github.com/mvm-sh/mvm@latest
Or from a clone of the repository:
go run . # start the REPL
go run . _samples/fib.go # run a Go source file
go run . run _samples/fib.go # same. "run" is the default subcommand
go run . run -e "fmt.Println(1+2)" # evaluate an inline expression
go run . test ./pkg # run TestX functions in a package directory
go run . help # list subcommands
A trap() builtin drops the program into an interactive debug REPL
where you can inspect the call stack and memory.
The repository contains two example trees: examples/ for
embedding mvm in Go and C host programs, and _samples/
for Go programs you can run directly with mvm run.
A static file server in one line, using the inlined stdlib:
mvm -e 'http.ListenAndServe(":8080", http.FileServer(http.Dir(".")))'
Documentation
- docs/index.md: documentation entry point
- docs/architecture.md: pipeline, memory model, key design decisions
- docs/modules/: per-package reference
- docs/decisions/: architecture decision records (ADRs)
Build
make test # tests with race detector and coverage
make lint # golangci-lint
Contributing
See the Contributing Guide
License
Mvm is distributed under the BSD-3-Clause license. See LICENSE
for the full text. The vendored Go standard library packages under
stdlib/src/ remain under their original BSD-3-Clause license (see
stdlib/src/LICENSE).
Documentation
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
This example demonstrates an integer heap built using the heap interface.
|
This example demonstrates an integer heap built using the heap interface. |
|
cmd
|
|
|
extract
command
Command extract parses Go package source using mvm's goparser and prints exported const, var, type, and func declarations to stdout.
|
Command extract parses Go package source using mvm's goparser and prints exported const, var, type, and func declarations to stdout. |
|
Package comp implements a byte code generator targeting the vm.
|
Package comp implements a byte code generator targeting the vm. |
|
examples
|
|
|
c/shim
command
Build the mvm interpreter as a C-callable static archive.
|
Build the mvm interpreter as a C-callable static archive. |
|
embed
command
Example: embedding the mvm interpreter in a host Go program.
|
Example: embedding the mvm interpreter in a host Go program. |
|
Package goparser implements a structured parser for Go.
|
Package goparser implements a structured parser for Go. |
|
Package interp implements an interpreter.
|
Package interp implements an interpreter. |
|
Package lang provides tokens for possibly multiple languages.
|
Package lang provides tokens for possibly multiple languages. |
|
golang
Package golang provides the lexical specification of Go language.
|
Package golang provides the lexical specification of Go language. |
|
Package scan provide a language independent scanner.
|
Package scan provide a language independent scanner. |
|
Package stdlib provides wrappers of standard library packages to be imported natively in mvm.
|
Package stdlib provides wrappers of standard library packages to be imported natively in mvm. |
|
all
Package all is the convenience aggregator for stdlib bindings: blank-import it to get the full set (core + ext + jsonx).
|
Package all is the convenience aggregator for stdlib bindings: blank-import it to get the full set (core + ext + jsonx). |
|
core
Package core provides wrappers for core standard library packages.
|
Package core provides wrappers for core standard library packages. |
|
jsonx
Package jsonx is a mvm-aware replacement for the encoding/json functions that need to honour mvm-defined methods on struct types (MarshalJSON, UnmarshalJSON).
|
Package jsonx is a mvm-aware replacement for the encoding/json functions that need to honour mvm-defined methods on struct types (MarshalJSON, UnmarshalJSON). |
|
src/cmp
Package cmp provides types and functions related to comparing ordered values.
|
Package cmp provides types and functions related to comparing ordered values. |
|
src/iter
Package iter provides basic definitions related to iterators over sequences.
|
Package iter provides basic definitions related to iterators over sequences. |
|
src/maps
Package maps defines various functions useful with maps of any type.
|
Package maps defines various functions useful with maps of any type. |
|
src/slices
Package slices defines various functions useful with slices of any type.
|
Package slices defines various functions useful with slices of any type. |
|
Package symbol implements symbol utilities.
|
Package symbol implements symbol utilities. |
|
Package vm implement a stack based virtual machine.
|
Package vm implement a stack based virtual machine. |