README suggestion of .sq files in src/main/sqldelight #1212
Conversation
As a first time user of the library I was putting my `.sq` files in `src/main/java/com...` and didn't understand why codegen wasn't working. There was a small note in the current README showing an example file path which included `src/main/sqldelight`, but it wasn't clearly called out as a requirement as a first time user, without custom gradle plugin configuration. I'm submitting this change in hopes that it will improve the first time experience of using SqlDelight and avoid my 30 minutes of trying to figure out why it wasn't generating sources: https://twitter.com/HandstandSam/status/1093513648885116928
| @@ -6,10 +6,11 @@ SQLDelight generates typesafe APIs from your SQL statements. It compile-time ver | |||
| Example | |||
| ------- | |||
|
|
|||
| To use SQLDelight, apply the [gradle plugin](https://github.com/square/sqldelight#gradle) and put your SQL statements in a `.sq` file, like | |||
| `src/main/sqldelight/com/example/HockeyPlayer.sq`. Typically the first statement creates a table. | |||
| To use SQLDelight, apply the [gradle plugin](https://github.com/square/sqldelight#gradle) and put your SQL statements in a `.sq` file in `src/main/sqldelight`. Typically the first statement in the SQL file creates a table. | |||
There was a problem hiding this comment.
Should we also explicitly mention that you should use a folder/package structure as well?
There was a problem hiding this comment.
Yeah. Including where the generated source ends up for people that aren't totally sure how that "magic" works.
I think that is a good sub-section to have, but not critical for providing your "quick start guide" where you just need:
- dependencies
- gradle plugin
- where to put
.sqfiles - how to use the generated code in Android/JVM/etc
There was a problem hiding this comment.
Reading over the docs again, and they are awesome for Kotlin Multiplatform, but I think a "quick start" for Android would suck people in, and the multi-platform would become a later benefit.
All good things to discuss, but not the intent of this PR. Just the small change. Maybe can create an issue for this follow up README work.
There was a problem hiding this comment.
yea id be very open to having more targeted getting started guides but keeping the readme more general
There was a problem hiding this comment.
When/if I have some time I might be able to blog something, but not for at least a week. Sounds like a good plan. Appreciate all the thought/time put into the library. Hopefully can get some good use out of it and can contribute back with some posts about it.
There was a problem hiding this comment.
Success story: https://twitter.com/HandstandSam/status/1093554347877765122
As a first time user of the library I was putting my
.sqfiles insrc/main/java/com...and didn't understand why codegen wasn't working. There was a small note in the current README showing an example file path which includedsrc/main/sqldelight, but it wasn't clearly called out as a requirement as a first time user, without custom gradle plugin configuration.I'm submitting this change in hopes that it will improve the first time experience of using SqlDelight and avoid my 30 minutes of trying to figure out why it wasn't generating sources: https://twitter.com/HandstandSam/status/1093513648885116928
I finally figured it out after finding @AlecStrong's blog post and seeing it as a SQL comment in his examples: https://medium.com/square-corner-blog/announcing-sqldelight-1-0-d482aa408f64