buffrs 0.13.0

Modern protobuf package management
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

# The Manifest Format

The Buffrs manifest file is named `Proto.toml` and is placed at the root of a
Buffrs package or workspace. It is written in [TOML](https://toml.io/) format.

## Fields

### `edition`

```toml
edition = "0.12"
```

The `edition` field declares which edition of the Buffrs manifest format is
being used. The edition is tied to the minor version of buffrs that introduced
it, so `"0.12"` means the edition introduced with buffrs `0.12.x`.

Editions are set automatically when you create a new package with
[`buffrs init`](../commands/buffrs-init.md) or [`buffrs new`](../commands/buffrs-new.md)
and are validated on load. If the edition is incompatible with the installed
buffrs version, an error is reported.

See [Editions](editions.md) for more information.

### `[package]`

The `[package]` section declares metadata about the current package. It is
optional when using a [workspace](../guide/workspaces.md)-only manifest.

```toml
[package]
type = "api"
name = "my-api"
version = "1.0.0"
description = "My API package"   # optional
```

| Field | Required | Description |
|-------|----------|-------------|
| `type` | yes | Package type: `"api"`, `"lib"`, or `"impl"` |
| `name` | yes | Package name – must be lowercase ASCII and dashes (see [Package Name Specifications](package-name-spec.md)) |
| `version` | yes | [Semantic version](https://semver.org/) of the package (e.g. `"1.2.3"`) |
| `description` | no | A short human-readable description of the package |

See [Package Types](../guide/package-types.md) for more information.

### `[dependencies]`

The `[dependencies]` section lists the packages that this package depends on.
Each entry maps a package name to a dependency specification.

#### Remote dependency

```toml
[dependencies]
my-package = { registry = "https://your.registry/artifactory", repository = "my-repo", version = "1.2.3" }
```

| Field | Required | Description |
|-------|----------|-------------|
| `registry` | yes | URL of the Artifactory registry |
| `repository` | yes | Name of the repository within the registry |
| `version` | yes | Exact version to install (e.g. `"1.2.3"`) |

#### Local dependency

```toml
[dependencies]
my-lib = { path = "../my-lib" }
```

| Field | Required | Description |
|-------|----------|-------------|
| `path` | yes | Relative path to the local package directory |

See [Local Dependencies](../guide/local-dependencies.md) and
[Specifying Dependencies](specifying-dependencies.md) for more details.

### `[workspace]`

The `[workspace]` section turns the manifest into a workspace root. It is
mutually exclusive with the `[package]` section (a file can be either a
workspace root or a package, not both).

```toml
[workspace]
members = ["pkg1", "pkg2"]
```

| Field | Required | Description |
|-------|----------|-------------|
| `members` | yes | List of relative paths to workspace member package directories |

See [Workspaces](../guide/workspaces.md) for more information.

## Examples

### Minimal implementation manifest

```toml
edition = "0.12"
```

### API package with a remote dependency

```toml
edition = "0.12"

[package]
type = "api"
name = "my-api"
version = "0.1.0"

[dependencies]
common-types = { registry = "https://your.registry/artifactory", repository = "protos", version = "1.0.0" }
```

### Library package

```toml
edition = "0.12"

[package]
type = "lib"
name = "common-types"
version = "1.0.0"
description = "Shared protobuf type definitions"
```

### Workspace manifest

```toml
edition = "0.12"

[workspace]
members = ["api", "lib"]
```