Skip to content

Latest commit

 

History

History
88 lines (61 loc) · 2.97 KB

devguide.md

File metadata and controls

88 lines (61 loc) · 2.97 KB
Raw

Developer Guide

The repository contains two main components:

  • dev: the development code with a concrete (register) implementation for testing. The folder also contains templates for dynamic code and all the static code that will be bundled together with the generated code.
  • -plugins/gorums: second order plugin to protoc-gen-gorums binary.

Makefile

The Makefile itself serves as documentation, inspect it for details. Important targets:

  • make gengolden: Generate and update what should be the golden output for the gorums plugin.

  • make gendev: Generate and update _gen.go files from the dev templates.

  • make gengoldenanddev: Combination of the two targets above.

File Endings

The following file ending conventions are used in the dev package:

  • _gen.go: File should be generated by the gorums plugin.
  • _udef.go File is user defined.
  • _test.go File is a Go test file.

These endings are important because all other files will be bundled together as static resources during gorums code generation (see the bundle) utility program.

Workflow

  1. Changes should be made to the development code in dev.

  2. Changes in any of the files ending with _gen.go must be reflected in the generator.

  3. If the change is in a "static" file it's enough to update the bundle of static code. This can be done by calling make genstatic.

  4. If any change is done to the static or generated code, the file representing the "golden" output of the generator must be regenerated. This can be done by running make gengolden.

See the Makefile for more details.

Testing

All tests can be invoked by running make test and/or make testrace. There are three main tests for this project:

  1. dev/config_rpc_test.go: The integration test in this package verifies that the concrete client/server register implementation works.

  2. End-to-end: This test invokes the generator with the register.proto example from dev and runs the integration test against the generated code.

  3. Golden: This test invokes the generator with the register.proto example from dev and compares the output against a golden output file in the testdata folder. This test verifies that the generator output does not change unexpectedly. The golden output file should be updated as described in the previous Workflow section if the output is expected to change.

Benchmarking

The benchcmp program is recommended for comparing benchmarks:

go get -u  golang.org/x/tools/cmd/benchcmp

Example :

git checkout devel (or another branch)
cd dev
go test . -run=$$ -bench=Read1KQ2N3Local -benchtime=3s -count=10 > old.txt
*make changes and regenerate _gen.go-files if needed*
go test . -run=$$ -bench=Read1KQ2N3Local -benchtime=3s -count=10 > new.txt
benchcmp old.txt new.txt