Apache Solr open-source search software
LUCENE-9509: Refine lucene/BUILD.md and top-level README (for newdevs) (#1835)
Tomoko Uchida51484e138bfa
diff --git a/README.md b/README.mdindex e045c7c9d81..5b3a8e2120e 100644--- a/README.md+++ b/README.md@@ -36,12 +36,20 @@ comprehensive documentation, visit:- Lucene: <http://lucene.apache.org/core/documentation.html>- Solr: <http://lucene.apache.org/solr/guide/>-## Building Lucene/Solr+## Building with Gradle-(You do not need to do this if you downloaded a pre-built package)+### Building Lucene+See [lucene/BUILD.md](./lucene/BUILD.md).-### Building with Gradle+### Building Solr++Firstly, you need to set up your development environment (OpenJDK 11 or greater).++We'll assume that you know how to get and set up the JDK - if you+don't, then we suggest starting at https://www.oracle.com/java/ and learning+more about Java, before returning to this README. Solr runs with+Java 11 and later.As of 9.0, Lucene/Solr uses [Gradle](https://gradle.org/) as the buildsystem. Ant build support has been removed.@@ -50,6 +58,12 @@ To build Lucene and Solr, run (`./` can be omitted on Windows):`./gradlew assemble`+NOTE: DO NOT use `gradle` command that is already installed on your machine (unless you know what you'll do).+The "gradle wrapper" (gradlew) does the job - downloads the correct version of it, setups necessary configurations.++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.The command above packages a full distribution of Solr server; thepackage can be located at:@@ -65,6 +79,8 @@ For development, especially when you have created test indexes etc, usethe `./gradlew dev` task which will copy binaries to `./solr/packaging/build/dev`but _only_ overwrite the binaries which will preserve your test setup.+If you want to build the documentation, type `./gradlew buildSite`.+## Running SolrAfter [building Solr](#building-lucene-solr), the server can be started usingdiff --git a/lucene/BUILD.md b/lucene/BUILD.mdindex 9846ed74570..84154bba7f8 100644--- a/lucene/BUILD.md+++ b/lucene/BUILD.md@@ -15,7 +15,7 @@ don't, then we suggest starting at https://www.oracle.com/java/ and learningmore about Java, before returning to this README. Lucene runs withJava 11 and later.-Lucene uses [Gradle](https://gradle.org/) for build control; and includes Gradle wrapper script to download the correct version of it.+Lucene uses [Gradle](https://gradle.org/) for build control.NOTE: When Solr moves to a Top Level Project, it will no longerbe necessary to download Solr to build Lucene. You can track@@ -24,45 +24,52 @@ progress at: https://issues.apache.org/jira/browse/SOLR-14497NOTE: Lucene changed from Ant to Gradle as of release 9.0. Prior releasesstill use Ant.-## Step 1) Download/Checkout Lucene source code+## Step 1) Checkout/Download Lucene source codeWe'll assume you already did this, or you wouldn't be reading this-file. However, you might have received this file by some alternate-route, or you might have an incomplete copy of the Lucene, so: Lucene-releases are available as part of Solr for download at:+file. However, you might have received this file by some alternate+route, or you might have an incomplete copy of the Lucene, so: you+can directly checkout the source code from GitHub:- https://lucene.apache.org/solr/downloads.html+ https://github.com/apache/lucene-solr-See the note above for why it is necessary currently to download Solr+Or Lucene source archives at particlar releases are available as part of Solr downloads:++ https://lucene.apache.org/solr/downloads.htmlDownload either a zip or a tarred/gzipped version of the archive, anduncompress it into a directory of your choice.-Or you can directly checkout the source code from GitHub:-- https://github.com/apache/lucene-solr--## Step 2) From the command line, change (cd) into the top-level directory of your Lucene/Solr installation+## Step 2) Change directory (cd) into the top-level directory of the source treeThe parent directory for both Lucene and Solr contains the base configuration-file for the combined build, as well as the "gradle wrapper" (gradlew) that-makes invocation of Gradle easier. By default, you do not need to change any of+file for the combined build. By default, you do not need to change any ofthe settings in this file, but you do need to run Gradle from this location soit knows where to find the necessary configurations.-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.-## Step 4) Run GradleAssuming you can exectue "./gradlew help" should show you the main tasks thatcan be executed to show help sub-topics.If you want to build Lucene independent of Solr, type:- ./gradlew -p lucene assemble-If you want to build the documentation, type "./gradlew buildSite".+```+./gradlew -p lucene assemble+```++NOTE: DO NOT use `gradle` command that is already installed on your machine (unless you know what you'll do).+The "gradle wrapper" (gradlew) does the job - downloads the correct version of it, setups necessary configurations.++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.++If you want to build the documentation, type:++```+./gradlew -p lucene documentation+```For further information on Lucene, go to: