jdaugherty commented on code in PR #14906: URL: https://github.com/apache/grails-core/pull/14906#discussion_r2207516851
########## grails-doc/src/en/guide/gettingStarted/downloadingAndInstalling.adoc: ########## @@ -21,16 +21,67 @@ There are many ways to create a Grails application. The best way is to use either https://start.grails.org[start.grails.org] or use the Grails CLI via https://sdkman.io[SDKMAN]. SDKMAN greatly simplifies installing and managing multiple Grails versions. -=== Types of CLI +=== Types of command-line interface (CLI) -Historically, Grails had one CLI - `grails shell`. -In Grails 6, a new CLI was introduced `grails forge` that was meant to replace `grails shell`. -Unfortunately, IntelliJ's Grails plugin relies on the legacy shell to provide functions for the IDE. -For this reason, the decision was made to restore publishing of the `grails-shell` in later versions of Grails 6. The other problem is to customize application generation, `grails forge` would need to be forked, customized, published, and hosted somewhere. -The process of building and hosting a custom version of `grails-forge` was found to be cumbersome for some people because the previous shell allowed for customization by providing a directory that laid out a skeleton of what to create. -Worse, some critical plugins, such as the database migration plugin had custom commands that cannot be easily imported into the forge cli. +Historically, Grails had one CLI - `grails shell`, until `grails forge` was introduced in Grails 6. -For this reason, Grails 7 adds the following commands to any Grails install: +==== Grails Shell CLI +The historical `grails shell` CLI has been a core part of the Grails Framework since its inception, providing command-line tools for project creation, code generation, and application management. +Nearly all historical references to the `grails` or `grailsw` commands pertain to `grails shell` functionality. +The `grails shell` CLI relies on Profiles, consisting of skeleton directories and YAML-based configurations for application generation. +However, this approach is less flexible than the feature-rich application generation capabilities of `grails forge`. +The Grails Wrapper is a lightweight script (`grailsw`) and the accompanying JAR file is designed to bootstrap and load the CLI within a Grails Application. +The `grails shell` CLI provides most of the same application generation functionality provided by `grails forge`. +Importantly, it can also run scripts, such as `run-app` that call Gradle and/or your Grails Application. +Most Grails plugins still include Grails Scripts that execute within `grails shell` CLI and have not yet been migrated to Gradle tasks. +IntelliJ IDEA's Grails plugin depends on `grails shell` for code generation and Grails command execution. +Extending application generation in the grails shell CLI is straightforward: developers can create a Custom Profile and reference it as a Maven dependency, which is generally simpler than customizing `grails forge`. + +==== Restoration of Grails Shell CLI +In Grails 6.0.0, `grails shell` CLI was removed and replaced with `grails forge` CLI. +However, in Grails 6.2.1, the grails shell CLI, along with Grails Profiles and the Wrapper were restored, empowering users to choose their preferred CLI and reclaiming functionalities that had not yet been fully transitioned to the `grails forge` CLI combined with Gradle tasks. + +==== Grails Shell CLI and Gradle +Certain `grails shell` CLI commands overlap with Gradle tasks. + +For Gradle these use a variety of Gradle tasks provided by Gradle, Spring Boot, Grails or a Grails Plugin. + +Partial list, for illustration purposes: + +[options="header,autowidth"] +|=== +| grails shell CLI | Gradle + +| `./grails run-app` | `./gradlew bootRun` +| `./grails test run-app` | `./gradlew bootRun -Dgrails.env=test` +| `./grails package` | `./gradlew assemble -Dgrails.env=prod` +| `./grails generate-all org.bookstore.Author` | `./gradlew runCommand -Pargs="generate-all org.bookstore.Author"` +| `./grails dbm-update` | `./gradlew dbmUpdate` +| `./grails dbm-generate-changelog person-domain.groovy` | `./gradlew dbmGenerateChangelog -Pargs=" person-domain.groovy"` +| `./grails s2-quickstart com.yourapp User Role` | `./gradlew runCommand -Pargs="s2-quickstart com.yourapp User Role"` Review Comment: Should we tell people how these map to gradle? i.e. dbm-update maps to a command, while s2-quickstart maps to a script. I am also ok leaving this. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: notifications-unsubscr...@grails.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
