{"id":13446775,"url":"https://github.com/gunk/gunk","last_synced_at":"2026-01-21T11:34:38.636Z","repository":{"id":28232025,"uuid":"116217180","full_name":"gunk/gunk","owner":"gunk","description":"Modern frontend and syntax for Protocol Buffers","archived":false,"fork":false,"pushed_at":"2024-07-03T00:12:55.000Z","size":1591,"stargazers_count":343,"open_issues_count":17,"forks_count":34,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-03-21T16:57:37.757Z","etag":null,"topics":["go","golang","gunk","protobuf","protocol-buffers"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gunk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-04T05:07:13.000Z","updated_at":"2024-11-28T16:33:42.000Z","dependencies_parsed_at":"2024-01-18T15:57:52.317Z","dependency_job_id":"dc5af286-cc68-48f1-8216-f339987477c8","html_url":"https://github.com/gunk/gunk","commit_stats":null,"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"purl":"pkg:github/gunk/gunk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gunk%2Fgunk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gunk%2Fgunk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gunk%2Fgunk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gunk%2Fgunk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gunk","download_url":"https://codeload.github.com/gunk/gunk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gunk%2Fgunk/sbom","scorecard":{"id":449450,"data":{"date":"2025-08-11","repo":{"name":"github.com/gunk/gunk","commit":"beccc87fc84a005f13a7e578c6428ff0b1bedbc5"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":2.7,"checks":[{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/test.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Code-Review","score":2,"reason":"Found 6/22 approved changesets -- score normalized to 2","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/gunk/gunk/test.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/gunk/gunk/test.yml/master?enable=pin","Info:   0 out of   2 GitHub-owned GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 17 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":0,"reason":"12 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GO-2024-2611 / GHSA-8r3f-844c-mc37","Warn: Project is vulnerable to: GO-2023-1495 / GHSA-fxg5-wq6x-vr4w","Warn: Project is vulnerable to: GO-2022-1144 / GHSA-xrjj-mj9h-534m","Warn: Project is vulnerable to: GO-2023-1571 / GHSA-vvpx-j8f3-3w6h","Warn: Project is vulnerable to: GO-2023-1988 / GHSA-2wrh-6pvc-2jm9","Warn: Project is vulnerable to: GO-2023-2102 / GHSA-4374-p667-p6c8","Warn: Project is vulnerable to: GO-2023-2153 / GHSA-m425-mq94-257g / GHSA-qppj-fm5r-hxr3","Warn: Project is vulnerable to: GO-2024-2687 / GHSA-4v7x-pqxf-cx7m","Warn: Project is vulnerable to: GO-2024-3333","Warn: Project is vulnerable to: GO-2025-3503 / GHSA-qxp5-gwg8-xv66","Warn: Project is vulnerable to: GO-2025-3595 / GHSA-vvgc-356p-c3xw","Warn: Project is vulnerable to: GO-2022-1059 / GHSA-69ch-w2m2-3vjp"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-19T07:47:30.975Z","repository_id":28232025,"created_at":"2025-08-19T07:47:30.975Z","updated_at":"2025-08-19T07:47:30.975Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28632772,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T04:47:28.174Z","status":"ssl_error","status_checked_at":"2026-01-21T04:47:22.943Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","golang","gunk","protobuf","protocol-buffers"],"created_at":"2024-07-31T05:00:59.580Z","updated_at":"2026-01-21T11:34:38.611Z","avatar_url":"https://github.com/gunk.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Gunk [![GoDoc][godoc]][godoc-link]\n\n[godoc]: https://godoc.org/github.com/gunk/gunk?status.svg \"GoDoc\"\n[godoc-link]: https://godoc.org/github.com/gunk/gunk\n\nGunk is a modern frontend and syntax for [Protocol Buffers][protobuf].\n\n[Quickstart][] | [Installing][] | [Syntax][] | [Configuring][] | [About][] | [Releases][]\n\n[quickstart]: #quickstart \"Quickstart\"\n[installing]: #installing \"Installing\"\n[syntax]: #protocol-types-and-messages \"Protocol Types and Messages Syntax\"\n[configuring]: #project-configuration-files \"Project Configuration Files\"\n[about]: #about \"About\"\n[releases]: https://github.com/gunk/gunk/releases \"Releases\"\n\n## Overview\n\nGunk provides a modern project-based workflow along with a [Go-derived][go-project]\nsyntax for defining types and services for use with [Protocol Buffers][protobuf].\nGunk is designed to integrate cleanly with existing [`protoc`][protobuf] based\nbuild pipelines, while standardizing workflows in a way that is\nfamiliar/accessible to Go developers.\n\n## Quickstart\n\nCreate a working directory for a project:\n\n```sh\n$ mkdir -p ~/src/example \u0026\u0026 cd ~/src/example\n```\n\n[Install `gunk`][installing] and place the following [Gunk definitions][syntax]\nin `example/util.gunk`:\n\n[gunk definition]: #syntax \"Gunk Protocol Syntax\"\n\n```go\npackage util\n\n// Util is a utility service.\ntype Util interface {\n\t// Echo returns the passed message.\n\tEcho(Message) Message\n}\n\n// Message contains an echo message.\ntype Message struct {\n\t// Msg is a message from a client.\n\tMsg string `pb:\"1\"`\n}\n```\n\nCreate the corresponding [project configuration][] in `example/.gunkconfig`:\n\n[project configuration]: #gunk-project-config \"Gunk Project Configuration File\"\n\n```ini\n[generate go]\n\n[generate js]\nimport_style=commonjs\nbinary\n```\n\nThen, generate [protocol buffer][protobuf] definitions/code:\n\n```sh\n$ ls -A\n.gunkconfig  util.gunk\n\n$ gunk generate\n\n$ ls -A\nall.pb.go  all_pb.js  .gunkconfig  util.gunk\n```\n\nAs seen above, `gunk` generated the corresponding Go and JavaScript [protobuf\ncode][protobuf] using the options defined in the `.gunkconfig`.\n\n#### End-to-end Example\n\nA end-to-end example gRPC server implementation, using Gunk definitions [is\navailable for review][gunk-example-server].\n\n#### Debugging `protoc` commands\n\nUnderlying commands executed by `gunk` can be viewed with the following:\n\n```sh\n$ gunk generate -x\nprotoc-gen-go\nprotoc --js_out=import_style=commonjs,binary:/home/user/example --descriptor_set_in=/dev/stdin all.proto\n```\n\n## Installing\n\nThe `gunk` command-line tool can be installed [via Release][], [via Homebrew][], [via Scoop][] or [via Go][]:\n\n[via release]: #installing-via-release\n[via homebrew]: #installing-via-homebrew-macos\n[via scoop]: #installing-via-scoop-windows\n[via go]: #installing-via-go\n\n### Installing via Release\n\n1. [Download a release for your platform][releases]\n2. Extract the `gunk` or `gunk.exe` file from the `.tar.bz2` or `.zip` file\n3. Move the extracted executable to somewhere on your `$PATH` (Linux/macOS) or\n   `%PATH%` (Windows)\n\n### Installing via Homebrew (macOS)\n\n`gunk` is available in the [`gunk/gunk` tap][gunk-tap], and can be installed in\nthe usual way with the [`brew` command][homebrew]:\n\n```sh\n# add tap\n$ brew tap gunk/gunk\n\n# install gunk\n$ brew install gunk\n```\n\n### Installing via Scoop (Windows)\n\n`gunk` can be installed using [Scoop](https://scoop.sh):\n\n```powershell\n# install scoop if not already installed\niex (new-object net.webclient).downloadstring('https://get.scoop.sh')\n\nscoop install gunk\n```\n\n### Installing via Go\n\n`gunk` can be installed in the usual Go fashion:\n\n```sh\n# install gunk\n$ go get -u github.com/gunk/gunk\n```\n\n## Protobuf Dependency and Caching\n\nThe `gunk` command-line tool uses the `protoc` command-line tool. `gunk` can be configured\nto use `protoc` at a specified path. If it isn't available, `gunk` will\n[download the latest protobuf release][protobuf-releases] to the user's cache,\nfor use. It's also possible to pin a specific version, see the section on [protoc configuration][].\n\n[protoc configuration]: #section-protoc\n\n## Protocol Types and Messages\n\nGunk provides an alternate, Go-derived syntax for defining [protocol\nbuffers][protobuf]. As such, Gunk definitions are a subset of the Go\nprogramming language. Additionally, a special `+gunk` annotation is recognized\nby `gunk`, to allow the declaration of [protocol buffer options][protobuf-options]:\n\n```go\npackage message\n\nimport \"github.com/gunk/opt/http\"\n\n// Message is a Echo message.\ntype Message struct {\n\t// Msg holds a message.\n\tMsg  string `pb:\"1\" json:\"msg\"`\n\tCode int    `pb:\"2\" json:\"code\"`\n}\n\n// Util is a utility service.\ntype Util interface {\n\t// Echo echoes a message.\n\t//\n\t// +gunk http.Match{\n\t// \tMethod:\t\"POST\",\n\t// \tPath:\t\"/v1/echo\",\n\t// \tBody:\t\"*\",\n\t// }\n\tEcho(Message) Message\n}\n```\n\nTechnically speaking, gunk is not actually strict subset of go, as gunk allows\nunused imports; it actually requires them for some features.\n\nSee the example above;\nin pure go, this would not be a valid go code, as `http` is not used outside of the comment.\n\n### Scalars\n\nGunk's Go-derived syntax uses the canonical [Go scalar types][protobuf-types]\nof the `proto3` syntax, defined by the [protocol buffer project][protobuf]:\n\n| Proto3 Type | Gunk Type |\n| ----------- | --------- |\n| `double`    | `float64` |\n| `float`     | `float32` |\n| `int32`     | `int`     |\n| `int32`     | `int32`   |\n| `int64`     | `int64`   |\n| `uint32`    | `uint`    |\n| `uint32`    | `uint32`  |\n| `uint64`    | `uint64`  |\n| `bool`      | `bool`    |\n| `string`    | `string`  |\n| `bytes`     | `[]byte`  |\n\n**Note:** Variable-length scalars will be enabled in the future using a tag\nparameter.\n\n[gunk ons]: #gunk-annotations \"Gunk Annotation Syntax\"\n\n### Messages\n\nGunk's Go-derived syntax uses Go's `struct` type declarations for declaring\nmessages, and require a `pb:\"\u003cfield_number\u003e\"` tag to indicate the field number:\n\n```go\ntype Message struct {\n\tFieldA string `pb:\"1\"`\n}\n\ntype Envelope struct {\n\tMessage Message  `pb:\"1\" json:\"msg\"`\n}\n```\n\nThere are additional tags (for example, the `json:` tag above), that will be\nrecognized by `gunk format`, and passed on to generators, where possible.\n\n**Note:** When using [`gunk format`][], a valid `pb:\"\u003cfield_number\u003e\"` tag will be automatically\ninserted if not declared.\n\n[`gunk format`]: #formatting-gunk-files\n\n### Services\n\nGunk's Go-derived syntax uses Go's `interface` syntax for declaring services:\n\n```go\ntype SearchService interface {\n\tSearch(SearchRequest) SearchResponse\n}\n```\n\nThe above is equivalent to the following protobuf syntax:\n\n```proto3\nservice SearchService {\n  rpc Search (SearchRequest) returns (SearchResponse);\n}\n```\n\n### Enums\n\nGunk's Go-derived syntax uses Go `const`'s for declaring enums:\n\n```go\ntype MyEnum int\n\nconst (\n\tMYENUM MyEnum = iota\n\tMYENUM2\n)\n```\n\n**Note:** values can also be fixed numeric values or a calculated value (using\n`iota`).\n\n### Maps\n\nGunk's Go-derived syntax uses Go `map`'s for declaring `map` fields:\n\n```go\ntype Project struct {\n\tProjectID string `pb:\"1\" json:\"project_id\"`\n}\n\ntype GetProjectResponse struct {\n\tProjects map[string]Project `pb:\"1\"`\n}\n```\n\n### Repeated Values\n\nGunk's Go-derived syntax uses Go's slice syntax (`[]`) for declaring a\nrepeated field:\n\n```go\ntype MyMessage struct {\n\tFieldA []string `pb:\"1\"`\n}\n```\n\n### Message Streams\n\nGunk's Go-derived syntax uses Go `chan` syntax for declaring streams:\n\n```go\ntype MessageService interface {\n\tList(chan Message) chan Message\n}\n```\n\nThe above is equivalent to the following protobuf syntax:\n\n```proto3\nservice MessageService {\n  rpc List(stream Message) returns (stream Message);\n}\n```\n\n### Protocol Options\n\n[Protocol buffer options][protobuf-options] are standard messages (ie, a\n`struct`), and can be attached to any service, message, enum, or other other\ntype declaration in a Gunk file via the doccomment preceding the type, field,\nor service:\n\n```go\n// MyOption is an option.\ntype MyOption struct {\n\tName string `pb:\"1\"`\n}\n\n// +gunk MyOption {\n// \tName: \"test\",\n// }\ntype MyMessage struct {\n\t/* ... */\n}\n```\n\n## Project Configuration Files\n\nGunk uses a top-level `.gunkconfig` configuration file for managing the Gunk\nprotocol definitons for a project:\n\n```ini\n# Example .gunkconfig for Go, grpc-gateway, Python and JS, TypeScript (CommonJS), TypeScript\n\n[generate go]\nout=v1/go\nplugins=grpc\n\n[generate]\nout=v1/go\ncommand=protoc-gen-grpc-gateway\nlogtostderr=true\n\n[generate python]\nout=v1/python\n\n[generate js]\nout=v1/js\nimport_style=commonjs\nbinary\n\n[generate ts]\nservice=true\nplugin_version=v0.12.0\nfix_paths_post_proc=true\n\n[generate ts_proto]\nservice=true\nplugin_version=v1.110.4\n\n[generate protobuf-ts]\nts_nocheck\neslint_disable\noptimize_code_size\nplugin_version= v2.9.4\n\n```\n\n- `[generate ts]` uses [ts-protoc-gen](https://www.npmjs.com/package/ts-protoc-gen)\n- `[generate ts_proto]` uses [ts-proto](https://www.npmjs.com/package/ts-proto)\n- `[generate protobuf-ts]` uses [@protobuf-ts/plugin](https://www.npmjs.com/package/@protobuf-ts/plugin)\n\n### Project Search Path\n\nWhen `gunk` is invoked from the command-line, it searches the passed package\nspec (or current working directory) for a `.gunkconfig` file, and walks up the\ndirectory hierarchy until a `.gunkconfig` is found, or the project's root is\nencountered. The project root is defined as the top-most directory containing a\n`.git` subdirectory, or where a `go.mod` file is located.\n\n### Format\n\nThe `.gunkconfig` file format is compatible with [Git config syntax][git-config],\nand in turn is compatible with the INI file format:\n\n```ini\n[generate]\ncommand=protoc-gen-go\n\n[generate]\nout=v1/js\nprotoc=js\n```\n\n### Global section\n\n- `import_path` - see \"Converting Existing Protobuf Files\"\n\n- `strip_enum_type_names` - with this option on, enums with their type prefixed\n  will be renamed to the version without prefix.\n\n  Note that this might produce invalid protobuf that stops compiling in 1.4.\\*\n  protoc-gen-go, if the enum names clash.\n\n### Section `[format]`\n\nThe configuration options for formatting Gunk files where formatting options\nthat may break program behavior can be enabled.\n\n#### Parameters\n\n- `snake_case_json` - automatically sets all field tags of JSON to their snake\n  cased name if enabled\n\n- `initialisms` - comma-separated list of initialisms to be used when\n  formatting JSON names\n\n- `reorder_pb` - automatically sets pb according to the field's order,\n  overwriting previous pb fields\n\n### Section `[protoc]`\n\nThe path where to check for (or where to download) the `protoc` binary can be configured.\nThe version can also be pinned.\n\n#### Parameters\n\n- `version` - the version of protoc to use. If unspecified, defaults\n  to the latest release available. Otherwise, gunk will either download the specified\n  version, or check that the version of `protoc` at the specified path matches what was\n  configured.\n\n- `path` - the path to check for the `protoc` binary. If unspecified, defaults appropriate user\n  cache directory for the user's OS. If no file exists at the path, `gunk` will attempt to download\n  protoc.\n\n### Section `[generate[ \u003ctype\u003e]]`\n\nEach `[generate]` or `[generate \u003ctype\u003e]` section in a `.gunkconfig` corresponds\nto a invocation of the `protoc-gen-\u003ctype\u003e` tool.\n\n#### Parameters\n\nEach `name[=value]` parameter defined within a `[generate]` section will be\npassed as a parameter to the `protoc-gen-\u003ctype\u003e` tool, with the exception of\nthe following special parameters that override the behavior of the `gunk generate` tool:\n\n- `command` - overrides the `protoc-gen-*` command executable used by\n  `gunk generate`. The executable must be findable on `$PATH` (Linux/macOS) or\n  `%PATH%` (Windows), or may be the full path to the executable. If not\n  defined, then `command` will be `protoc-gen-\u003ctype\u003e`, when `\u003ctype\u003e` is the\n  value in `[generate \u003ctype\u003e]`.\n\n- `protoc` - overrides the `\u003ctype\u003e` value, causing `gunk generate` to use the\n  `protoc` value in place of `\u003ctype\u003e`.\n\n- `out` - overrides the output path of `protoc`. If not defined, output will be\n  the same directory as the location of the `.gunk` files.\n\n- `plugin_version` - specify version of plugin. The plugin is downloaded\n  from github/maven, built in cache and used. It is _not_ installed in $PATH.\n  This currently works with the following plugins:\n\n  - `protoc-gen-go`\n  - `protoc-gen-grpc-java`\n  - `protoc-gen-grpc-gateway`\n  - `protoc-gen-openapiv2` (`protoc-gen-swagger` support is deprecated)\n  - `protoc-gen-swift` (installing swift itself first is necessary)\n  - `protoc-gen-grpc-swift` (installing swift itself first is necessary)\n  - `protoc-gen-ts` (installing node and npm first is necessary)\n  - `protoc-gen-grpc-python` (cmake, gcc is necessary; takes ~10 minutes to clone build)\n\n  It is recommended to use this function everywhere, for reproducible builds,\n  together with `version` for protoc.\n\n- `json_tag_postproc` - uses `json` tags defined in gunk file also for go-generated\n  file\n\n- `fix_paths_postproc` - for `js` and `ts` - by default, gunk generates wrong\n  paths for other imported gunk packages, because of the way gunk moves files\n  around.\n  Works only if `js` also has `import_style=commonjs` option.\n\n- `generate_single`- runs the generator with all files at once instead of per\n  package.\n  The `out` parameter must be set when enabled.\n\nAll other `name[=value]` pairs specified within the `generate` section will be\npassed as plugin parameters to `protoc` and the `protoc-gen-\u003ctype\u003e` generators.\n\n#### Short Form\n\nThe following `.gunkconfig`:\n\n```ini\n[generate go]\n\n[generate js]\nout=v1/js\n```\n\nis equivalent to:\n\n```ini\n[generate]\ncommand=protoc-gen-go\n\n[generate]\nout=v1/js\nprotoc=js\n```\n\n#### Different forms of invocation\n\nThere are three different forms of gunkconfig sections that have three\ndifferent semantics.\n\n```ini\n[generate]\ncommand=protoc-gen-go\n\n[generate]\nprotoc=go\n\n[generate go]\n```\n\nThe first one uses protoc-gen-go plugin directly, without using protoc.\nIt also attempts to move files to the same directory as the gunk file.\n\nThe second one uses protoc and does not attempt to move any files.\nProtoc attempts to load plugin from $PATH, if it is not one of the\nbuilt-in protoc plugins; this will _not_ work together with pinned version\nand other gunk features and is not recommended outside of built-in\nprotoc generators.\n\nThe third version is reccomended. It will try to detect whether language\nis one of built-in\nprotoc generators, in that case behaves like the second way, otherwise\nbehaves like the first.\n\nThe built-in protoc generators are:\n\n- cpp\n- java\n- python\n- php\n- ruby\n- csharp\n- objc\n- js\n\n## Third-Party Protobuf Options\n\nGunk provides the [`+gunk` annotation syntax][] for declaring [protobuf\noptions][protobuf-options], and specially recognizes some third-party API\nannotations, such as Google HTTP options, including all builtin/standard\n`protoc` options for code generation:\n\n[`+gunk` annotation syntax]: #protocol-options \"Gunk Annotation Syntax\"\n\n```go\n// +gunk java.Package(\"com.example.message\")\n// +gunk java.MultipleFiles(true)\npackage message\n\nimport (\n\t\"github.com/gunk/opt/http\"\n\t\"github.com/gunk/opt/file/java\"\n)\n\ntype Util interface {\n\t// +gunk http.Match{\n\t// \tMethod:\t\"POST\",\n\t// \tPath:\t\"/v1/echo\",\n\t// \tBody:\t\"*\",\n\t// }\n\tEcho()\n}\n```\n\nFurther documentation on available options can be found at the\n[Gunk options project][gunk-options].\n\n## Formatting Gunk Files\n\nGunk provides the `gunk format` command to format `.gunk` files (akin to `gofmt`):\n\n```sh\n$ gunk format /path/to/file.gunk\n$ gunk format \u003cpathspec\u003e\n```\n\n## Converting Existing Protobuf Files\n\nGunk provides the `gunk convert` command that will converting existing `.proto`\nfiles (or a directory) to the Go-derived Gunk syntax:\n\n```sh\n$ gunk convert /path/to/file.proto\n$ gunk convert /path/to/protobuf/directory\n```\n\nIf your `.proto` is referencing another `.proto` from another directory,\nyou can add `import_path` in the global section of your `.gunkconfig`.\nIf you don't provide `import_path` it will only search in the root directory.\n\n```ini\nimport_path=relative/path/to/protobuf/directory\n```\n\n\u003e The path to provide is relative from the `.gunkconfig` location.\n\nFurthermore, the referenced files must contain:\n\n```proto\noption go_package=\"path/of/go/package\";\n```\n\nThe resulting `.gunk` file will contain the import path as defined in `go_package`:\n\n```go\nimport (\n\tname \"path/of/go/package\"\n)\n```\n\n## About\n\nGunk is developed by the team at [Brankas][brankas], and was designed to\nstreamline API design and development.\n\n### History\n\nFrom the beginning of the company, the Brankas team defined API types and\nservices in `.proto` files, leveraging ad-hoc `Makefile`'s, shell scripts, and\nother non-standardized mechanisms for generating [Protocol Buffer code][protobuf].\n\nAs development exploded in 2017 (and beyond) with continued addition of backend\nmicroservices/APIs, more code repositories and projects, and team members, it\nbecame necessary to standardize tooling for the organization as well as reduce\nthe cognitive load of developers (who for the most part were working almost\nexclusively with Go) when declaring gRPC and REST services.\n\n### Naming\n\nThe Gunk name has a cheeky, backronym \"Gunk Unified N-terface Kompiler\",\nhowever the name was chosen because it was possible to secure the GitHub `gunk`\nproject name, was short, concise, and not used by other projects.\n\nAdditionally, \"gunk\" is an apt description for the \"gunk\" surrounding protocol\ndefinition, generation, compilation, and delivery.\n\n## Contributing\n\nIssues, Pull Requests, and other contributions are greatly welcomed and\nappreciated! Get started with building and running `gunk`:\n\n```sh\n# clone source repository\n$ git clone https://github.com/gunk/gunk.git \u0026\u0026 cd gunk\n\n# force GO111MODULES\n$ export GO111MODULE=on\n\n# build and run\n$ go build \u0026\u0026 ./gunk\n```\n\n### Dependency Management\n\nGunk uses [Go modules][go-modules] for dependency management, and as such\nrequires Go 1.11+. Please run `go mod tidy` before submitting any PRs:\n\n```sh\n$ export GO111MODULE=on\n$ cd gunk \u0026\u0026 go mod tidy\n```\n\n[brankas]: https://brank.as/\n[git-config]: https://git-scm.com/docs/git-config\n[go-modules]: https://github.com/golang/go/wiki/Modules\n[go-project]: https://golang.org/project\n[gunk-options]: https://github.com/gunk/opt\n[gunk-example-server]: https://github.com/gunk/gunk-example-server\n[gunk-tap]: https://github.com/gunk/homebrew-gunk\n[homebrew]: https://brew.sh/\n[protobuf]: https://developers.google.com/protocol-buffers/\n[protobuf-options]: https://developers.google.com/protocol-buffers/docs/proto#options\n[protobuf-releases]: https://github.com/protocolbuffers/protobuf/releases\n[protobuf-types]: https://developers.google.com/protocol-buffers/docs/proto3#scalar\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgunk%2Fgunk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgunk%2Fgunk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgunk%2Fgunk/lists"}