hz install

hz is a tool provided by the Hertz framework for generating code. Currently, hz can generate scaffolding for Hertz projects based on thrift and protobuf’s IDL.

Install

1. Make sure the GOPATH environment variable has been defined correctly (eg export GOPATH=~/go) and add $GOPATH/bin to the PATH environment (eg export PATH=$GOPATH/bin:$PATH); do not set GOPATH to a directory that the current user does not have read/write access to.

2. Install hz:

   go install github.com/cloudwego/hertz/cmd/hz@latest
   

3. Verify that the installation was successful hz -v, if the following version message is displayed, the installation was successful

   hz version v0.x.x
   

Note，Since hz creates soft links to its own binary, make sure that the installation path of hz has writable permissions.

Operating mode

To generate code using thrift or protobuf IDL, The corresponding compiler needs to be installed: thriftgo or protoc.

The code generated by hz, part of it is generated by the underlying compiler (usually about the struct defined in IDL), and the other part is the user-defined routing, method and other information in IDL. The user can run the code directly.

In terms of execution flow, when hz uses thrift IDL to generate code, hz calls thriftgo to generate the go struct code and executes itself as a plugin to thriftgo (named thrift-gen-hertz) to generate the rest of the code. This is also true when used with the protobuf IDL.

$> hz  ... --idl=IDL
    |
    | thrift-IDL
    |---------> thriftgo --gen go:... -plugin=hertz:... IDL
    |
    | protobuf-IDL
     ---------> protoc --hertz_out=... --hertz_opt=... IDL

How to install thriftgo/protoc:

thriftgo:

GO111MODULE=on go install github.com/cloudwego/thriftgo@latest

protoc:

// brew installation
$ brew install protobuf

// Official image installation, using macos as an example
$ wget https://github.com/protocolbuffers/protobuf/releases/download/v3.19.4/protoc-3.19.4-osx-x86_64.zip
$ unzip protoc-3.19.4-osx-x86_64.zip
$ cp bin/protoc /usr/local/bin/protoc
// Make sure include/google goes under /usr/local/include
$ cp -r include/google /usr/local/include/google