////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////

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

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.

For this reason, Grails 7 adds the following commands to any Grails install:

1. `grails-forge-cli` - the forge cli that was shipped as `grails` initially in Grails 6. This CLI has both interactive completion & bash autocompletion.
Long term, we intend to fold the legacy shell functions into it - including the ability to create custom commands & supporting a custom layout.
2. `grails-shell-cli` - the legacy shell cli that IntelliJ uses.
This CLI has only interactive completion.
Historically, this shell has not had autocompletion.
3. `grails` - a new, delegating shell application that will call either `grails-shell-cli` or `grails-forge-cli`.
By default, `./grails` uses `grails-shell-cli` for backwards compatibility.
To use `grails-forge-cli`, pass the `-t` or `--type` argument:
[source,console]
$ ./grails -t forge


=== Install with SDKMAN

To install the latest version of Grails using SDKMAN, run this on your terminal:

[source,console]
$ sdk install grails

You can also specify a version

[source,console,subs=attributes+]
$ sdk install grails {version}

You can find more information about SDKMAN usage on the https://sdkman.io/usage[SDKMAN Docs].
After installing, all three CLI commands: `grails`, `grails-shell-cli`, and `grails-forge-cli` will be available.

=== Manual installation

For manual installation follow these steps:

* https://github.com/apache/grails-core/releases[Download] a binary distribution of Grails and extract the resulting zip file to a location of your choice.
Then add the bin directory to your system path.

==== Unix/Linux

** This can be done by adding `export PATH="$PATH:/path/to/grails/bin"` to your profile

==== Windows
** Copy the path to the bin directory inside the grails folder you have downloaded, for example,

----
C:\path_to_grails\bin
----

** Go to Environment Variables, you can typically search or run the command below, the type env and then Enter

----
Start + R
----

** Edit the Path variable on User Variables / System Variables depending on your choice.
** Paste the copied path in the Path Variable.

If Grails is working correctly you should now be able to type `grails --version` in the terminal window and see output similar to this:

[source,console,subs=attributes+]
----
Grails Version: {version}
----

=== Grails Wrapper

The original CLI binaries can be quite large.
When installing via SDKMAN or via a download, we include a single shadowJar that contains both shells and the associated scripts to invoke them.
However, when a project is generated, we also include a wrapper `grailsw` that can be checked into source control.
This wrapper will download the CLI's to `~/.grails/wrapper/myGrailsVersion` and invoke them when calling `grailsw`.
It is meant to be a light weight option if SDKMAN is not available.