Tutorial - buf build
This tutorial takes you through building a Buf image from your Protobuf files and introspecting the contents of an image.
Prerequisites
We recommend completing the Buf CLI tour to get an overview of the Buf CLI first.
- Install the Buf CLI
1. Define a workspace
To create a workspace and define the modules within it, add a buf.yaml
file to the directory that
contains your directories of .proto
files. You can create the default buf.yaml
file by running this command:
$ buf config init
version: v2
breaking:
use:
- FILE
lint:
use:
- STANDARD
Add a declaration for each directory you want to treat as a module. The value should be relative to the workspace root.
For example, if you have a directory of .proto
files named foo
, your configuration would look like this:
version: v2
modules:
- path: foo
breaking:
use:
- FILE
lint:
use:
- STANDARD
2. Build an image
To build the modules in your workspace, go to its root directory and run this command:
$ buf build
If there are errors, they're printed out in a file:line:column:message
format by default. For example:
$ buf build
Outputacme/pet/v1/pet.proto:5:8:acme/payment/v1alpha1/payment.proto: does not exist
Error output can also be printed as JSON:
$ buf build --error-format=json
Output{"path":"acme/pet/v1/pet.proto","start_line":5,"start_column":8,"end_line":5,"end_column":8,"type":"COMPILE","message":"acme/payment/v1alpha1/payment.proto: does not exist"}
3. Change the output format
By default, buf build
outputs its result to /dev/null
. In this case, it's common to use buf build
as a validation
step, analogous to checking if the input compiles.
buf build
also supports outputting a FileDescriptorSet
or an image, which is Buf's
custom extension of the FileDescriptorSet
. Better yet, these outputs can be formatted in a variety of ways.
buf build
can deduce the output format by the file extension. For example:
$ buf build -o image.binpb
$ buf build -o image.binpb.gz
$ buf build -o image.binpb.zst
$ buf build -o image.json
$ buf build -o image.json.gz
$ buf build -o image.json.zst
$ buf build -o image.txtpb
$ buf build -o image.txtpb.gz
$ buf build -o image.txtpb.zst
The special value -
is used to denote stdout, and you can manually set the format. For example:
$ buf build -o -#format=json
See the Inputs page for more information about automatically derived formats.
Related docs
- Read the overview
- Browse the
buf build
command reference