A few more console adjustments:

* Move "run" tasks to rhino-tools from rhino-all
* Document various ways to run the shell

# Conflicts:
#	rhino-all/build.gradle

Author: gbrail

README.md

@@ -8,6 +8,21 @@ Rhino is an implementation of JavaScript in Java.
 
 Rhino is licensed under the [MPL 2.0](./LICENSE.txt).
 
+## Summary
+
+Rhino requires Java 11 or higher to run, and 17 or higher to build. Java 21
+or 25 is highly recommended.
+
+To build and run a Rhino shell:
+
+    ./gradlew run -q --console=plain
+
+To run the tests:
+
+    git submodule init
+    git submodule update
+    ./gradlew check
+
 ## Releases
 
 The current release is <a href="https://github.com/mozilla/rhino/releases/tag/Rhino1_9_0_Release">Rhino 1.9.0</a>. Please see the [Release Notes](./RELEASE-NOTES.md).
@@ -43,11 +58,9 @@ features from ES6, and ES2016+ are implemented in Rhino.
 
 Information for script builders and embedders:
 
-[Archived](http://web.archive.org/web/20210304081342/https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Rhino/Documentation)
+[Documentation](https://rhino.github.io)
 
-JavaDoc for all the APIs:
-
-[https://javadoc.io/doc/org.mozilla/rhino](https://javadoc.io/doc/org.mozilla/rhino)
+[JavaDoc](https://javadoc.io/doc/org.mozilla/rhino)
 
 [List of projects using Rhino](USAGE.md)
 
@@ -73,17 +86,31 @@ testing but which are not published to Maven Central:
 * **benchmarks**: Runs benchmarks using JMH.
 * **examples**: Surprisingly, this contains example code.
 
+### Recommendations
+
+All applications that embed rhino need the main "rhino" module. Many applications don't
+need anything else -- consider doing the same, for a few reasons:
+
+* While "rhino-engine" implements the Java ScriptEngine interface, this is a strange
+abstraction that does not necessarily map well to Rhino.
+* "rhino-tools" includes the Global module, which many tools use because it includes
+handy built-in functions like "print" and "load". However, these are not part of any
+formal standard, and it includes functionality to launch programs and load
+files that you may not necessarily want in your environment. (Note that "rhino" includes
+an implementation of the "console" object that you may want to use instead.)
+
 ## Building
 
 ### Requirements
 
-Rhino requires Java 17 or higher to build. The "spotless" tool, which enforces code formatting, will not
-run on older Java versions and you will receive a warning. If in doubt, Java 21 works great.
+It's recommended to build Rhino using Java 25. However, it will build with Java 17
+and up. The "spotless" tool, which enforces code formatting, will not
+run on older Java versions -- it will emit a warning.
 
 Rhino runs on Java 11 and higher. The build tools use the "--release" flag to ensure that only
 features from Java 11 are used in the product.
 
-The CI tools run the Rhino tests on Java 11, 17, and 21. Regardless of what version of Java you are
+The CI tools run the Rhino tests on Java 11, 17, 21, and 25. Regardless of what version of Java you are
 building with, you can test on another Java version using the RHINO_TEST_JAVA_VERSION environment variable.
 
 ### How to Build
@@ -100,8 +127,22 @@ To just run the Rhino shell, you can do this from the top-level directory:
 
 Alternately, you can build an all-in-one JAR and run that:
 
-    ./gradlew :rhino-all:build
-    java -jar rhino-all/build/libs/rhino-all-1.7.16-SNAPSHOT.jar
+    ./gradlew shadowJar
+    java -jar rhino-all/build/libs/rhino-all-2.0.0-SNAPSHOT.jar
+
+And finally, you can extract the classpath and use it in a variety of ways:
+
+    export CLASSPATH=$(./gradlew -q printClasspath)
+    java org.mozilla.javascript.tools.shell.Main
+
+### JLine-Based Console
+
+If the JLine library is present, the Rhino shell will use it for command-line
+editing. The commands above will all include JLine. However, the Gradle wrapper
+interferes with JLine's ability to manipulate the terminal. For the best CLI
+experience, use either of the last two options, instead of ./gradlew run.
+
+### Benchmarking
 
 You can also run the benchmarks:
 
@@ -151,6 +192,7 @@ To see an aggregated coverage report for everything, which is probably what you
     ./gradlew testCodeCoverageReport
 
 The result is in:
+
     ./tests/build/reports/jacoco/testCodeCoverageReport/html
 
 ## Releasing and publishing new version

buildSrc/src/main/groovy/rhino.java-conventions.gradle

@@ -20,7 +20,7 @@ repositories {
 dependencies {
     testImplementation platform("org.junit:junit-bom:5.10.3")
     testImplementation "org.junit.jupiter:junit-jupiter"
-    testImplementation "junit:junit:4.13.2"
+    testImplementation libs.junit4
     testRuntimeOnly "org.junit.vintage:junit-vintage-engine"
     testRuntimeOnly "org.junit.platform:junit-platform-launcher"
     testImplementation "org.hamcrest:hamcrest:3.0"

gradle.properties

@@ -8,4 +8,4 @@ org.gradle.caching=true
 org.gradle.parallel=true
 org.gradle.configuration-cache=true
 android.useAndroidX=true
-org.gradle.jvmargs=--enable-native-access=ALL-UNNAMED
+org.gradle.jvmargs=--enable-native-access=ALL-UNNAMED

gradle/libs.versions.toml

@@ -0,0 +1,13 @@
+[versions]
+jline = '3.30.0'
+junit4 = '4.13.2'
+
+[libraries]
+junit4 = { group = 'junit', name = 'junit', version.ref = 'junit4' }
+jline-terminal = { group = 'org.jline', name = 'jline-terminal', version.ref = 'jline' }
+jline-reader = { group = 'org.jline', name = 'jline-reader', version.ref = 'jline' }
+jline-ffm = { group = 'org.jline', name = 'jline-terminal-ffm', version.ref = 'jline' }
+jline-jni = { group = 'org.jline', name = 'jline-terminal-jni', version.ref = 'jline' }
+
+[bundles]
+jline-runtime = [ 'jline-ffm', 'jline-jni' ]

it-android/build.gradle

@@ -64,7 +64,7 @@ if (!System.getenv("ANDROID_HOME") && !localProperties.get("sdk.dir")) {
         implementation project(':rhino-tools')
         implementation project(':rhino-xml')*/
 
-        testImplementation 'junit:junit:4.13.2'
+        testImplementation libs.junit4
         androidTestImplementation 'androidx.test:runner:1.7.0'
         androidTestImplementation 'androidx.test.ext:junit:1.3.0'
     }

rhino-all/build.gradle

@@ -1,25 +1,16 @@
 plugins {
     id 'rhino.library-conventions'
     id 'com.gradleup.shadow' version '9.3.1'
-    id 'application'
-}
-
-application {
-    mainClass = 'org.mozilla.javascript.tools.shell.Main'
-}
-
-run {
-    standardInput = System.in
 }
 
 dependencies {
     implementation project(':rhino')
     implementation project(':rhino-tools')
     implementation project(':rhino-xml')
-    runtimeOnly 'org.jline:jline-terminal:3.30.0'
-    runtimeOnly 'org.jline:jline-reader:3.30.0'
-    runtimeOnly 'org.jline:jline-terminal-ffm:3.30.0'
-    runtimeOnly 'org.jline:jline-terminal-jni:3.30.0'
+    // Include JLine so that the stand-alone JAR gets a nice terminal
+    runtimeOnly libs.jline.terminal
+    runtimeOnly libs.jline.reader
+    runtimeOnly libs.bundles.jline.runtime
 }
 
 shadowJar {
@@ -32,14 +23,9 @@ shadowJar {
     filesNotMatching('META-INF/services/**') {
         duplicatesStrategy = DuplicatesStrategy.FAIL // Or FAIL.
     }
-}
-
-startScripts {
-    dependsOn 'shadowJar'
-}
-
-startShadowScripts {
-    dependsOn 'jar'
+    manifest {
+        attributes 'Main-Class': 'org.mozilla.javascript.tools.shell.Main'
+    }
 }
 
 publishing {

rhino-tools/build.gradle

@@ -1,14 +1,58 @@
 plugins {
     id 'rhino.library-conventions'
+    id 'application'
+}
+
+application {
+    mainClass = 'org.mozilla.javascript.tools.shell.Main'
+}
+
+configurations {
+    shellOnly
 }
 
 dependencies {
     implementation project(':rhino')
-    compileOnly 'org.jline:jline-terminal:3.30.0'
-    compileOnly 'org.jline:jline-reader:3.30.0'
+    // Dependencies that ensure that we can compile with the JLine library
+    compileOnly libs.jline.terminal
+    compileOnly libs.jline.reader
+    // Dependencies that add JLine only for the "run" task
+    shellOnly libs.jline.terminal
+    shellOnly libs.jline.reader
+    shellOnly libs.bundles.jline.runtime
     testImplementation project(':testutils')
 }
 
+run {
+    standardInput = System.in
+    classpath = sourceSets.main.runtimeClasspath +
+            configurations.shellOnly
+}
+
+// This task makes it easier to write other command-line apps
+tasks.register('printClassPath') {
+    def cp = sourceSets.main.runtimeClasspath + configurations.shellOnly
+    inputs.files(cp)
+    doLast {
+        println cp.asPath
+    }
+}
+
+// Easy way to launch the debugger
+tasks.register('runDebugger', JavaExec) {
+    mainClass = 'org.mozilla.javascript.tools.debugger.Main'
+    classpath = sourceSets.main.runtimeClasspath
+}
+
+// This does the same thing as "gradle run" but adds a bit of usability
+// since we also have a "runDebugger" task
+tasks.register('runCli', JavaExec) {
+    mainClass = 'org.mozilla.javascript.tools.shell.Main'
+    classpath = sourceSets.main.runtimeClasspath +
+            configurations.shellOnly
+    standardInput = System.in
+}
+
 publishing {
     publications {
         rhinotools(MavenPublication) {

rhino-tools/src/main/java/org/mozilla/javascript/tools/shell/JLineConsoleProvider.java

@@ -29,10 +29,7 @@ public Console newConsole() {
 
     @Override
     public boolean isSupported() {
-        // Only allow JLine to be used if we have full functionality.
-        return (terminal != null
-                && !Terminal.TYPE_DUMB.equals(terminal.getType())
-                && !Terminal.TYPE_DUMB_COLOR.equals(terminal.getType()));
+        return (terminal != null);
     }
 
     @Override

testutils/build.gradle

@@ -8,5 +8,5 @@ dependencies {
     implementation project(':rhino')
     // We need this to be an "implementation" dependency because, in order to be shared
     // with tests in other projects, code in here must be in "main".
-    implementation "junit:junit:4.13.2"
+    implementation libs.junit4
 }