diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000000..25188a58ae --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,203 @@ +# Development Guide + +An overview of the tools and scripts used in the project. + +## Golang + +The project currently runs with `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 into the binary. Without this tag, the static files are download from +the `v1` tag of the release. + +#### `js` and `wasm` + +This tag is used to build the project to WebAssembly. With this tag enabled, some printer will be disabled and the +json marshaler will be changed to the `wasm` marshaler. + +#### profiler tags + +##### `pgo` + +Enables `cpu` profiler to collect info for Profile-Guided Optimization. + +##### `profiler` + +Enables all profilers while running integration tests. + +### Tests + +#### Unit tests + +Unit tests are split into different parts. + +- `embed` build tag +- `GOOS=js GOARCH=wasm` build constraints + +For wasm tests, you will need a runner for wasm files. + +You can give [Zxilly/go_js_wasm_exec](https://github.com/Zxilly/go_js_wasm_exec) a try. + +> This runner needs `Node.js` installed on your machine. It's a wrapper of the official `misc/wasm/go_js_wasm_exec` runner. + +Or you can use [agnivade/wasmbrowsertest](https://github.com/agnivade/wasmbrowsertest), +but it has bugs under Go Toolchain environment. see [issue](https://github.com/agnivade/wasmbrowsertest/issues/61). + +#### Integration tests + +Integrations tests should run by helper scripts described following. +It executes on the binaries from [Zxilly/go-testdata](https://github.com/Zxilly/go-testdata) + +### Helper scripts + +Helper scripts are managed by `poetry` and `python`. Make sure you have them installed. + +All the scripts are in the `scripts` directory. + +#### Download binary + +Download binary from the [Zxilly/go-testdata](https://github.com/Zxilly/go-testdata). + +```bash +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 + +```bash +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 the source to tests. + +```bash +python scripts/generate.py +``` + +##### Reporter for CI + +Collect the test results and generate a report in GitHub Actions format. + +Requires `svgo` installed to optimize the SVG files. + +It uses service [Zxilly/data2image](https://github.com/Zxilly/data2image) to bypass +GitHub data-uri limit. This project was written in `Rust`. + +The svg data was optimized by `svgo` then compressed by `zstd` and encoded by `base64` +to be included safely in the url. + +```bash +python scripts/report.py +``` + +#### Build + +##### Wasm + +Requires [WebAssembly/binaryen](https://github.com/WebAssembly/binaryen) installed to optimize the wasm binary. + +```bash +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. + +```bash +python scripts/pgo.py +``` + +### Linter + +The project uses `golangci-lint` to lint the code. + +> Golangci-lint doesn't official supports `Go 1.23` right now. Use preview version from PR. + +```bash +golangci-lint run +``` + +## TypeScript and React + +The project uses `TypeScript` and `React` to build the web interface. +Most of the file is in the `ui` directory. + +### Build + +The project uses `pnpm` to manage the dependencies. + +```bash +pnpm install +``` + +#### Explorer + +The explorer needs built `wasm` file from go part. + +Just run `scripts/wasm.py` should place it at the right place. + +```bash +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 attach the `embed` build tag. + +```bash +pnpm run dev:ui # Development +pnpm run build:ui # Production +``` + +### Tests + +```bash +pnpm run test +``` + +### Linter + +The project uses `eslint` to lint the code. + +```bash +pnpm run lint +pnpm run lint:fix +``` + +## Typos + +The project uses [crate-ci/typos](https://github.com/crate-ci/typos) to find typos. + diff --git a/README.md b/README.md index fe23afaff0..e02b3438a3 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ [![go-recipes](https://raw.githubusercontent.com/nikolaydubina/go-recipes/main/badge.svg?raw=true)](https://github.com/nikolaydubina/go-recipes?tab=readme-ov-file#-visualise-dependencies-size-in-compiled-binaries-with-go-size-analyzer) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Zxilly/go-size-analyzer/badge)](https://scorecard.dev/viewer/?uri=github.com/Zxilly/go-size-analyzer) -English | [简体中文](./README_zh-CN.md) +English | [简体中文](./README_zh_CN) A simple tool to analyze the size of a Go compiled binary. @@ -245,6 +245,8 @@ Terminal interface options Any contribution is welcome, feel free to open an issue or a pull request. +For development, see the [Development Guide](./DEVELOPMENT.md) for more details. + ## LICENSE Published under the [AGPL-3.0](./LICENSE). diff --git a/README_zh-CN.md b/README_zh_CN.md similarity index 99% rename from README_zh-CN.md rename to README_zh_CN.md index 29096580e2..d9ffc9c88d 100644 --- a/README_zh-CN.md +++ b/README_zh_CN.md @@ -243,6 +243,8 @@ Terminal interface options 欢迎任何形式的贡献，随时提出问题或拉取请求。 +关于开发，请查看 [开发指南](./DEVELOPMENT.md) 以获取更多详细信息。 + ## LICENSE 根据 [AGPL-3.0](./LICENSE) 发布。