gobuild

gobuild

Thread-safe Go/WASM build handler with sync/async compilation support.

Installation

go get github.com/tinywasm/gobuild

Quick Start

Configuration is documented in config.go.

// See config.go for full configuration options
config := &Config{
    Command:                    "go",
    MainInputFileRelativePath:  "server/main.go",
    OutName:                    "app",
    Extension:                  ".exe",
    OutFolderRelativePath:      "dist",
    Logger:                     func(msg ...any) { fmt.Println(msg...) },
    Timeout:                    5 * time.Second,
    Env:                        []string{"GOOS=js", "GOARCH=wasm"}, // For WASM compilation
}

compiler := gobuild.New(config)
err := compiler.CompileProgram() // Synchronous

Async Compilation

config.Callback = func(err error) {
    if err != nil {
        log.Printf("Failed: %v", err)
    } else {
        log.Printf("Success!")
    }
}
err := compiler.CompileProgram() // Returns immediately

Thread-Safe Control

// Cancel ongoing compilation
compiler.Cancel()

// Check compilation status
if compiler.IsCompiling() {
    fmt.Println("Compilation in progress...")
}

Methods

• CompileProgram() error - Compile to disk (sync/async based on callback)
• CompileToMemory() ([]byte, error) - Compile to memory (returns byte slice, sync only)
• BinarySize() string - Get human-readable binary size (e.g., "2.1 MB", "10.4 KB")
• Cancel() error - Cancel current compilation
• IsCompiling() bool - Check if compilation is active
• MainOutputFileNameWithExtension() string - Get output filename with extension (e.g., "main.wasm")
• FinalOutputPath() string - Get full path to compiled binary (e.g., "web/build/main.wasm")

In-Memory Compilation

// Compile directly to memory without writing to disk
binary, err := compiler.CompileToMemory()
if err != nil {
    log.Fatal(err)
}

// Get human-readable size (works with both disk and memory compilations)
fmt.Printf("Binary size: %s (%d bytes)\n", compiler.BinarySize(), len(binary))
// Output: Binary size: 2.1 MB (2254340 bytes)

Binary Size Information

// After CompileProgram() or CompileToMemory()
size := compiler.BinarySize()
fmt.Println("Compiled binary:", size) 
// Examples: "10.4 KB", "2.3 MB", "1.5 GB"
// Returns "0.0 KB" if binary is unavailable

Guarda del grafo de importaciones

GuardImports corre antes de cada compilación y falla si el binario alcanza, por cualquier cadena de imports, un paquete de la biblioteca estándar que el ecosistema reemplaza (fmt, strconv, reflect, bytes, unicode, …). Cada uno de esos paquetes pesa bastante más de lo que aparenta en un binario WASM — bytes por sí solo arrastra las tablas completas de Unicode.

config := &gobuild.Config{
    Command:                    "tinygo",
    MainInputFileRelativePath:  "edge/main.go",
    Env:                        []string{"GOOS=js", "GOARCH=wasm"},
    GuardImports:                true, // false por defecto
    // ForbiddenList: nil,           // nil = gobuild.ForbiddenWASMImports
}

Necesita GOOS/GOARCH en Env: sin ellos la guarda se omite —adivinar el objetivo produciría falsos positivos o falsos negativos— y lo dice por Logger.

Cuando encuentra una cadena, el error trae el camino completo, no sólo el nombre del paquete prohibido — es lo único que le dice a quien lee dónde cortar:

gobuild: el binario WASM alcanza paquetes prohibidos de la biblioteca estándar

  fmt
    github.com/veltylabs/misitio/edge
     -> github.com/tinywasm/user/authority
     -> github.com/tinywasm/user/email_password
     -> golang.org/x/crypto/bcrypt
     -> fmt

  unicode
    github.com/veltylabs/misitio/edge
     -> github.com/tinywasm/goflare/workers
     -> bytes
     -> unicode

También se puede llamar por separado, fuera de una compilación, p. ej. desde un test del propio proyecto:

chains, err := gobuild.CheckForbiddenImports("/ruta/al/modulo", "./edge/", "js", "wasm", nil)
if err != nil {
    t.Fatal(err)
}
if len(chains) > 0 {
    t.Fatal(gobuild.FormatChains(chains))
}

Features

• Thread-safe: Automatic cancellation of previous compilations
• Unique temp files: Prevents conflicts during concurrent builds
• Context-aware: Proper cancellation and timeout handling
• In-memory: Compile directly to memory slice without disk I/O
• Size reporting: Human-readable binary size (KB, MB, GB) for both disk and memory compilations

Contributing