How to run interpreted mode

Use interpreted mode (dev-i) to reload .pk edits without rebuilding the server binary. Start with an existing Piko project and the Piko CLI. For the trade-offs between run modes, see about interpreted mode.

Register the interpreter

In cmd/main/main.go, import the provider package and register it on your server before the existing ssr.Run(...) call. Projects created with the wizard's interpreted-mode option already include this registration.

import "piko.sh/piko/wdk/interp/interp_provider_pipit"

// After ssr := piko.New(...).
ssr.WithInterpreterProvider(interp_provider_pipit.NewProvider())

Keep your existing bootstrap options and run-mode selection.

Start the server

From the project root, run the following command.

piko dev-i

Open the address printed by the server. Edit some visible text in a .pk page and save it. The page should show the change after reloading, without a server restart.

Add native package symbols

Pipit provides standard-library symbols, and Piko supplies its runtime symbols. Piko can also compile local project packages from source. Use symbol extraction for third-party Go packages, or to run a project package as native code.

Check which imports need symbol tables.

piko extract discover

If the scan finds packages and you do not yet have piko-symbols.yaml, create it. Review the package list before generating the tables.

piko extract init

Skip extraction if the scan finds no packages. init can create an empty manifest, but generate requires at least one package. If a manifest already exists, update its package list to include the imports you need.

Generate the tables from the non-empty manifest.

piko extract generate

Import the generated package in cmd/main/main.go, replacing example.com/myapp with your module path. Add the registration before ssr.Run(...).

import "example.com/myapp/internal/piko_symbols"

ssr.WithSymbols(piko_symbols.Symbols)

Restart piko dev-i to build the native symbols into the server. Regenerate the tables when exported symbols change. Restart after changing any package listed in the manifest, because its native code comes from the server binary.

Inspect generated bytecode

To investigate a compilation problem, enable bytecode emission when registering the provider.

ssr.WithInterpreterProvider(interp_provider_pipit.NewProvider(
    interp_provider_pipit.WithBytecodeEmission(".piko/bytecode"),
))

Restart piko dev-i and reproduce the problem. Find the emitted .bin file under .piko/bytecode/compiled/, then pass its path to the inspector.

piko inspect bytecode .piko/bytecode/compiled/bytecode-abc.bin

Replace bytecode-abc.bin with the emitted filename. A successful compilation also produces a .pkasm disassembly. For a failed compilation, read the .error.txt file instead. See the interpreter API reference for the output files.

See also