getting-started.md

Getting Started with please-rules

This guide explains how to integrate and consume build rules from please-rules in your Please project.

---

1. Declaring the Plugin Dependency

In your project's plugins/BUILD file, declare each required language plugin using plugin_repo. Because please-rules uses a Hub-and-Spoke Gitflow, specify the respective language release tag or branch in revision:

# plugins/BUILD

# Rust plugin
plugin_repo(
    name = "rust",
    owner = "wcodesoft",
    plugin = "please-rules",
    revision = "rust-v0.5.0",  # or revision = "rust"
)

# Kotlin plugin
plugin_repo(
    name = "kotlin",
    owner = "wcodesoft",
    plugin = "please-rules",
    revision = "kotlin-v0.2.0",  # or revision = "kotlin"
)

# Swift plugin
plugin_repo(
    name = "swift",
    owner = "wcodesoft",
    plugin = "please-rules",
    revision = "swift-v0.1.1",  # or revision = "swift"
)

# TypeScript / Deno plugin
plugin_repo(
    name = "ts",
    owner = "wcodesoft",
    plugin = "please-rules",
    revision = "ts-v0.1.2",  # or revision = "ts"
)

---

2. Configuring .plzconfig

Add configuration sections for each language plugin in your project's root .plzconfig:

Rust

[Plugin "rust"]
Target = //plugins:rust
RustcTool = ///rust//tools/rust_toolchain:toolchain|rustc

(Where RustcTool points to the hermetic toolchain target or local compiler).

Kotlin

[Plugin "kotlin"]
Target = //plugins:kotlin
KotlincTool = ///kotlin//tools/kotlin_toolchain:toolchain|kotlinc
JavaTool = ///kotlin//tools/kotlin_toolchain:toolchain|java

Swift

[Plugin "swift"]
Target = //plugins:swift
SwiftcTool = ///swift//tools/swift_toolchain:toolchain|swiftc

TypeScript / Deno

[Plugin "ts"]
Target = //plugins:ts
DenoTool = ///ts//tools/ts_toolchain:toolchain|deno

---

3. Subincluding Rules in BUILD Files

In any package where you want to use the rules, subinclude the rule definitions:

# Rust targets
subinclude("///rust//build_defs:rust")

# Kotlin targets
subinclude("///kotlin//build_defs:kotlin")

# Swift targets
subinclude("///swift//build_defs:swift")

# TypeScript targets
subinclude("///ts//build_defs:ts")

Alternatively, you can preload build definitions globally in .plzconfig under [parse]:

[parse]
preloadsubincludes = ///rust//build_defs:rust, ///kotlin//build_defs:kotlin, ///swift//build_defs:swift, ///ts//build_defs:ts

---

Next Steps

Explore the language-specific guides and rule references:

• Rust Rules Documentation (rust branch)
• Kotlin Rules Documentation (kotlin branch)
• Swift Rules Documentation (swift branch)
• TypeScript Rules Documentation (ts branch)
• Multi-Language Gitflow Architecture: Details on branch strategy, common code syncing, and release tagging.
• Documentation Portal: Full index of rules, architecture, and references.