Please Rules (please-rules)

A curated collection of modern, hermetic build rules and plugins for the Please build system.

This repository provides language toolchains and build definitions designed for hermeticity, reproducible builds, and minimal host dependencies.

---

Getting Started

To integrate and use rules from this repository in your Please project, see the Getting Started & Integration Guide.

---

Supported Languages

please-rules employs a Hub-and-Spoke Gitflow where each language ruleset is developed, tested, and released on its own dedicated long-lived branch:

Language	Branch	Latest Release	Documentation	Description
Rust (///rust)	rust	[Rust] v0.5.0	Rust Rules Documentation	Hermetic toolchains, crates.io dependency management, C native linking, and llvm-cov coverage.
Kotlin (///kotlin)	kotlin	[Kotlin] v0.2.0	Kotlin Rules Documentation	100% hermetic kotlinc 2.1 & OpenJDK 21, JUnit XML telemetry, and JaCoCo code coverage.
Swift (///swift)	swift	[Swift] v0.1.1	Swift Rules Documentation	Swift 6+ rules, native swift-testing support, multi-module static linking, and coverage.
TypeScript (///ts)	ts	[TypeScript] v0.1.2	TypeScript Rules Documentation	Hermetic Deno v2.2 toolchain, zero node_modules, ephemeral import maps, bundling, and testing.
WIT (///wit)	wit	[WIT] v0.2.0	WIT Rules	WebAssembly Interface Types (WIT) bundling and binding generators for Swift, Kotlin, Rust, Go, TS, C++, and Python.

---

Documentation

Detailed guides, language rule references, and architecture documentation:

• Documentation Portal: Main documentation hub.
• Getting Started Guide: Project integration and setup.
• Multi-Language Gitflow Guide: Repository branching model, release tagging, and synchronization workflows.
• Language Rulesets:
  • Rust Documentation (rust branch)
  • Kotlin Documentation (kotlin branch)
  • Swift Documentation (swift branch)
  • TypeScript Documentation (ts branch)
  • WIT Documentation (wit branch)

---

Building & Testing

To run all tests across the repository:

./pleasew test //...

To build all targets:

./pleasew build //...

---

Development & IDE Setup (Go / VSCode)

please-rules builds its helper tools (such as please_rust, please_kotlin, please_swift, please_ts) using Please's hermetic Go toolchain with root-relative package import paths (e.g. import "tools/please_rust/testrunner").

For optimal VSCode editor integration without conflicting with external Go toolchains, .vscode/settings.json is configured to disable background gopls builds while preserving format on save.