Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
201 lines (127 loc) · 4.68 KB

DEVELOPMENT.md

File metadata and controls

201 lines (127 loc) · 4.68 KB

Development Guide

An overview of the tools and scripts used in the project.

Golang

The project currently runs with the Go Toolchain. Use any Go version that supports it.

The project has some build tags that can be used to build the project with different configurations.

Build Tags

embed

This tag is used to embed the static files in the binary. Without this tag, the static files will be downloaded from the ui-v2 tag of the release.

js and wasm

These tags are used to build the project to WebAssembly. With this tag enabled, some printers are disabled and the json marshaler will be changed to the wasm marshaler.

Profiler tags

pgo

Enables the cpu profiler to collect information for profile-guided optimization.

profiler

Activate all profilers while running integration tests.

Tests

Unit Tests

Unit tests are divided into several parts.

  • embed build tag
  • GOOS=js GOARCH=wasm build constraints

For wasm tests, you need a runner for wasm files.

You can try Zxilly/go_js_wasm_exec.

This runner requires node.js to be installed on your machine. It's a wrapper for the official misc/wasm/go_js_wasm_exec runner.

Or you can use agnivade/wasmbrowsertest, but it has bugs in the Go toolchain environment, see issue.

Integration tests

Integration tests should be executed by the helper scripts described below. It runs on the binaries from Zxilly/go-testdata

Linter

The project uses golangci-lint to lint the code.

golangci-lint run

Python

Helper scripts

Helper scripts are managed by uv. Make sure you have it installed.

All scripts are in the scripts directory.

Download the binary

Download the binary from Zxilly/go-testdata.

python scripts/ensure.py --help
usage: ensure.py [-h] [--example] [--real]

options:
  -h, --help  show this help message and exit
  --example   Download example binaries.
  --real      Download real binaries.

Tests

python scripts/tests.py --help
usage: tests.py [-h] [--unit-full] [--unit-wasm] [--unit-embed] [--unit] [--integration-example] [--integration-real] [--integration]

options:
  -h, --help            show this help message and exit
  --unit-full           Run full unit tests.
  --unit-wasm           Run unit tests for wasm.
  --unit-embed          Run unit tests for embed
  --unit                Run unit tests.
  --integration-example
                        Run integration tests for small binaries.
  --integration-real    Run integration tests for large binaries.
  --integration         Run all integration tests.
Integration binary source generator

Generate scripts/binaries.csv as a source for tests.

python scripts/generate.py
Reporter for CI

Collect the test results and generate a report in GitHub Actions format.

It uses service Zxilly/data2image to bypass GitHub data-uri limit. This project was written in Rust.

The svg data was optimized then compressed with zstd and encoded with base64 for safe inclusion in the url.

python scripts/report.py

Build

Wasm

Requires WebAssembly/binaryen installed to optimize the wasm binary.

python scripts/wasm.py --help
usage: wasm.py [-h] [--raw]

options:
  -h, --help  show this help message and exit
  --raw       Do not optimize the wasm binary
Profile Guided Optimization

Collect the profile data, then build ./cmd/gsa with the profile data.

python scripts/pgo.py

TypeScript and React

The project uses TypeScript and React to build the web interface. Most of the files are located in the ui directory.

Build

The project uses pnpm to manage the dependencies.

pnpm install

Explorer

The explorer needs a wasm file built from the go part.

Just running scripts/wasm.py should put it in the right place.

pnpm run dev:explorer # Development
pnpm run build:explorer # Production

Webui

The built file ./ui/dist/index.html should be placed in internal/webui to be embedded in the binary. Don't forget to set the embed build tag.

pnpm run dev:ui # Development
pnpm run build:ui # Production

Tests

pnpm run test

Linter

The project uses eslint to lint the code.

pnpm run lint
pnpm run lint:fix

Typos

The project uses crate-ci/typos to find typos.