search

grpc / grpc-kotlin

Kotlin gRPC implementation. HTTP/2 based RPC
https://grpc.io/docs/languages/kotlin
Apache License 2.0
1.2k stars 165 forks source link

Clarify versionCatalog usage in examples #583

Closed dieter-aerit closed 8 months ago

dieter-aerit commented 8 months ago

Hi,

Somebody will probably point out that I am a dumbass, but after spending quite some time trying to mimic the example functionality in my own code, I can't get it working. I think the primary task of the examples should be to clearly demonstrate how to use the functionality in your own code? For the moment I feel like the examples don't do this very well.

My main problem is the usage of (what I think is) the Gradle versionCatalog functionality. All dependencies are declared using something along the lines of: alias(libs.something.bla) . However, after digging for a while now I can't figure out where this versionCatalog is defined. So my attempts at trying to figure out what dependencies and versions are used and how I can mimic this in my code have been fruitless. The examples build just fine with Gradle, but I can't for the life of me figure out where it's getting the dependency versions. Neither can IntelliJ, I guess that Gradle feature is not supported.

I'm sure this is all very smart and all, but wouldn't it be better if the examples were simple and idiomatic gradle so even morons like me can figure out how it works and how to use it? Isn't that precisely what the examples are there for?

(Sorry for the slight frustrated tone. I'm sure somebody will now point out the obvious and we can all agree I suck and ignore this further.)

Edit: I found PR #582 which seems to point to this gradle/libs.versions.toml file which seems to contains versions. I feel like my point still holds though, this doesn't feel like a very well known gradle feature, there's some magic involved and the relevant file is hidden in the gradle directory where there's usually nothing interesting to be found. I'll create a small PR to maybe add a line to the documentation to help fellow ignorati like me in the future.

jamesward commented 8 months ago

Yeah, the version catalog stuff adds some complexity that has a downside. We do have some other samples that are much more basic: https://github.com/GoogleCloudPlatform/kotlin-samples/tree/main/run

It'd probably be worth documenting the existence of those somewhere in this repo. Do those samples help you get things working?

dieter-aerit commented 8 months ago

I got something working now, but all the Gradle magic isn't helping (or Gradle in general, but that's another issue).

Thanks for those samples, will take a look!

It would be incredibly helpful though to maybe add comments to the Gradle build files to explain what each line does. It obviously works, but deciphering the mechanics of HOW it works and how I can modify it for my own purposes is quite the challenge. (Adding onto the usual gradle confusion.)

Edit: reading the docs about Gradle versionCatalogs and how the mapping between toml files and accessors works, it really is ... something ... 😬