Skip to content

Commit d97caa2

Browse files
committed
docs: update HELP.md for multi-template repository
- Add documentation for both Kotlin Spring and Go Gin templates - Include template selection guide (sparse checkout) - Add Go-specific workflows (go.mod, gazelle, bazel mod tidy) - Update prerequisites and troubleshooting sections - Reorganize content for better readability
1 parent 4469662 commit d97caa2

1 file changed

Lines changed: 236 additions & 12 deletions

File tree

HELP.md

Lines changed: 236 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,67 @@
11
# Help
22

3-
## Prerequisites
3+
## Available Templates
44

5-
- [Bazelisk](https://github.com/bazelbuild/bazelisk) (recommended) or Bazel 7.0+
6-
- JDK 17 or higher
5+
This repository contains multiple Bazel project templates:
76

8-
## Creating a New Module
7+
- **Kotlin Spring** (`kotlin/spring/`) - Multi-module Spring Boot template
8+
- **Go Gin** (`go/gin/`) - Single-module Gin web framework template
9+
10+
Each template is an independent Bazel workspace with its own `MODULE.bazel`.
11+
12+
## Using a Template
13+
14+
### Option 1: Clone Specific Template (Recommended)
15+
16+
Using Git sparse checkout to get only the template you need:
17+
18+
```bash
19+
# Clone with sparse checkout
20+
git clone --filter=blob:none --sparse https://github.com/EntryDSM/entrydsm-bazel-template
21+
cd entrydsm-bazel-template
22+
23+
# Checkout Kotlin Spring template
24+
git sparse-checkout set kotlin/spring
25+
26+
# OR checkout Go Gin template
27+
git sparse-checkout set go/gin
28+
```
29+
30+
### Option 2: Copy Template Directory
31+
32+
```bash
33+
# Clone entire repository
34+
git clone https://github.com/EntryDSM/entrydsm-bazel-template
35+
36+
# Copy the template you want
37+
cp -r entrydsm-bazel-template/kotlin/spring my-project
38+
# OR
39+
cp -r entrydsm-bazel-template/go/gin my-project
40+
41+
cd my-project
42+
```
43+
44+
---
45+
46+
## Kotlin Spring Template
47+
48+
### Prerequisites
49+
50+
- [Bazelisk](https://github.com/bazelbuild/bazelisk) (recommended) or Bazel 8.5+
51+
- JDK 21 or higher
52+
53+
### Project Structure
54+
55+
```
56+
kotlin/spring/
57+
├── MODULE.bazel # Bazel module definition
58+
├── BUILD.bazel # Root build file
59+
├── kotlin.bzl # Kotlin compiler configuration
60+
├── module-a/ # Example module
61+
└── module-b/ # Example module
62+
```
63+
64+
### Creating a New Module
965

1066
1. Create the module directory structure:
1167
```bash
@@ -14,7 +70,7 @@ mkdir -p module-name/src/test/kotlin
1470
```
1571

1672
2. Create `module-name/deps.bzl`:
17-
```bzl
73+
```starlark
1874
MODULE_DEPS = [
1975
"@maven//:org_springframework_boot_spring_boot_starter_web",
2076
]
@@ -25,7 +81,7 @@ TEST_DEPS = [
2581
```
2682

2783
3. Create `module-name/BUILD.bazel`:
28-
```bzl
84+
```starlark
2985
load("@rules_kotlin//kotlin:jvm.bzl", "kt_jvm_binary", "kt_jvm_test")
3086
load("//:kotlin.bzl", "setup_kotlin_compiler", "setup_spring_allopen_plugin")
3187
load("//module-name:deps.bzl", "MODULE_DEPS", "TEST_DEPS")
@@ -56,27 +112,29 @@ kt_jvm_test(
56112
)
57113
```
58114

59-
## Adding Dependencies
115+
### Adding Maven Dependencies
60116

61-
1. Add the Maven artifact to `MODULE.bazel`:
62-
```bzl
117+
1. Add the artifact to `MODULE.bazel`:
118+
```starlark
63119
maven.artifact(
64120
artifact = "artifact-name",
65121
group = "group.id",
66122
version = VERSION_CONSTANT,
67123
)
68124
```
69125

70-
2. Add the dependency to your module's `deps.bzl`:
71-
```bzl
126+
2. Add to your module's `deps.bzl`:
127+
```starlark
72128
MODULE_DEPS = [
73129
"@maven//:group_id_artifact_name",
74130
]
75131
```
76132

77-
## Building and Testing
133+
### Building and Testing
78134

79135
```bash
136+
cd kotlin/spring
137+
80138
# Build all targets
81139
bazel build //...
82140

@@ -87,8 +145,174 @@ bazel test //...
87145
bazel run //module-name:main
88146
```
89147

148+
---
149+
150+
## Go Gin Template
151+
152+
### Prerequisites
153+
154+
- [Bazelisk](https://github.com/bazelbuild/bazelisk) (recommended) or Bazel 8.5+
155+
- Go 1.25+ (optional, Bazel will download)
156+
157+
### Project Structure
158+
159+
```
160+
go/gin/
161+
├── MODULE.bazel # Bazel module definition
162+
├── BUILD.bazel # Gazelle configuration
163+
├── go.mod # Go module (dependency source of truth)
164+
├── go.sum # Go checksums
165+
└── cmd/
166+
└── server/ # Server binary
167+
├── main.go
168+
└── main_test.go
169+
```
170+
171+
### Adding Go Dependencies
172+
173+
1. Add dependency using Go tools:
174+
```bash
175+
cd go/gin
176+
go get github.com/some/package@version
177+
```
178+
179+
2. Update Bazel:
180+
```bash
181+
bazel mod tidy
182+
```
183+
184+
The `go.mod` file is the single source of truth for dependencies.
185+
186+
### Creating New Packages
187+
188+
1. Create your Go files:
189+
```bash
190+
mkdir -p internal/mypackage
191+
# Write your .go files
192+
```
193+
194+
2. Run Gazelle to generate BUILD files:
195+
```bash
196+
bazel run //:gazelle
197+
```
198+
199+
### Building and Testing
200+
201+
```bash
202+
cd go/gin
203+
204+
# Update dependencies
205+
bazel mod tidy
206+
207+
# Build all targets
208+
bazel build //...
209+
210+
# Run all tests
211+
bazel test //...
212+
213+
# Run the server
214+
bazel run //cmd/server
215+
```
216+
217+
### Running the Server Locally
218+
219+
```bash
220+
# Using Bazel
221+
bazel run //cmd/server
222+
223+
# OR using Go directly
224+
go run cmd/server/main.go
225+
```
226+
227+
The server will start on `http://localhost:8080` with:
228+
- `GET /health` - Health check endpoint
229+
230+
---
231+
232+
## Common Commands
233+
234+
### Bazel
235+
236+
```bash
237+
# Clean build cache
238+
bazel clean
239+
240+
# Show build graph
241+
bazel query //...
242+
243+
# Build with verbose output
244+
bazel build //... --verbose_failures
245+
246+
# Run specific test
247+
bazel test //path/to:test_target
248+
```
249+
250+
### Go-Specific (in go/gin/)
251+
252+
```bash
253+
# Update go.mod and go.sum
254+
go mod tidy
255+
256+
# Update Bazel BUILD files
257+
bazel run //:gazelle
258+
259+
# Update dependencies in MODULE.bazel
260+
bazel mod tidy
261+
```
262+
263+
### Kotlin-Specific (in kotlin/spring/)
264+
265+
```bash
266+
# Format Kotlin code
267+
bazel run @kotlin_formatter//file
268+
269+
# Run with JVM debug
270+
bazel run //module:main --jvmopt=-agentlib:jdwp=...
271+
```
272+
273+
---
274+
90275
## Getting Help
91276

92277
- [Bazel Documentation](https://bazel.build/docs)
93278
- [rules_kotlin Documentation](https://github.com/bazelbuild/rules_kotlin)
279+
- [rules_go Documentation](https://github.com/bazel-contrib/rules_go)
280+
- [Gazelle Documentation](https://github.com/bazel-contrib/bazel-gazelle)
94281
- [Issue Tracker](../../issues)
282+
283+
---
284+
285+
## Troubleshooting
286+
287+
### "No such package" errors
288+
289+
Run `bazel clean` and rebuild:
290+
```bash
291+
bazel clean
292+
bazel build //...
293+
```
294+
295+
### Go dependency issues
296+
297+
1. Update go.mod:
298+
```bash
299+
go mod tidy
300+
```
301+
302+
2. Update Bazel:
303+
```bash
304+
bazel mod tidy
305+
```
306+
307+
3. Rebuild:
308+
```bash
309+
bazel build //...
310+
```
311+
312+
### Maven dependency not found (Kotlin)
313+
314+
1. Check dependency is in `MODULE.bazel`
315+
2. Verify the Maven coordinate format:
316+
- Group: `com.example``com_example`
317+
- Artifact: `my-lib``my_lib`
318+
- Full: `@maven//:com_example_my_lib`

0 commit comments

Comments
 (0)