@aptre/common 0.30.0 → 0.30.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +131 -70
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
[![GoDoc Widget]][GoDoc] [![Go Report Card Widget]][Go Report Card] [![npm Widget]][npm]
|
|
4
4
|
|
|
5
|
-
>
|
|
5
|
+
> Unified protobuf code generation for Go, TypeScript, C++, and Rust with WASM.
|
|
6
6
|
|
|
7
7
|
[GoDoc]: https://godoc.org/github.com/aperturerobotics/common
|
|
8
8
|
[GoDoc Widget]: https://godoc.org/github.com/aperturerobotics/common?status.svg
|
|
@@ -11,114 +11,162 @@
|
|
|
11
11
|
[npm]: https://www.npmjs.com/package/@aptre/common
|
|
12
12
|
[npm Widget]: https://img.shields.io/npm/v/@aptre/common.svg
|
|
13
13
|
|
|
14
|
-
##
|
|
14
|
+
## What is this?
|
|
15
15
|
|
|
16
|
-
-
|
|
17
|
-
- [protobuf-project](https://github.com/aperturerobotics/protobuf-project) - More extensive example
|
|
16
|
+
This repository provides the `aptre` CLI — a single tool that generates protobuf code for **four languages** without requiring you to install protoc, protoc plugins, or language-specific toolchains. Everything runs via embedded WebAssembly modules using [wazero].
|
|
18
17
|
|
|
19
|
-
|
|
18
|
+
[wazero]: https://github.com/tetratelabs/wazero
|
|
19
|
+
|
|
20
|
+
### Key Features
|
|
21
|
+
|
|
22
|
+
- **Zero native dependencies** — protoc and plugins run as WASM, no installation required
|
|
23
|
+
- **Multi-language output** — generates Go, TypeScript, C++, and Rust from a single command
|
|
24
|
+
- **Smart caching** — only regenerates when source files actually change
|
|
25
|
+
- **Go-style imports** — use familiar import paths in your `.proto` files
|
|
26
|
+
|
|
27
|
+
## Supported Languages
|
|
28
|
+
|
|
29
|
+
| Language | Message Types | RPC Services | Plugin |
|
|
30
|
+
| ---------- | ------------- | ------------------- | -------------------------- |
|
|
31
|
+
| Go | `*.pb.go` | `*_srpc.pb.go` | [protobuf-go-lite] |
|
|
32
|
+
| TypeScript | `*.pb.ts` | `*_srpc.pb.ts` | [protobuf-es-lite] |
|
|
33
|
+
| C++ | `*.pb.cc/h` | `*_srpc.pb.hpp/cpp` | Built-in protoc + [starpc] |
|
|
34
|
+
| Rust | `*.pb.rs` | `*_srpc.pb.rs` | [prost] (WASI) + [starpc] |
|
|
35
|
+
|
|
36
|
+
[protobuf-go-lite]: https://github.com/aperturerobotics/protobuf-go-lite
|
|
37
|
+
[protobuf-es-lite]: https://github.com/aperturerobotics/protobuf-es-lite
|
|
38
|
+
[starpc]: https://github.com/aperturerobotics/starpc
|
|
39
|
+
[prost]: https://github.com/tokio-rs/prost
|
|
40
|
+
|
|
41
|
+
## Rust Support via WASI
|
|
42
|
+
|
|
43
|
+
The Rust code generation uses an embedded [WASI] build of `protoc-gen-prost`, meaning **you don't need Cargo, rustc, or any Rust toolchain installed** to generate `.pb.rs` files. The prost plugin runs entirely within the wazero WebAssembly runtime alongside protoc itself.
|
|
44
|
+
|
|
45
|
+
[WASI]: https://wasi.dev/
|
|
20
46
|
|
|
21
|
-
|
|
47
|
+
This is powered by [go-protoc-gen-prost], which embeds a ~600KB WASM binary that implements the full prost protobuf code generator.
|
|
48
|
+
|
|
49
|
+
[go-protoc-gen-prost]: https://github.com/aperturerobotics/go-protoc-gen-prost
|
|
50
|
+
|
|
51
|
+
### Example Output
|
|
52
|
+
|
|
53
|
+
Given a simple proto file:
|
|
54
|
+
|
|
55
|
+
```protobuf
|
|
56
|
+
syntax = "proto3";
|
|
57
|
+
package echo;
|
|
58
|
+
|
|
59
|
+
message EchoMsg {
|
|
60
|
+
string body = 1;
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
The generated `echo.pb.rs`:
|
|
65
|
+
|
|
66
|
+
```rust
|
|
67
|
+
// @generated
|
|
68
|
+
// This file is @generated by prost-build.
|
|
69
|
+
#[derive(Clone, PartialEq, Eq, Hash, ::prost::Message)]
|
|
70
|
+
pub struct EchoMsg {
|
|
71
|
+
#[prost(string, tag="1")]
|
|
72
|
+
pub body: ::prost::alloc::string::String,
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
See [starpc](https://github.com/aperturerobotics/starpc) for a complete example.
|
|
77
|
+
|
|
78
|
+
## Installation
|
|
22
79
|
|
|
23
80
|
```bash
|
|
24
|
-
# Run directly
|
|
25
|
-
go run github.com/aperturerobotics/common/cmd/aptre@latest
|
|
81
|
+
# Run directly (no install needed)
|
|
82
|
+
go run github.com/aperturerobotics/common/cmd/aptre@latest generate
|
|
26
83
|
|
|
27
84
|
# Or install globally
|
|
28
85
|
go install github.com/aperturerobotics/common/cmd/aptre@latest
|
|
29
86
|
```
|
|
30
87
|
|
|
31
|
-
##
|
|
88
|
+
## Quick Start
|
|
32
89
|
|
|
33
|
-
|
|
90
|
+
1. **Set up your project** with Go and optionally TypeScript:
|
|
34
91
|
|
|
35
92
|
```bash
|
|
36
|
-
|
|
93
|
+
# Initialize Go module
|
|
94
|
+
go mod init github.com/yourorg/yourproject
|
|
37
95
|
```
|
|
38
96
|
|
|
39
|
-
|
|
97
|
+
2. **Create a proto file** using Go-style imports:
|
|
40
98
|
|
|
41
99
|
```protobuf
|
|
42
100
|
syntax = "proto3";
|
|
43
101
|
package example;
|
|
44
102
|
|
|
45
|
-
// Import .proto files using Go-style import paths
|
|
103
|
+
// Import .proto files using Go-style import paths
|
|
46
104
|
import "github.com/aperturerobotics/controllerbus/controller/controller.proto";
|
|
47
105
|
|
|
48
|
-
// GetBusInfoResponse is the response type for GetBusInfo.
|
|
49
106
|
message GetBusInfoResponse {
|
|
50
|
-
// RunningControllers is the list of running controllers.
|
|
51
107
|
repeated controller.Info running_controllers = 1;
|
|
52
108
|
}
|
|
53
109
|
```
|
|
54
110
|
|
|
55
|
-
|
|
111
|
+
3. **Generate code**:
|
|
56
112
|
|
|
57
113
|
```bash
|
|
114
|
+
# Stage files for git (required for discovery)
|
|
58
115
|
git add -A
|
|
59
|
-
|
|
60
|
-
#
|
|
61
|
-
|
|
116
|
+
|
|
117
|
+
# Generate all languages
|
|
118
|
+
go run github.com/aperturerobotics/common/cmd/aptre@latest generate
|
|
119
|
+
|
|
120
|
+
# Or with verbose output
|
|
121
|
+
go run github.com/aperturerobotics/common/cmd/aptre@latest generate --verbose
|
|
62
122
|
```
|
|
63
123
|
|
|
64
|
-
## Commands
|
|
65
|
-
|
|
66
|
-
The `aptre` CLI provides the following commands:
|
|
67
|
-
|
|
68
|
-
| Command | Description |
|
|
69
|
-
| ---------------- | -------------------------------------------- |
|
|
70
|
-
| `generate` | Generate protobuf code (Go, TypeScript, C++) |
|
|
71
|
-
| `clean` | Remove generated files and cache |
|
|
72
|
-
| `deps` | Ensure all dependencies are installed |
|
|
73
|
-
| `lint` | Run golangci-lint |
|
|
74
|
-
| `fix` | Run golangci-lint with --fix |
|
|
75
|
-
| `test` | Run go test |
|
|
76
|
-
| `test --browser` | Run tests in browser with WebAssembly |
|
|
77
|
-
| `format` | Format Go code with gofumpt |
|
|
78
|
-
| `goimports` | Run goimports |
|
|
79
|
-
| `outdated` | Show outdated dependencies |
|
|
80
|
-
| `release run` | Create a release using goreleaser |
|
|
81
|
-
| `release bundle` | Create a bundled snapshot release |
|
|
82
|
-
| `release build` | Build a snapshot release |
|
|
83
|
-
| `release check` | Run goreleaser checks |
|
|
84
|
-
|
|
85
|
-
### Examples
|
|
124
|
+
## CLI Commands
|
|
86
125
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
126
|
+
| Command | Description |
|
|
127
|
+
| ------------------ | -------------------------------------------------- |
|
|
128
|
+
| `generate` | Generate protobuf code (Go, TypeScript, C++, Rust) |
|
|
129
|
+
| `generate --force` | Regenerate all files, ignoring cache |
|
|
130
|
+
| `clean` | Remove generated files and cache |
|
|
131
|
+
| `deps` | Ensure all dependencies are installed |
|
|
132
|
+
| `lint` | Run golangci-lint |
|
|
133
|
+
| `fix` | Run golangci-lint with --fix |
|
|
134
|
+
| `test` | Run go test |
|
|
135
|
+
| `test --browser` | Run tests in browser with WebAssembly |
|
|
136
|
+
| `format` | Format Go code with gofumpt |
|
|
137
|
+
| `outdated` | Show outdated dependencies |
|
|
90
138
|
|
|
91
|
-
|
|
92
|
-
go run ./cmd/aptre generate --force
|
|
139
|
+
## How It Works
|
|
93
140
|
|
|
94
|
-
|
|
95
|
-
go run ./cmd/aptre test
|
|
141
|
+
The `aptre` tool orchestrates code generation using embedded WebAssembly:
|
|
96
142
|
|
|
97
|
-
|
|
98
|
-
|
|
143
|
+
1. **Discovery** — Finds `.proto` files matching your targets (default: `./*.proto`)
|
|
144
|
+
2. **Caching** — Checks `.protoc-manifest.json` to skip unchanged files
|
|
145
|
+
3. **Protoc (WASM)** — Runs [go-protoc-wasi] to parse protos and invoke plugins
|
|
146
|
+
4. **Plugins** — Native plugins for Go/TS, WASM plugin for Rust (prost)
|
|
147
|
+
5. **Post-processing** — Fixes imports and formats output
|
|
99
148
|
|
|
100
|
-
|
|
101
|
-
go run ./cmd/aptre lint
|
|
149
|
+
[go-protoc-wasi]: https://github.com/aperturerobotics/go-protoc-wasi
|
|
102
150
|
|
|
103
|
-
|
|
104
|
-
go run ./cmd/aptre format
|
|
151
|
+
### Architecture
|
|
105
152
|
|
|
106
|
-
|
|
107
|
-
|
|
153
|
+
```
|
|
154
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
155
|
+
│ aptre CLI │
|
|
156
|
+
├─────────────────────────────────────────────────────────────┤
|
|
157
|
+
│ wazero runtime │
|
|
158
|
+
├─────────────┬─────────────────────────┬─────────────────────┤
|
|
159
|
+
│ protoc.wasm │ protoc-gen-prost.wasm │ Native Plugins │
|
|
160
|
+
│ (parsing) │ (Rust output) │ (Go, TS, C++) │
|
|
161
|
+
└─────────────┴─────────────────────────┴─────────────────────┘
|
|
108
162
|
```
|
|
109
163
|
|
|
110
164
|
## C++ Support
|
|
111
165
|
|
|
112
|
-
C++ protobuf files (`.pb.cc` and `.pb.h`) are generated alongside
|
|
113
|
-
files. Add `vendor/` to your include path and create a symlink for your project:
|
|
166
|
+
C++ protobuf files (`.pb.cc` and `.pb.h`) are generated alongside other outputs. Add `vendor/` to your include path:
|
|
114
167
|
|
|
115
168
|
```cmake
|
|
116
169
|
# CMakeLists.txt
|
|
117
|
-
set(VENDOR_LINK_DIR "${CMAKE_CURRENT_SOURCE_DIR}/vendor/github.com/yourorg")
|
|
118
|
-
if(NOT EXISTS "${VENDOR_LINK_DIR}/yourproject")
|
|
119
|
-
file(CREATE_LINK "${CMAKE_CURRENT_SOURCE_DIR}" "${VENDOR_LINK_DIR}/yourproject" SYMBOLIC)
|
|
120
|
-
endif()
|
|
121
|
-
|
|
122
170
|
include_directories(${PROJECT_SOURCE_DIR}/vendor)
|
|
123
171
|
```
|
|
124
172
|
|
|
@@ -126,21 +174,34 @@ include_directories(${PROJECT_SOURCE_DIR}/vendor)
|
|
|
126
174
|
#include "github.com/yourorg/yourproject/example/example.pb.h"
|
|
127
175
|
```
|
|
128
176
|
|
|
129
|
-
|
|
177
|
+
For StarPC C++ services, the `*_srpc.pb.hpp` files provide client/server stubs.
|
|
130
178
|
|
|
131
|
-
|
|
132
|
-
This means you don't need to install protoc separately - it works on any platform
|
|
133
|
-
that supports Go.
|
|
179
|
+
## Configuration
|
|
134
180
|
|
|
135
|
-
|
|
181
|
+
The generator uses sensible defaults but can be customized:
|
|
182
|
+
|
|
183
|
+
- **Targets**: Proto file patterns (default: `./*.proto`)
|
|
184
|
+
- **Exclude**: Patterns to skip (e.g., `vendor/**`)
|
|
185
|
+
- **ToolsDir**: Plugin binary location (default: `.tools`)
|
|
186
|
+
- **Cache**: Manifest file (default: `.protoc-manifest.json`)
|
|
187
|
+
|
|
188
|
+
## Related Projects
|
|
189
|
+
|
|
190
|
+
- [starpc](https://github.com/aperturerobotics/starpc) — Streaming RPC for Go, TypeScript, and Rust
|
|
191
|
+
- [protobuf-go-lite](https://github.com/aperturerobotics/protobuf-go-lite) — Lightweight Go protobuf without reflection
|
|
192
|
+
- [protobuf-es-lite](https://github.com/aperturerobotics/protobuf-es-lite) — Lightweight TypeScript protobuf
|
|
193
|
+
- [go-protoc-wasi](https://github.com/aperturerobotics/go-protoc-wasi) — Embedded protoc as WASM
|
|
194
|
+
- [go-protoc-gen-prost](https://github.com/aperturerobotics/go-protoc-gen-prost) — Prost plugin as WASM
|
|
195
|
+
- [template](https://github.com/aperturerobotics/template) — Project template using this package
|
|
196
|
+
- [protobuf-project](https://github.com/aperturerobotics/protobuf-project) — More extensive example
|
|
136
197
|
|
|
137
198
|
## Support
|
|
138
199
|
|
|
139
|
-
Please open a [GitHub issue] with any questions
|
|
200
|
+
Please open a [GitHub issue] with any questions or issues.
|
|
140
201
|
|
|
141
202
|
[GitHub issue]: https://github.com/aperturerobotics/common/issues/new
|
|
142
203
|
|
|
143
|
-
... or
|
|
204
|
+
... or reach out on [Matrix Chat] or [Discord].
|
|
144
205
|
|
|
145
206
|
[Matrix Chat]: https://matrix.to/#/#aperturerobotics:matrix.org
|
|
146
207
|
[Discord]: https://discord.gg/KJutMESRsT
|