Custom Runner Support in gox.mod

[joeykchen]

Proposal

Add support for run directive in gox.mod files that allows projects to specify a custom runner command.
When xgo run is executed and the project has a run directive, it will invoke the specified runner instead of standard Go run.

Syntax

run <package-path>

Example gox.mod

xgo 1.3

project main.spx Game github.com/goplus/spx/v2 math

class -embed *.spx SpriteImpl

run github.com/goplus/spx/v2/cmd/spxrun

Behavior

When xgo run . is executed:

1. Check if gox.mod contains a run directive
2. If no directive found, use standard go run (current behavior)
3. If directive exists:
   • Extract the runner binary name from package path
   • Look for runner in $GOPATH/bin, $GOBIN, or $PATH
   • If not found, auto-install using go install <package-path>@latest
   • Execute: <runner-binary> <project-dir> [args...]

Runner Interface

The custom runner must accept:

<runner-binary> <project-directory> [user-args...]

Example:

spxrun /path/to/my-game --debug

User Experience

Before:

$ cd my-spx-game
$ spxrun .  # Must know and use specific runner

After:

$ cd my-spx-game
$ xgo run .  # Unified command, automatic runner detection

---

Background

XGo classfile projects (like SPX games, data science scripts, web apps) often require specialized runtime environments rather than standard Go execution. Each classfile type may need:

• Custom initialization (graphics engine, resource managers)
• Specialized runtime configuration (database connections, web servers)
• Domain-specific error handling and debugging

Currently, users must:

1. Know which runner to use for their project type
2. Manually invoke the correct runner command
3. Remember different command patterns for different project types

This creates friction, especially for:

• Beginners: Confused about which command to use
• Cross-domain developers: Switching between SPX, data science, and web projects
• Tool integration: IDEs and scripts need project-type-specific logic

Example Scenarios

Project Type	Current Command	Desired Command
SPX Game	spxrun .	xgo run .
Data Script	gshrun .	xgo run .
Web App	yaprun .	xgo run .

---

Workarounds

Current Installation

export PATH=$PATH:$GOPATH/bin
git clone https://github.com/goplus/xgo.git && cd xgo && go install ./...
git clone https://github.com/goplus/spx.git && cd spx && git checkout dev && make setup

Running SPX Games

spx run tutorial/00-Hello

[xushiwei]

It seems more appropriate to change the directive run to runner.

[xushiwei]

Syntax

runner <package-path> [<version>]

• if <version> is not specified, it will be latest

Example gox.mod

xgo 1.3

project main.spx Game github.com/goplus/spx/v2 math

class -embed *.spx SpriteImpl

runner github.com/goplus/spx/v2/cmd/spxrun

[xushiwei]

parser: supported in https://github.com/goplus/mod/releases/tag/v0.18.0