Better dev environment (open-telemetry#598)

* local dev protobuf gen script

* remove gen_proto_java

* fix cargo build

* add docs

* add development docs

* add development docs

* fix linter

* Update docs/development.md

Co-authored-by: Reiley Yang <reyang@microsoft.com>

* Update docs/development.md

Co-authored-by: Reiley Yang <reyang@microsoft.com>

* Update docs/development.md

Co-authored-by: Reiley Yang <reyang@microsoft.com>

* Update docs/development.md

Co-authored-by: Reiley Yang <reyang@microsoft.com>

* Update docs/development.md

Co-authored-by: Reiley Yang <reyang@microsoft.com>

* alpha order c++ pre-requisites

* use python3

* add protoc-gen-go / grpc

Co-authored-by: Reiley Yang <reyang@microsoft.com>

.gitignore

@@ -22,16 +22,25 @@ obj/
 .idea/
 build/
 node_modules/
-src/shippingservice/target/
-
 coverage
 .next/
 out/
 build
-src/frontend/protos
 next-env.d.ts
-src/frontend/cypress/videos
-src/frontend/cypress/screenshots
 vendor/
 composer.lock
 .venv
+
+src/frontend/cypress/videos
+src/frontend/cypress/screenshots
+src/shippingservice/target/
+
+# Ignore copied/generated protobuf files
+/src/cartservice/src/protos/
+/src/checkoutservice/genproto/
+/src/frontend/pb/
+/src/frontend/protos/
+/src/paymentservice/demo.proto
+/src/productcatalogservice/genproto/
+/src/recommendationservice/demo_pb2*.py
+/src/shippingservice/proto/

Makefile

@@ -80,3 +80,7 @@ build-env-file:
 run-tests:
 	docker compose run frontendTests
 	docker compose run integrationTests
+
+.PHONY: generate-protobuf
+generate-protobuf:
+	./ide-gen-proto.sh

docs/README.md

@@ -72,6 +72,7 @@ We'll be adding more scenarios over time.
 Project reference documentation, like requirements and feature matrices.
 
 - [Architecture](./current_architecture.md)
+- [Development](./development.md)
 - [Feature Flags Reference](./feature_flags.md)
 - [Metric Feature Matrix](./metric_service_features.md)
 - [Requirements](./requirements/)

docs/development.md

@@ -0,0 +1,70 @@
+# Development
+
+Development for this demo requires tooling in several programming languages.
+Minimum required versions will be noted where possible, but it is recommended
+to update to the latest version for all tooling. The OpenTelemetry demo team
+will attempt the services in this repository up to date with the latest version
+for dependencies and tooling when possible.
+
+## Generate Protobuf files
+
+The `make generate-protobuf` command is provided to generate protobuf files for
+all services. This can be used to compile code locally (without Docker) and
+receive hints from IDEs such as IntelliJ or VS Code.
+
+## Development tooling requirements
+
+### .NET
+
+- .NET 6.0+
+
+### C++
+
+- build-essential
+- cmake
+- libcurl4-openssl-dev
+- libprotobuf-dev
+- nlohmann-json3-dev
+- pkg-config
+- protobuf-compiler
+
+### Elixir
+
+- Erlang/OTP 23+
+- Elixir 1.13+
+- Rebar3 3.20+
+
+### Go
+
+- Go 1.19+
+- protoc-gen-go
+- protoc-gen-go-grpc
+
+### Java
+
+- JDK 17+
+- Gradle 7+
+
+### JavaScript
+
+- Node.js 16+
+
+### PHP
+
+- PHP 8.1+
+- Composer 2.4+
+
+### Python
+
+- Python 3.10
+- grpcio-tools 1.48+
+
+### Ruby
+
+- Ruby 3.1+
+
+### Rust
+
+- Rust 1.61+
+- protoc 3.21+
+- protobuf-dev

ide-gen-proto.sh

@@ -0,0 +1,73 @@
+#!/bin/sh
+
+# This script is used to generate protobuf files for all services.
+# Useful to ensure code can compile without Docker, and provide hints for IDEs.
+# Several dev tools including: cargo, protoc, python grpc_tools.protoc, and rebar3 may be required to run this script.
+
+base_dir=$(pwd)
+
+gen_proto_dotnet() {
+  echo "Generating .NET protobuf files for $1"
+  cd "$base_dir"/src/"$1" || return
+  mkdir -p ./src/protos/
+  cp -r "$base_dir"/pb/ ./src/protos/
+  cd "$base_dir" || return
+}
+
+gen_proto_elixir() {
+  echo "Generating Elixir protobuf files for $1"
+  cd "$base_dir"/src/"$1" || return
+  cp "$base_dir"/pb/demo.proto ./proto/demo.proto
+  rebar3 grpc gen
+  cd "$base_dir" || return
+}
+
+gen_proto_go() {
+  echo "Generating Go protobuf files for $1"
+  cd "$base_dir"/src/"$1" || return
+  protoc -I ../../pb ./../../pb/demo.proto --go_out=./ --go-grpc_out=./
+  cd "$base_dir" || return
+}
+
+gen_proto_js() {
+  echo "Generating Javascript protobuf files for $1"
+  cd "$base_dir"/src/"$1" || return
+  cp "$base_dir"/pb/demo.proto .
+  cd "$base_dir" || return
+}
+
+gen_proto_python() {
+  echo "Generating Python protobuf files for $1"
+  cd "$base_dir"/src/"$1" || return
+  python3 -m grpc_tools.protoc -I=../../pb --python_out=./ --grpc_python_out=./ ./../../pb/demo.proto
+  cd "$base_dir" || return
+}
+
+gen_proto_rust() {
+  echo "Generating Rust protobuf files for $1"
+  cd "$base_dir"/src/"$1" || return
+  mkdir -p proto
+  cp "$base_dir"/pb/demo.proto proto/demo.proto
+  cargo build
+  cd "$base_dir" || return
+}
+
+gen_proto_ts() {
+  echo "Generating Typescript protobuf files for $1"
+  cd "$base_dir"/src/"$1" || return
+  cp -r "$base_dir"/pb .
+  cd "$base_dir" || return
+}
+
+# gen_proto_java adservice
+gen_proto_dotnet cartservice
+gen_proto_go checkoutservice
+# gen_proto_cpp currencyservice
+# gen_proto_ruby emailservice
+# gen_proto_elixir featureflagservice
+gen_proto_ts frontend
+gen_proto_js paymentservice
+gen_proto_go productcatalogservice
+# gen_proto_php quoteservice
+gen_proto_python recommendationservice
+gen_proto_rust shippingservice