Skip to content

Latest commit

 

History

History
244 lines (165 loc) · 4.9 KB

manifest.md

File metadata and controls

244 lines (165 loc) · 4.9 KB
Raw

Build manifests

You tell reproto what to do by writing build manifests. The default build manifest that reproto looks for is reproto.toml in the current directory. These are stored with the project, and describe what should be built.

The following is an example manifest:

# File: reproto.toml

language = "java"

# Use a maven preset.
[presets.maven]

This specifies that reproto should built any available version of the toystore package, suitable for a Maven project.

Build paths

Build paths is specified under the paths key. These are the directories where reproto will look for local specification when they are built, imported, or published.

paths = ["src"]

Package discovery

reproto supports automatically identifying packages from your build paths.

Any .reproto file discovered in a build path will be treated as a reproto specification, whose package corresponds to the path that the package is located in.

For example, assume we have the following structure.

Manifest:

paths = [
  "src/main/reproto",
  "reproto"
]

Files:

  • src/main/reproto/io/reproto/example.reproto
  • src/main/reproto/io/reproto/other-0.0.1.reproto
  • proto/io/reproto/example-2.0.1.reproto

The build system would then identify the following packages to be built:

  • io.reproto.example (no version)
  • io.reproto.other-0.0.1
  • io.reproto.example-2.0.1

packages section

The [packages] section is an optional section which can be used to designate which packages should be built by reproto.

[packages]
"io.reproto.toystore" = "*"

This can be specified in a more elaborate format to support more options:

[packages]
"io.reproto.toystore" = {version = "*"}

Or:

[packages."io.reproto.toystore"]
version = "*"

files section

The [files] section permits building a single, local file as some specific package and version. This would typically be used to patch external manifests:

[files]
"io.reproto.toystore" = "patches/toystore.reproto"

This can be specified in a more elaborate format to support more options:

[files]
"io.reproto.toystore" = {path = "patches/toystore.reproto", version = "1.0.1"}

Or:

[files."io.reproto.toystore"]
path = "patches/toystore.reproto"
version = "1.0.1"

publish section

In order to publish packages, the version of the package needs to be known.

Since specifications would typically be unversioned during development, reproto supports a [publish] section where you can map what version a local specification belongs to.

The package specified is a prefix. The version will apply to any contained packages.

paths = ["src"]

[publish]
"io.reproto" = "1.0.1"

These can be specified in a more elaborate format:

[publish]
"io.reproto" = {version = "1.0.1"}

Or:

[publish."io.reproto"]
version = "1.0.1"

Assuming you have a specification in src/io/reproto/toystore.reproto, you can now publish it using:

$> reproto publish

Additional specifications can be added to src/io/reproto, and they will also be published with the same version.

presets section

Presets are bundles of configuration that can be activated through the presets key.

Activated presets are determined by their type.

The available types and their corresponding options are documented in this section.

maven preset

Sets default options suitable for building with a default Maven project.

# File: reproto.toml

[presets.maven]

This preset is equivalent to the following manifest:

# File: reproto.toml

paths = ["src/main/reproto"]
output = "target/generated/reproto/java"

swift preset

Sets default options suitable for building a Swift project.

# File: reproto.toml

[presets.swift]

This preset is equivalent to the following manifest:

# File: reproto.toml

paths = ["proto"]
output = "Sources/Modules"

go preset

Sets default options suitable for building a Go project.

# File: reproto.toml

[presets.go]

This preset is equivalent to the following manifest:

# File: reproto.toml

paths = ["reproto"]
output = "modules"

doc

The doc keys control how documentation is generated:

[doc]
# See available themes with `reproto doc --list-themes`.
theme = "light"

# See available themes with `reproto doc --list-syntax-themes`.
syntax_theme = "ayu-mirage"