From b6e7f2555961688c2946102f8c02e0280ecc78b0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Orkun=20K=C3=BCl=C3=A7e?= <kulceorkun@gmail.com>
Date: Tue, 13 Aug 2019 17:05:06 +0300
Subject: [PATCH] Document prototool usage

---
 docs/weave-tutorial/03-codec.md | 74 ++++++++++++++++++++++++++++++++-
 1 file changed, 73 insertions(+), 1 deletion(-)

diff --git a/docs/weave-tutorial/03-codec.md b/docs/weave-tutorial/03-codec.md
index aaf9fa57..50afab67 100644
--- a/docs/weave-tutorial/03-codec.md
+++ b/docs/weave-tutorial/03-codec.md
@@ -114,7 +114,79 @@ As you can see above we define necessary fields that will be used by `handler` t
 
 To compile protobuf files, you need to have the [protoc](https://github.com/google/protobuf#protocol-compiler-installation) binary installed and a language-specific translator (gogo-protobuf in this case). This can be a bit of a pain, especially the first time, so the default **weave-starter-kit** [Makefile](https://github.com/iov-one/weave-starter-kit/blob/master/Makefile) contains helpers for you.
 
-After defining your state and messages run `make protoc`. This script will download `prototool` docker image that is for making protooling easier) and compile codec.proto file `codec.pb.go` file.
+### Prototool
+
+At IOV, we use [prototool](https://github.com/iov-one/prototool-docker) for linting, formating and generating protobuf files. It is highly convenient and easy to use. Generating `*.pb.go` files are easy as running `make protoc` with Makefile script. Configuration is easier, just edit `prototool.yaml` or `prototool.json`.
+
+Here is the [prototool.yaml](https://github.com/iov-one/weave-starter-kit/blob/master/prototool.yaml) from **weave-starter-kit**:
+
+```yaml
+protoc:
+  version: 3.7.1 # Defines which version of protoc to use
+
+  # If not set, compile will fail if there are unused imports.
+  # Setting this will ignore unused imports.
+  allow_unused_imports: false
+
+  # Import parths
+  includes:
+    - .
+    - /usr/include
+    - spec
+    - spec/github.com/iov-one/weave
+
+# excluded paths
+excludes:
+  - .git
+  - spec
+
+generate:
+  go_options:
+    import_path: github.com/iov-one/weave-starter-kit
+
+  plugins:
+    - name: gogofaster # Indicates gogofaster will be used.
+      type: gogo
+      output: .
+
+lint:
+  rules:
+    remove:
+      - FILE_OPTIONS_REQUIRE_JAVA_MULTIPLE_FILES
+      - FILE_OPTIONS_REQUIRE_JAVA_OUTER_CLASSNAME
+      - FILE_OPTIONS_REQUIRE_JAVA_PACKAGE
+      - FILE_OPTIONS_REQUIRE_GO_PACKAGE
+```
+
+- `includes` field contains which import paths will be used when running protoc.
+
+  - `.` means that `import "x/custom/codec.go"` will work inside this app (recommended to avoid GOPATH issues)
+  - `spec` means that we can `import "github.com/iov-one/weave/coins/codec.proto"` and it will use the protobuf file from our spec directory (which must be kept up to date with the weave repo).
+  - `spec/github.com/iov-one/weave` is needed as if we import eg. `github.com/iov-one/weave/x/cash/codec.proto`, it imports `coins/codec.proto` using relative imports to it's project. When we then import this via spec, the relative import doesn't work without this second line.
+  
+- `excludes` field contains which paths to exclude when compiling protobuf. `spec` directory contains the weave codecs that will be used in modules, so no need to compile these.
+
+```yaml
+generate:
+  go_options:
+    import_path: github.com/iov-one/weave-starter-kit
+```
+
+- The base import path. This should be the go path of the prototool.yaml file. This is required if you have any go plugins.
+
+```yaml
+plugins:
+    - name: gogofaster # Indicates gogofaster will be used.
+      type: gogo
+      output: .
+```
+
+- This part tells protool to use `gogofaster` plugin and output is current directory.
+You are welcome to use other codecs than `gogofaster`, you can also try the standard Go language protobuf compiler. What this mode goes is auto-generate static code for serialization and deserialization of the type. It performs the introspection one time to generate efficient code allowing us to avoid the use of reflection at runtime and get ~10x speed ups in the serialization/deserialization. I like this, but this may vary based on your preference or aversion of auto-generated code.
+
+- `lint` field defines the linting rules. Extra rules could be added if desired.
+
+After defining your state and messages run `make protoc`. This script will download `prototool` docker image and compile codec.proto file `codec.pb.go` file.
 Now we have scaffold of our application thanks to auto-generated *codec.pb.go* file.
 
 ## Using Autogenerated Structs