diff --git a/.gitignore b/.gitignore index b5dbfd7..9e92aff 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,4 @@ -/gen/ +/grpc/gen/ # Created by https://www.gitignore.io/api/windows,osx,linux,jetbrains,visualstudiocode # Edit at https://www.gitignore.io/?templates=windows,osx,linux,jetbrains,visualstudiocode diff --git a/README.md b/README.md index d3da2d3..b2fced8 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,5 @@ -## BDLedger gRPC API +## BDLedger APIs -### Generating gRPC code in languages +This repository contains the original interface definitions of BDLedger APIs that currently support gRPC protocols. Reading the original interface definitions can provide a better understanding of BDLedger APIs and help you to utilize them more efficiently. You can also use these definitions with open source tools to generate client libraries, documentation, and other artifacts. -#### Installling tools - -Download the [Protocol Buffers compiler](https://github.com/protocolbuffers/protobuf/releases) (protoc-3.11.4-*) for your platform and add `protoc` to `PATH` environment variable - -For generating Go code: -```bash -GIT_TAG="v1.4.0-rc.4" -go get -d -u github.com/golang/protobuf/protoc-gen-go -git -C "$(go env GOPATH)"/src/github.com/golang/protobuf checkout $GIT_TAG -go install github.com/golang/protobuf/protoc-gen-go -``` -(Update to google.golang.org/protobuf when https://github.com/grpc/grpc-go/pull/3435 resolves) - -For generating Java code: From `bdledger-sdk-java` run `gradle generateProto` - -For generating Node.js code: -```bash -npm install -g grpc-tools -``` -For generating TypeScript definitions, also run: -```bash -npm install -g protoc-gen-ts -``` - -For frontend JavaScript: -```bash -git clone https://github.com/grpc/grpc-web -cd grpc-web -sudo make install-plugin -``` - -References: -- [Go Quick Start](https://grpc.io/docs/quickstart/go.html#prerequisites) -- [gRPC Go FAQ](https://github.com/grpc/grpc-go#faq) - -**TODO: Look into [protobuf.js](https://github.com/protobufjs/protobuf.js) for Nodes.js and frontend** -**TODO: Look into [Kroto+](https://github.com/marcoferrer/kroto-plus) for Kotlin** - -#### Generating code - -Run -```bash -./scripts/gen [go] [nodejs] [ts] -``` +- [gRPC APIs](grpc/README.md) diff --git a/grpc/README.md b/grpc/README.md new file mode 100644 index 0000000..3dfda46 --- /dev/null +++ b/grpc/README.md @@ -0,0 +1,63 @@ +## BDLedger API + +### Documentation + +See [API documentation](..\docs\apis.md) + +### Development + +#### Generating gRPC code in languages + +##### Installling tools + +Download the [Protocol Buffers compiler](https://github.com/protocolbuffers/protobuf/releases) (protoc-3.11.4-*) for your platform and add `protoc` to `PATH` environment variable + +For generating Go code: +```bash +GIT_TAG="v1.4.0-rc.4" +go get -d -u github.com/golang/protobuf/protoc-gen-go +git -C "$(go env GOPATH)"/src/github.com/golang/protobuf checkout $GIT_TAG +go install github.com/golang/protobuf/protoc-gen-go +``` +(Update to google.golang.org/protobuf when https://github.com/grpc/grpc-go/pull/3435 resolves) + +For generating Java code: From `bdledger-sdk-java` run `gradle generateProto` + +For generating Node.js code, install Node.js then run: +```bash +npm install -g grpc-tools +``` +For generating TypeScript definitions, also run: +```bash +npm install -g protoc-gen-ts +``` + +For frontend JavaScript: +```bash +git clone https://github.com/grpc/grpc-web +cd grpc-web +sudo make install-plugin +``` + +References: +- [Go Quick Start](https://grpc.io/docs/quickstart/go.html#prerequisites) +- [gRPC Go FAQ](https://github.com/grpc/grpc-go#faq) + +**TODO: Look into [protobuf.js](https://github.com/protobufjs/protobuf.js) for Nodes.js and frontend** +**TODO: Look into [Kroto+](https://github.com/marcoferrer/kroto-plus) for Kotlin** + +##### Generating code + +Run: +```bash +./scripts/gen [go] [nodejs] [ts] +``` + +#### Generateing documentation + +Install Go then run: + +```bash +go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc +./scripts/gen docs +``` diff --git a/bdware/bdledger/api/common.proto b/grpc/pb/bdware/bdledger/api/common.proto similarity index 100% rename from bdware/bdledger/api/common.proto rename to grpc/pb/bdware/bdledger/api/common.proto diff --git a/bdware/bdledger/api/error_details.proto b/grpc/pb/bdware/bdledger/api/error_details.proto similarity index 100% rename from bdware/bdledger/api/error_details.proto rename to grpc/pb/bdware/bdledger/api/error_details.proto diff --git a/bdware/bdledger/api/ledger.proto b/grpc/pb/bdware/bdledger/api/ledger.proto similarity index 100% rename from bdware/bdledger/api/ledger.proto rename to grpc/pb/bdware/bdledger/api/ledger.proto diff --git a/bdware/bdledger/api/node.proto b/grpc/pb/bdware/bdledger/api/node.proto similarity index 100% rename from bdware/bdledger/api/node.proto rename to grpc/pb/bdware/bdledger/api/node.proto diff --git a/bdware/bdledger/api/query.proto b/grpc/pb/bdware/bdledger/api/query.proto similarity index 100% rename from bdware/bdledger/api/query.proto rename to grpc/pb/bdware/bdledger/api/query.proto diff --git a/google/protobuf/empty.proto b/grpc/pb/google/protobuf/empty.proto similarity index 100% rename from google/protobuf/empty.proto rename to grpc/pb/google/protobuf/empty.proto diff --git a/scripts/gen-go.sh b/grpc/scripts/gen-go.sh similarity index 100% rename from scripts/gen-go.sh rename to grpc/scripts/gen-go.sh diff --git a/scripts/gen-node.js.sh b/grpc/scripts/gen-node.js.sh similarity index 100% rename from scripts/gen-node.js.sh rename to grpc/scripts/gen-node.js.sh diff --git a/scripts/gen-web.bat b/grpc/scripts/gen-web.bat similarity index 100% rename from scripts/gen-web.bat rename to grpc/scripts/gen-web.bat diff --git a/scripts/gen-web.sh b/grpc/scripts/gen-web.sh similarity index 100% rename from scripts/gen-web.sh rename to grpc/scripts/gen-web.sh diff --git a/grpc/scripts/gen.bat b/grpc/scripts/gen.bat new file mode 100644 index 0000000..3841557 --- /dev/null +++ b/grpc/scripts/gen.bat @@ -0,0 +1,47 @@ +@echo off +setlocal EnableDelayedExpansion + +cd /d "%~dp0..\pb" +where /q protoc || echo Missing protoc && exit /b +set gen=..\gen +set pbs=bdware/bdledger/api/*.proto +REM set protos=%pkg%/common.proto %pkg%/error_details.proto %pkg%/node.proto %pkg%/ledger.proto %pkg%/query.proto %pkg%/contract.proto + +for %%A in (%*) do ( + if "%%A"=="go" ( + set plugin=protoc-gen-go + where /q !plugin! || echo Missing !plugin! && exit /b + set out=%gen%\go + if not exist !out! mkdir !out! + echo Generating Go code + start /b protoc --go_out=plugins=grpc:!out! %pbs% + ) + if "%%A"=="nodejs" ( + set plugin=grpc_tools_node_protoc_plugin + where /q !plugin! || echo missing !plugin! && exit /b + for /f %%i in ('where !plugin!') do set pluginPath=%%i + set out=%gen%\nodejs + if not exist !out! mkdir !out! + echo Generating Node.js code + start /b protoc --js_out=import_style=commonjs,binary:!out! --grpc_out=!out! --plugin=protoc-gen-grpc=!pluginPath! %pbs% google/protobuf/empty.proto + ) + if "%%A"=="ts" ( + set plugin=protoc-gen-ts + where /q !plugin! || echo missing !plugin! && exit /B + for /f %%i in ('where !plugin!') do set pluginPath=%%i + set out=%gen%\nodejs + if not exist !out! mkdir !out! + echo Generating TypeScript definitions + start /b protoc --ts_out=!out! --plugin=protoc-gen-ts=!pluginPath! %pbs% google/protobuf/empty.proto + ) + if "%%A"=="docs" ( + set plugin=protoc-gen-ts + where /q !plugin! || echo missing !plugin! && exit /B + set out=..\..\docs + if not exist !out! mkdir !out! + echo Generating documentation + start /b protoc --doc_out=!out! --doc_opt=html,apis.html %pbs% google/protobuf/empty.proto + start /b protoc --doc_out=!out! --doc_opt=markdown,apis.md %pbs% google/protobuf/empty.proto + start /b protoc --doc_out=!out! --doc_opt=json,apis.json %pbs% google/protobuf/empty.proto + ) +) diff --git a/scripts/gen.sh b/grpc/scripts/gen.sh similarity index 100% rename from scripts/gen.sh rename to grpc/scripts/gen.sh diff --git a/scripts/gen.bat b/scripts/gen.bat deleted file mode 100644 index 46092bb..0000000 --- a/scripts/gen.bat +++ /dev/null @@ -1,37 +0,0 @@ -@echo off -setlocal EnableDelayedExpansion - -cd /d "%~dp0.." -where /q protoc || echo Missing protoc && exit /b -set gen=.\gen -set pkg=bdware/bdledger/api -set protos=%pkg%/common.proto %pkg%/error_details.proto %pkg%/node.proto %pkg%/ledger.proto %pkg%/query.proto %pkg%/contract.proto - -for %%A in (%*) do ( - if "%%A"=="go" ( - set plugin=protoc-gen-go - where /q !plugin! || echo Missing !plugin! && exit /b - set out=%gen%\go - if not exist !out! mkdir !out! - echo Generating Go code - start /b protoc --go_out=plugins=grpc:!out! %protos% - ) - if "%%A"=="nodejs" ( - set plugin=grpc_tools_node_protoc_plugin - where /q !plugin! || echo missing !plugin! && exit /b - for /f %%i in ('where !plugin!') do set pluginPath=%%i - set out=%gen%\nodejs - if not exist !out! mkdir !out! - echo Generating Node.js code - start /b protoc --js_out=import_style=commonjs,binary:!nout! --grpc_out=!nout! --plugin=protoc-gen-grpc=!pluginPath! %protos% - ) - if "%%A"=="ts" ( - set plugin=protoc-gen-ts - where /q !plugin! || echo missing !plugin! && exit /B - for /f %%i in ('where !plugin!') do set pluginPath=%%i - set out=%gen%\nodejs - if not exist !out! mkdir !out! - echo Generating TypeScript definitions - start /b protoc --ts_out=!out! --plugin=protoc-gen-ts=!pluginPath! %protos% - ) -)