[lucene-solr] branch master updated: LUCENE-9509: Refine lucene/BUILD.md and top-level README (for newdevs) (#1835)

[to...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

tomoko pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/lucene-solr.git


The following commit(s) were added to refs/heads/master by this push:
     new 51484e1  LUCENE-9509: Refine lucene/BUILD.md and top-level README (for newdevs) (#1835)
51484e1 is described below

commit 51484e138bfa0b96dac5456828c8d74f5b18944d
Author: Tomoko Uchida <to...@gmail.com>
AuthorDate: Mon Sep 7 19:08:38 2020 +0900

    LUCENE-9509: Refine lucene/BUILD.md and top-level README (for newdevs) (#1835)
---
 README.md       | 22 +++++++++++++++++++---
 lucene/BUILD.md | 47 +++++++++++++++++++++++++++--------------------
 2 files changed, 46 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index e045c7c..5b3a8e2 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 build
 system. 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; the 
 package can be located at:
@@ -65,6 +79,8 @@ For development, especially when you have created test indexes etc, use
 the `./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 Solr
 
 After [building Solr](#building-lucene-solr), the server can be started using
diff --git a/lucene/BUILD.md b/lucene/BUILD.md
index 9846ed7..84154bb 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 learning
 more about Java, before returning to this README. Lucene runs with
 Java 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 longer
 be necessary to download Solr to build Lucene. You can track
@@ -24,45 +24,52 @@ progress at: https://issues.apache.org/jira/browse/SOLR-14497
 NOTE: Lucene changed from Ant to Gradle as of release 9.0. Prior releases
 still use Ant.
 
-## Step 1) Download/Checkout Lucene source code
+## Step 1) Checkout/Download Lucene source code
 
 We'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.html
 
 Download either a zip or a tarred/gzipped version of the archive, and
 uncompress 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 tree
 
 The 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 of
 the settings in this file, but you do need to run Gradle from this location so 
 it 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 Gradle
 
 Assuming you can exectue "./gradlew help" should show you the main tasks that
 can 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: