////
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.
////

If you're interested in contributing fixes and features to any part of grails, you will have to learn how to get hold of the project's source, build it and test it with your own applications. Before you start, make sure you have:

* A JDK (17 or above)
* A git client

Once you have all the pre-requisite packages installed, the next step is to download the Grails source code, which is hosted at https://github.com/apache/grails-core[GitHub].
This is a simple case of cloning the repository you're interested in.
For example, to get the core framework run:

[source,groovy]
----
git clone https://github.com/apache/grails-core.git
----

This will create a "grails-core" directory in your current working directory containing all the project source files. The next step is to get a Grails installation from the source.

=== Using Grails Shell

If you want to use a custom version of the grails shell to generate an application, you can do so by generating the shell distribution.

[source,groovy]
----
./gradlew grails-shell-cli:installDist
----

This will fetch all the standard dependencies required by Grails, build it, and then generate a zip file containing the necessary shell script to invoke the grails-shell-cli.

Once the above command has finished, extract one of files located under `grails-shell-cli/build/distributions` to a desired location.
Under the extracted location is a `bin` directory.
Add it to your path.
When you next type `grails-shell-cli` command to run, you'll be using the version you just built.

If you are using https://sdkman.io/[SDKMAN] then that can also be used to work with this local installation via the following:

[source,groovy]
----
sdk install grails dev /path/to/extracted/files
----

You will also need to publish your local installation to your local maven.
----
./gradlew publishToMavenLocal
----

Now you will have a dev version in your local which you can use to test your features.


=== Running the test suite


All you have to do to run the full suite of tests is:

[source,groovy]
----
./gradlew check
----

These will take a while (15-30 mins on slower machines, modern hardware will run the build in approximately 5 minutes), so consider running individual tests using the command line.
For example, to run the test spec `BinaryPluginSpec` simply execute the following command:
[source,groovy]
----
./gradlew :grails-core:test --tests *.BinaryPluginSpec
----

Note that you need to specify the sub-project that the test case resides in, because the top-level "test" target won't work....

Please also note that a container runtime is required to run tests.

=== Developing in IntelliJ IDEA


You need to run the following gradle task:
[source,groovy]
----
./gradlew idea
----

Then open the project file which is generated in IDEA. Simple!


=== Debugging Grails or a Grails application


To enable debugging, run:

[source,groovy]
----
grails run-app --debug-jvm
----

[source,groovy]
----
./gradlew bootRun --debug-jvm
----

By default Grails forks a JVM to run the application in. The `-debug-jvm` argument causes the debugger to be associated with the forked JVM.  In order to instead attach the debugger to the build system which is going to fork the JVM use the `-debug` option:

[source,groovy]
----
grails -debug run-app
----
By default Grails forks a JVM to run the application in. The `-debug-jvm` argument causes the debugger to be associated with the forked JVM.