Skip to content

dev-guide.md

Latest commit

 

History

History
109 lines (78 loc) · 5.54 KB

dev-guide.md

File metadata and controls

109 lines (78 loc) · 5.54 KB

Developer Guide

The repository contains two main components located in cmd/protoc-gen-gorums:

  • dev: Contains static code and code generated by templates. In other words, this is the code that the protoc-gen-gorums compiler will output. All files that are not prefixed by zorums* and do not end in _test.go get bundled into template_static.go.
  • gengorums: Contains the code for the protoc-gen-gorums compiler, as well as templates.

Workflow and File Endings

  1. Template Changes: Changes to generated code in the dev/zorums_*_gorums.pb.go files should be done by editing the various templates in the corresponding gengorums/template_*.go file. Making changes to the zorums* files will be overwritten. Note that there is not a one-to-one correspondence for all files.

  2. Static Code File Changes: Any .go file in dev/ that is not prefixed by zorums_ and does not end in _test.go is treated as static code and bundled into template_static.go. Currently, aliases.go is the only such file, but additional files can be added to the dev/ directory and they will be included automatically.

Generated Static Surface and Reserved Identifiers

Every generated _gorums.pb.go file embeds a small block of static code taken verbatim from dev/aliases.go. That block currently consists of four type aliases:

type (
    Configuration = gorums.Configuration
    Node          = gorums.Node
    NodeContext   = gorums.NodeContext
    ConfigContext = gorums.ConfigContext
)

These aliases make the most commonly used Gorums types available without requiring an explicit gorums import in user code.

Each name declared in aliases.go (and any other non-ignored file in dev/) is also added to the reserved identifier list. The Gorums generator rejects proto files that define a message type whose name matches a reserved identifier, because such a name would collide with the generated alias and cause a compile error.

The bundler (gorums_bundle.go) discovers reserved identifiers by inspecting TypesInfo.Defs for all exported, package-scope declarations in the dev package. This means that simply declaring a type alias (or any other exported top-level name) in aliases.go is sufficient to reserve that name — no extra annotation is needed.

The TestReservedIdentifiers test in gengorums/gorums_bundle_test.go pins the expected set. If you add or remove an alias, update that test to match.

Any changes to templates or static code requires the invocation of make in order to:

  • Bundle the static code into template_static.go.
  • Rebuild the protoc-gen-gorums compiler.
  • Update the zorums_*_gorums.pb.go files.

See the Makefile for more details. To force compile, e.g. following a protoc update, you can use:

make -B

Testing

Testing the protoc-gen-gorums compiler itself can be done by running the command below. These tests verify that the code generated by the Gorums compiler is correct and stable.

Default Mode (bufconn)

By default, tests use in-memory bufconn connections:

make test

Integration Mode (real network)

For end-to-end validation with real TCP connections:

make integrationtest

Or directly:

go test -tags=integration ./...

Benchmarking

See benchmarking.md

Makefile

Below is a description of the current Makefile targets. The Makefile itself also serves as documentation; inspect it for details.

Target Description
all Builds dev, benchmark, and compiles tests (default target).
dev Updates template_static.go and regenerates generated files from templates.
genproto Force-regenerates all protobuf and Gorums files across the repo (dev, benchmark, tests, examples).
benchmark Compiles the benchmark tool.
compiletests Compiles test protos in internal/tests.
tools Installs required tools (protoc-gen-go, protoc-gen-go-grpc, stress, etc.) via go install tool.
installgorums Reinstalls the protoc-gen-gorums plugin.
bootstrapgorums Bootstraps the plugin when it is not yet installed.
test Runs all tests (using bufconn by default).
integrationtest Runs integration tests with real TCP connections.
testrace Runs tests with the race detector enabled.
benchtest Validates that benchmarks compile and run without error (short runs).
bench Runs benchmarks with proper measurement for performance analysis.
stresstest Runs stress tests (build tag: stress) for thorough testing.
modernize Applies Go modernization fixes across the codebase.