Skip to main content

9 Add a Dependency

Without the BSR, depending on other Protobuf APIs is a painful, manual process. For example, if you want to use googleapis, you're expected to clone the Git repository, and manually copy the .proto file(s) you need in order to compile your .proto files. Worse, this workflow is prone to API drift, where the latest googleapis code evolves and is therefore inconsitent with your local copy. This is exactly what we have in the current PetStoreService - the google/type/datetime.proto is copied in order to build the module.

Now that we have the BSR, this entire workflow simplifies immensely.

9.1 Remove google/type/datetime.proto#

We'll start by removing the google/type/datetime.proto file from our module altogether. From within the petapis directory, run the following command:

$ rm -rf google

Then, remove the google/type/datetime.proto reference from your buf.yaml:

buf.yaml
 version: v1 lint:   use:     - DEFAULT-  ignore:-    - google/type/datetime.proto breaking:   use:     - FILE

If you try to build the module in its current state, you will notice an error:

$ buf buildpet/v1/pet.proto:7:8:google/type/datetime.proto: does not exist

9.2 Depend on buf.build/googleapis/googleapis#

We can resolve this error by configuring a dependency in your buf.yaml's deps key. The google/type/datetime.proto file is provided by the buf.build/googleapis/googleapis module, so we can configure it like so:

buf.yaml
 version: v1+deps:+  - buf.build/googleapis/googleapis lint:   use:     - DEFAULT breaking:   use:     - FILE

Now, if you try to build the module again, you'll notice the following:

$ buf buildWARN    Specified deps are not covered in your buf.lock, run "buf mod update":    - buf.build/googleapis/googleapispet/v1/pet.proto:7:8:google/type/datetime.proto: does not exist

buf detected that we specified a dependency that isn't included in the module's buf.lock file, which is your module's dependency manifest, and represents a single, reproducible build of your module's dependencies. We don't even have a buf.lock file yet, but we can create one with the command that buf recommended above:

$ buf mod update

The buf mod update command updates all of your deps to their latest version. The generated buf.lock will look similar to the following (the commit, digest, and create_time may vary):

buf.lock
# Generated by buf. DO NOT EDIT.version: v1deps:  - remote: buf.build    owner: googleapis    repository: googleapis    branch: main    commit: 1c473ad9220a49bca9320f4cc690eba5    digest: b1-unlhrcI3tnJd0JEGuOb692LZ_tY_gCGq6mK1bgCn1Pg=    create_time: ...

Now, if we try to build the module again, you'll notice that it's successful:

$ buf buildbuf: downloading buf.build/googleapis/googleapis:1c473ad9220a49bca9320f4cc690eba5

This is the BSR's dependency management in action! A few things happened here, so let's break it down:

  1. buf noticed that a new dependency was added to the deps key.
  2. buf resolved the latest version of the buf.build/googleapis/googleapis module, and wrote it to the module's buf.lock.
  3. When another buf command is run, buf downloads the buf.build/googleapis/googleapis module to the local module cache.
  4. Finally, now that buf has all of the dependencies it needs, it can successfully build the module (i.e. with google/type/datetime.proto included).

In summary, buf is able to resolve the dependencies specified in your buf.yaml's deps key, and include the imports required to build your module. You don't have to manually copy .proto files anymore!

9.3 Pin Your Dependencies#

You can pin to a specific tag or commit by specifying it in your deps after the : delimiter. For example, if you want to depend on the same commit we resolved above and prevent buf from updating it in the future, you can specify it like so:

buf.yaml
 version: v1 deps:-  - buf.build/googleapis/googleapis+  - buf.build/googleapis/googleapis:1c473ad9220a49bca9320f4cc690eba5 lint:   use:     - DEFAULT breaking:   use:     - FILE

This is not recommended in general since you should always be able to update to the latest version of your dependencies if they remain backwards compatible. However, in some situations it is unavoidable. With that said, restore the buf.yaml file to its previous state before we continue:

buf.yaml
 version: v1 deps:-  - buf.build/googleapis/googleapis:1c473ad9220a49bca9320f4cc690eba5+  - buf.build/googleapis/googleapis lint:   use:     - DEFAULT breaking:   use:     - FILE

9.4 Push Your Changes#

Now that we've updated our module to depend on buf.build/googleapis/googleapis instead of vendoring the google/type/datetime.proto ourselves, we can push the module to the BSR:

$ buf pushb2917eb692064beb92ad1e38dba6c25e