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.
Want to kick the tires without installing anything? Try it in the browser at the mvm playground.
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 ago test-compatible runner (tests, benchmarks, and examples) - 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 . run -x _samples/fib.go # run with execution tracing
go run . github.com/mvm-sh/mvm/cmd/mvmlint . # fetch and run a remote main package
go run . test ./pkg # run TestX functions in a package directory
go run . test ./pkg -v # ... verbose; -run REGEX selects tests
go run . test github.com/google/uuid # fetch a remote module and run its tests
go run . help # list subcommands
See docs/usage.md for the full command reference, the
-x / MVM_TRACE tracing modes, and the trap() debugger.
Remote import paths (run or test) are resolved through the Go module
proxy and held in memory, so no module sources are written to disk. 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/usage.md: CLI reference, tracing, the trap() debugger, remote imports
- docs/architecture.md: pipeline, memory model, key design decisions
- docs/modules/: per-package reference
- docs/decisions/: architecture decision records (ADRs)
- CHANGELOG.md: release notes
Build
make fast # quick inner loop: interp suite, -short + race detector
make test # full interp suite with the race detector
make cover # cross-package coverage profile
make lint # golangci-lint
Questions and discussions
GitHub Discussions is the preferred place to ask anything mvm-related: how to do something, whether a behavior is a bug or a misuse, or to float an idea for a new feature before it becomes an issue or a pull request. When in doubt, start a discussion.
Contributing
See the Contributing Guide
License
Mvm is distributed under the BSD-3-Clause license. See LICENSE for the full text. The bundled Go standard library sources retain their original BSD-3-Clause 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. |
|
mvmlint
command
Command mvmlint runs mvm's project-specific source checks over mvm's own Go source, using mvm's own scanner (github.com/mvm-sh/mvm/scan) rather than the Go AST or go/analysis.
|
Command mvmlint runs mvm's project-specific source checks over mvm's own Go source, using mvm's own scanner (github.com/mvm-sh/mvm/scan) rather than the Go AST or go/analysis. |
|
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 modfs implements an io/fs.FS backed by the Go module proxy protocol.
|
Package modfs implements an io/fs.FS backed by the Go module proxy protocol. |
|
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. |
|
errorsx
Package errorsx is a mvm-aware replacement for the parts of stdlib `errors` that need to walk error chains containing interpreted error types.
|
Package errorsx is a mvm-aware replacement for the parts of stdlib `errors` that need to walk error chains containing interpreted error types. |
|
gobx
Package gobx bridges interpreted types that implement encoding.BinaryMarshaler/BinaryUnmarshaler through native encoding/gob.
|
Package gobx bridges interpreted types that implement encoding.BinaryMarshaler/BinaryUnmarshaler through native encoding/gob. |
|
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). |
|
stdmod
Package stdmod redirects stdlib-shaped import paths to a std module hosted on the Go module proxy.
|
Package stdmod redirects stdlib-shaped import paths to a std module hosted on the Go module proxy. |
|
xmlx
Package xmlx is a mvm-aware shim for the encoding/xml functions that must honour xml.Unmarshaler methods (UnmarshalXML) defined on interpreted types.
|
Package xmlx is a mvm-aware shim for the encoding/xml functions that must honour xml.Unmarshaler methods (UnmarshalXML) defined on interpreted types. |
|
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. |