install.md

id	title	sidebar_label
install	Installing Twirp	Installation

Runtime Library

The runtime library package github.com/twitchtv/twirp contains common types like twirp.Error. If you are only importing Twirp clients from other services, you only need to import the twirp package and the protobuf APIv2 dependency (google.golang.org/protobuf).

If the Twirp client was generated with older versions of Twirp (v5, v7), then you need to import the older protobuf APIv1 dependency (github.com/golang/protobuf).

Code Generator

You need to install go and the protoc compiler in your system. Then, install the protoc plugins protoc-gen-twirp and protoc-gen-go to generate Go code.

Prerequisites

• Go: Twirp works well with any one of the three latest major releases of Go. For installation instructions, see Go’s Getting Started guide.
• Protocol buffer compiler, protoc version 3. For installation instructions, see Protocol Buffer Compiler Installation (For example in MacOS: brew install protobuf).

Define tools.go for versioning in go.mod

You should track the Twirp and Protobuf versions like any other go-based tool (e.g. stringer). The currently recommended approach is to track the tool's version in your module's go.mod file (See "Go Modules by Example" walkthrough). For example, a tools.go file may look like this:

// +build tools

package tools

import (
        _ "google.golang.org/protobuf/cmd/protoc-gen-go"
        _ "github.com/twitchtv/twirp/protoc-gen-twirp"
)

Install Twirp and Protobuf Generators

Set GOBIN (see go help environment) to define where the tool dependencies will be installed. For example, if you have a /bin folder in your project:

export GOBIN=$PWD/bin

The installed packages need to be accessible by the protoc compiler. You might need to add GOBIN to your PATH:

export PATH=$GOBIN:$PATH

Install generators:

go install github.com/twitchtv/twirp/protoc-gen-twirp@latest
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest

Old Twirp versions (v5, v7) depend on Protobuf APIv1

Older versions of Twirp require Protobuf APIv1 instead of APIv2 (See Version Compatibility), that has a different module name:

go get github.com/twitchtv/twirp/[email protected]
go get github.com/golang/protobuf/[email protected]

Generate code

Try the protoc compiler with the flags --twirp_out and --go_out to see if it is able to generate the twirp.go and .pb.go files. See protobuf docs for details on how to use the protoc compiler with --go-out, the Twirp flag --twirp_out supports the same parameters (see Generator Flags for more options).

An example call with default parameters to generate code for rpc/haberdasher/service.proto:

protoc --go_out=. --twirp_out=. rpc/haberdasher/service.proto