# Working With Solr Source Code

## Building Solr from Source

Download the Java 11 JDK (Java Development Kit) or later.
We recommend the OpenJDK distribution Eclipse Temurin available from https://adoptium.net/.
You will need the JDK installed, and the $JAVA_HOME/bin (Windows: %JAVA_HOME%\bin) folder included on your command path.
To test this, issue a "java -version" command from your shell (command prompt) and verify that the Java version is 11 or later.
See the xref:jvms.adoc[JVM developer doc] for more information on Gradle and JVMs.

Clone the latest Apache Solr source code directly from the Git repository: <https://solr.apache.org/community.html#version-control>.
Alternatively, you can download the Apache Solr distribution, from https://solr.apache.org/downloads.html and unzip the distribution to a folder of your choice, e.g. C:\solr or ~/solr.

Solr uses https://gradle.org/[Gradle] as the build system.
Navigate to the root of your source tree folder and issue the `./gradlew tasks` command to see the available options for building, testing, and packaging Solr.

`./gradlew dev` will create a Solr executable suitable for development.
Change directories via `cd ./solr/packaging/build/dev` and run the `bin/solr` script to start Solr.
It will also create a "slim" Solr executable based on the "slim" Solr distribution.
You can find this environment at `./solr/packaging/build/dev-slim`.
Use either `./gradlew devSlim` or `./gradlew devFull` to create just one type of distribution.

NOTE: `gradlew` is the "Gradle Wrapper" and will automatically download and start using the correct version of Gradle for Solr.

NOTE: `./gradlew help` will print a list of high-level tasks. There are also a number of plain-text files in <source folder root>/help that you can browse.

The first time you run Gradle, it will create a file "gradle.properties" that contains machine-specific settings.
Normally you can use this file as-is, but it can be modified if necessary.

Note as well that the gradle build does not create or copy binaries throughout the source repository so you need to switch to the packaging output folder `./solr/packaging/build`; the rest of the instructions below remain identical.
The packaging directory is rewritten on each build.

To build the documentation, type `./gradlew -p solr documentation`.

`./gradlew check` will assemble Solr and run all validation tasks unit tests.

NOTE: the `check` command requires `perl` and `python3` to be present on your `PATH` to validate documentation.

To build the final Solr artifacts run `./gradlew assemble`.

Lastly, there is developer oriented documentation in `./dev-docs/README.adoc` that you may find useful in working with Solr.

## Unit Tests

Please make sure that all unit tests succeed before constructing your patch.

> gradlew clean test


After a while, if you see a success or failure message.

Solr testing makes extensive use of randomization.
Each test starts with a "seed" for the random number generator, allowing repeatability.
We had one test, for instance, that only failed when the locale was set to a particular locale.
Re-using the seed reproduces these kinds of cases.

You'll find a "reproduce with..." message either on the screen or in the output that gives the exact command necessary.

Carefully read the errors messages and check your code.
If the test fails you may want to repeatedly rerun a single test as you debug and sort out any problems.
In which case you could run the "reproduce with" command in the output.

### Frequently failing Tests

There are some tests that fail sometimes on some systems, but run on Jenkins fine.
It's always a good idea to be sure you can run the full test suite successfully before you start making code changes.
Or keep an un-changed version of the code around to see if your changes are really to blame.

One of the great things about Open Source is so many people run the tests on so many different systems.
Occasionally you'll be the lucky person who has the system that wins the prize by having the environment that exposes a new failure mode, see the discussion at https://issues.apache.org/jira/browse/SOLR-3846 for an example.

If you do find one of these, here's what you should do:

1. If tests continue to fail, ask on the dev list if anyone else has seen the issue. This is the case where having the un-changed code helps. If the tests fail on both the changed and un-changed versions, discuss on the dev list whether the test should be disabled.
1. If tests fail with your changes but not on un-altered code, well, you need to understand why. By far the most frequent reason is a bug or unintended side-effect of your code, but occasionally it's a test that needs modification. Again, the dev list is a good place to discuss this.
1. Be very cautious about adding anything like @Ignore to a test. This is generally the wrong thing to do unless you get some consensus, and it'll surely generate "spirited debate".
1. Of course any effort you want to make towards tracking down the reason a test fails in your particular environment is greatly appreciated!

## Additional Information

You can review the https://github.com/apache/solr/blob/main/CONTRIBUTING.md[contribution guide] for information on how to contribute.
There are also additional helpful docs https://github.com/apache/solr/blob/main/help[in the help directory].