dev-docs/README.adoc - solr - Git at Google

 = Solr Developer Docs
 // 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
 //
 //   http://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.

 This directory includes information for Solr developers.   There are some other
 sources of information for learning about developing on Solr:

 1. The help .txt files for the Gradle commands in the `help/` directory.

 2. Information on how to handle adding dependencies and related licensing
 details, see the information in `/solr/licenses/README.committers.txt`.

 3. The Solr Reference Guide, which provides primarily end user oriented documentation.
 However, the Ref Guide hosts it's own documentation on how to write Ref Guide content.

 There are a number of tools related to doing development on Solr available in the `/dev-tools`
 directory.

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

 Download the Apache Solr distribution, from https://solr.apache.org/downloads.html.
 Unzip the distribution to a folder of your choice, e.g. C:\solr or ~/solr
 Alternately, you can obtain a copy of the latest Apache Solr source code
 directly from the Git repository:

 <https://solr.apache.org/community.html#version-control>

 Solr uses [Gradle](https://gradle.org/) 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.
 cd to `./solr/packaging/build/dev` and run the `bin/solr` script
 to start Solr.

 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.

 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.

 If you want to build the documentation, type `./gradlew -p solr documentation`.

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

 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.


 ### Gradle build and IDE support

 - *IntelliJ* - IntelliJ idea can import the project out of the box.
                Code formatting conventions should be manually adjusted.
 - *Eclipse*  - Not tested.
 - *Netbeans* - Not tested.


 ### Running Solr in Docker

 You can run Solr in Docker via the [official image](https://hub.docker.com/_/solr).

 To run Solr in a container and expose the Solr port, run:

 `docker run -p 8983:8983 solr`

 In order to start Solr in cloud mode, run the following.

 `docker run -p 8983:8983 solr solr-fg -c`

 For documentation on using the official docker builds, please refer to the [DockerHub page](https://hub.docker.com/_/solr).
 Up to date documentation for running locally built images of this branch can be found in the [local reference guide](solr/solr-ref-guide/src/running-solr-in-docker.adoc).

 There is also a gradle task for building custom Solr images from your local checkout.
 These local images are built identically to the official image except for retrieving the Solr artifacts locally instead of from the official release.
 This can be useful for testing out local changes as well as creating custom images for yourself or your organization.
 The task will output the image name to use at the end of the build.

 `./gradlew docker`

 For more info on building an image, run:

 `./gradlew helpDocker`
	= Solr Developer Docs
	// 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
	//
	// http://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.

	This directory includes information for Solr developers. There are some other
	sources of information for learning about developing on Solr:

	1. The help .txt files for the Gradle commands in the `help/` directory.

	2. Information on how to handle adding dependencies and related licensing
	details, see the information in `/solr/licenses/README.committers.txt`.

	3. The Solr Reference Guide, which provides primarily end user oriented documentation.
	However, the Ref Guide hosts it's own documentation on how to write Ref Guide content.

	There are a number of tools related to doing development on Solr available in the `/dev-tools`
	directory.

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

	Download the Apache Solr distribution, from https://solr.apache.org/downloads.html.
	Unzip the distribution to a folder of your choice, e.g. C:\solr or ~/solr
	Alternately, you can obtain a copy of the latest Apache Solr source code
	directly from the Git repository:

	<https://solr.apache.org/community.html#version-control>

	Solr uses [Gradle](https://gradle.org/) 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.
	cd to `./solr/packaging/build/dev` and run the `bin/solr` script
	to start Solr.

	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.

	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.

	If you want to build the documentation, type `./gradlew -p solr documentation`.

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

	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.


	### Gradle build and IDE support

	- IntelliJ - IntelliJ idea can import the project out of the box.
	Code formatting conventions should be manually adjusted.
	- Eclipse - Not tested.
	- Netbeans - Not tested.


	### Running Solr in Docker

	You can run Solr in Docker via the [official image](https://hub.docker.com/_/solr).

	To run Solr in a container and expose the Solr port, run:

	`docker run -p 8983:8983 solr`

	In order to start Solr in cloud mode, run the following.

	`docker run -p 8983:8983 solr solr-fg -c`

	For documentation on using the official docker builds, please refer to the [DockerHub page](https://hub.docker.com/_/solr).
	Up to date documentation for running locally built images of this branch can be found in the [local reference guide](solr/solr-ref-guide/src/running-solr-in-docker.adoc).

	There is also a gradle task for building custom Solr images from your local checkout.
	These local images are built identically to the official image except for retrieving the Solr artifacts locally instead of from the official release.
	This can be useful for testing out local changes as well as creating custom images for yourself or your organization.
	The task will output the image name to use at the end of the build.

	`./gradlew docker`

	For more info on building an image, run:

	`./gradlew helpDocker`