Apache Solr open-source search software
Update the help folder for solr only (#6)
Jan Høydahl372b293fe79f
diff --git a/help/ant.txt b/help/ant.txtindex 61a00acb60f..c62bb512985 100644--- a/help/ant.txt+++ b/help/ant.txt@@ -10,8 +10,8 @@ Gradle tasks apply to all modules that contain a given task name. Use"-p" switch with a directory or a colon-notation to specify a particulartask or module. For example these two are equivalent:-gradlew -p lucene/core check-gradlew :lucene:core:check+gradlew -p solr/core check+gradlew :solr:core:checkList of common dev task equivalents-----------------------------------diff --git a/help/dependencies.txt b/help/dependencies.txtindex 5db03c9c140..318b6887912 100644--- a/help/dependencies.txt+++ b/help/dependencies.txt@@ -13,7 +13,7 @@ https://docs.gradle.org/current/userguide/dependency_management_for_java_projecthttps://docs.gradle.org/current/userguide/java_library_plugin.html#sec:java_library_separationhttps://docs.gradle.org/current/userguide/java_plugin.html#sec:java_plugin_and_dependency_management-For the needs of Lucene and Solr we will typically focus on three+For the needs of Solr we will typically focus on threeconfigurations and attach project dependencies to them:api - makes a dependency available for main classes, tests and any@@ -30,9 +30,9 @@ Adding a library dependency---------------------------Let's say we wish to add a dependency on library "foo.bar:baz" in-version 1.2 to :lucene:core. Let's assume this library is only-used internally by the project. The :lucene:core project is configured-by lucene/core/build.gradle and we would add (or modify) the dependency+version 1.2 to :solr:core. Let's assume this library is only+used internally by the project. The :solr:core project is configured+by solr/core/build.gradle and we would add (or modify) the dependencyblock as follows:dependencies {@@ -90,7 +90,7 @@ Inspecting current dependenciesThe tree of dependencies of a project (in all configurations) canbe dumped by the following command (example):-gradlew -p lucene\analysis\icu dependencies+gradlew -p solr/solrj dependenciesBut this can be a bit overwhelming; we will most likely be interestedin just the "publicly visible" and "classpath-visible" configurations.@@ -98,12 +98,12 @@ in just the "publicly visible" and "classpath-visible" configurations.The publicly visible project dependencies (classes shared by othermodules importing our module) can be displayed with:-gradlew -p lucene\analysis\icu dependencies --configuration api+gradlew -p solr/solrj dependencies --configuration apiAnd the "private" set of dependencies (real classpath) can be dumpedwith:-gradlew -p lucene\analysis\icu dependencies --configuration runtimeClasspath+gradlew -p solr/solrj dependencies --configuration runtimeClasspathExcluding a transitive dependencydiff --git a/help/formatting.txt b/help/formatting.txtindex 55490ac75ce..96240b3f44d 100644--- a/help/formatting.txt+++ b/help/formatting.txt@@ -1,7 +1,13 @@Code formatting===============-Starting with (LUCENE-9564) Java code is enforced to comply with+NOTE: This does not yet apply to Solr, see SOLR-14920 for details+++++---+Starting with (SOLR-14920) Java code is enforced to comply withgoogle-java-format conventions. In theory you shouldn't worry aboutwhat the convention actually looks like - write the code in any wayyou like and then run:@@ -18,3 +24,4 @@ majority of cases the formatter will do a great job of cleaning up thecode. Occasionally you may want to rewrite the code (introduce a localvariable orreshape code paths) so that it's easier to read afterautomatic formatting.+---\ No newline at end of filediff --git a/help/jvms.txt b/help/jvms.txtindex 42a88d2c0b4..3e14a8d5fd5 100644--- a/help/jvms.txt+++ b/help/jvms.txt@@ -12,7 +12,7 @@ property (-P...).Example:-gradlew test -p lucene/test-framework --tests TestJvmInfo -Dtests.verbose=true -Druntime.java.home=/jvms/jdk14+gradlew test -p solr/test-framework --tests TestLogLevelAnnotations -Dtests.verbose=true -Druntime.java.home=/jvms/jdk14Note that an alternative JVM can also be made the "default" settingby adding it to (project-local) gradle.properties.diff --git a/help/localSettings.txt b/help/localSettings.txtindex 263af7f711c..13364974b06 100644--- a/help/localSettings.txt+++ b/help/localSettings.txt@@ -1,7 +1,7 @@Local developer settings========================-The first invocation of any task in Lucene/Solr gradle build will generate+The first invocation of any task in Solr gradle build will generateand save a project-local 'gradle.properties' file. This file containsthe defaults you may (but don't have to) tweak for your particular hardware(or taste).@@ -12,7 +12,7 @@ Parallelism-----------Gradle build can run tasks in parallel but by default it consumes all CPU cores which-is too optimistic a default for Lucene/Solr tests. You can disable the parallelism+is too optimistic a default for Solr tests. You can disable the parallelismentirely or assign it a 'low' priority with these properties:org.gradle.parallel=[true, false]diff --git a/help/tests.txt b/help/tests.txtindex 5054c0ee02d..2cbc84790a9 100644--- a/help/tests.txt+++ b/help/tests.txt@@ -23,8 +23,8 @@ gradlew check -x testRun verification for a selected module only:-gradlew :lucene:core:check # By full gradle project path-gradlew -p lucene/core check # By folder designation + task+gradlew :solr:core:check # By full gradle project path+gradlew -p solr/core check # By folder designation + taskRandomization@@ -33,35 +33,35 @@ RandomizationTo run tests with the given starting seed pass 'tests.seed'property:-gradlew :lucene:misc:test -Ptests.seed=DEADBEEF+gradlew :solr:solrj:test -Ptests.seed=DEADBEEFThere are a lot of other test randomization propertiesavailable. To list them, their defaults and current valuesrun the testOpts task against a project that has tests.For example:-gradlew -p lucene/core testOpts+gradlew -p solr/core testOptsFiltering----------Run tests of lucene-core module:+Run tests of solr-core module:-gradlew -p lucene/core test+gradlew -p solr/core testRun a single test case (from a single module). Uses gradle's built-in filtering(https://docs.gradle.org/current/userguide/java_testing.html#test_filtering):-gradlew -p lucene/core test --tests TestDemo+gradlew -p solr/core test --tests TestDemoRun all tests in a package:-gradlew -p lucene/core test --tests "org.apache.lucene.document.*"+gradlew -p solr/core test --tests "org.apache.solr.index.*"Run all test classes/ methods that match this pattern:-gradlew -p lucene/core test --tests "*testFeatureMissing*"+gradlew -p solr/core test --tests "*RPTField*"Test groups@@ -72,13 +72,13 @@ Some test group annotations include: @AwaitsFix, @Nightly, @SlowThis uses filtering infrastructure on the *runner* (randomizedtesting),not gradle's built-in mechanisms (but it can be combined with "--tests").-For example, run all lucene-core tests annotated as @Slow:+For example, run all solr-core tests annotated as @Slow:-gradlew -p lucene/core test -Ptests.filter=@Slow+gradlew -p solr/core test -Ptests.filter=@SlowTest group filters can be combined into Boolean expressions:-gradlew -p lucene/core test "default and not(@awaitsfix or @slow)"+gradlew -p solr/core test "default and not(@awaitsfix or @slow)"Reiteration ("beasting")@@ -87,19 +87,19 @@ Reiteration ("beasting")Multiply each test case N times (this works by repeating the same testwithin the same JVM; it also works in IDEs):-gradlew -p lucene/core test --tests TestDemo -Ptests.iters=5+gradlew -p solr/core test --tests TestDemo -Ptests.iters=5Tests tasks will be (by default) re-executed on each invocation becausewe pick a random global tests.seed. If you run the same tests twicewith the same seed, the test task will be skipped (as it is up-to-datewith respect to source code):-gradlew -p lucene/core test -Ptests.seed=deadbeef+gradlew -p solr/core test -Ptests.seed=deadbeefto force re-execution of tests, even for the same master seed, applycleanTest task:-gradlew -p lucene/core cleanTest test -Ptests.seed=deadbeef+gradlew -p solr/core cleanTest test -Ptests.seed=deadbeefThe 'tests.iters' option should be sufficient for individual test casesand is *much* faster than trying to duplicate re-runs of the entire@@ -107,7 +107,7 @@ test suites. When it is absolutely needed to re-run an entire suite (becauseof randomization in the static initialization, for example), you can do itby running the 'beast' task with 'tests.dups' option:-gradlew -p lucene/core beast -Ptests.dups=10 --tests TestPerFieldDocValuesFormat+gradlew -p solr/core beast -Ptests.dups=10 --tests DummyMergePolicyFactoryNote the filter (--tests) used to narrow down test reiterations to a particularclass. You can use any filter, including no filter at all, but it rarely makes@@ -115,7 +115,7 @@ sense (will take ages). By default the test tasks generated by the 'beast' modeuse a random starting seed for randomization. If you pass an explicit seed, thiswon't be the case (all tasks will use exactly the same starting seed):-gradlew -p lucene/core beast -Ptests.dups=10 --tests TestPerFieldDocValuesFormat -Dtests.seed=deadbeef+gradlew -p solr/core beast -Ptests.dups=10 --tests DummyMergePolicyFactory -Dtests.seed=deadbeefVerbose mode and debugging--------------------------@@ -124,7 +124,7 @@ The "tests.verbose" mode switch enables standard streams from teststo be dumped directly to the console. Run your verbose tests explicitlyspecifying the project and test task or a fully qualified task path. Example:-gradlew -p lucene/core test -Ptests.verbose=true --tests "TestDemo"+gradlew -p solr/core test -Ptests.verbose=true --tests "TestDemo"Profiling slow tests@@ -135,23 +135,23 @@ and prints a simple summary at the end.For example, top-10 histogram of methods (cpu samples):-gradlew -p lucene/core test -Ptests.profile=true+gradlew -p solr/core test -Ptests.profile=trueAlternatively, you can profile heap allocations instead:-gradlew -p lucene/core test -Ptests.profile=true -Ptests.profile.mode=heap+gradlew -p solr/core test -Ptests.profile=true -Ptests.profile.mode=heapBy default, results are computed (deduplicated) on just the method name, foldingtogether all events from the same method. To drill down further, you can increase thestack size from the default of 1, to get a histogram of stacktraces instead:-gradlew -p lucene/core test -Ptests.profile=true -Ptests.profile.stacksize=8+gradlew -p solr/core test -Ptests.profile=true -Ptests.profile.stacksize=8For big methods, it can also be helpful to include line numbers for more granularity:-gradlew -p lucene/core test -Ptests.profile=true -Ptests.profile.linenumbers=true+gradlew -p solr/core test -Ptests.profile=true -Ptests.profile.linenumbers=trueUsing these additional options will make the results more sparse, so it may be usefulto increase the top-N count:-gradlew -p lucene/core test -Ptests.profile=true -Ptests.profile.count=100+gradlew -p solr/core test -Ptests.profile=true -Ptests.profile.count=100diff --git a/help/workflow.txt b/help/workflow.txtindex d70b2436dcb..eec7c4e33bf 100644--- a/help/workflow.txt+++ b/help/workflow.txt@@ -4,13 +4,13 @@ Typical workflow and tasksThis shows some typical workflow gradle commands.Run tests on a module:-gradlew -p lucene/core test+gradlew -p solr/core testRun test of a single-class (run "gradlew :helpTests" for more):-gradlew -p lucene/core test --tests "*Demo*"+gradlew -p solr/core test --tests "*Demo*"Run all tests and validation checks on a module:-gradlew -p lucene/core check+gradlew -p solr/core checkRun all tests and validation checks on everything:gradlew check@@ -18,9 +18,9 @@ gradlew checkRun all validation checks but skip all tests:gradlew check -x test-Assemble a single module's JAR (here for lucene-core):-gradlew -p lucene/core assemble-ls lucene/core/build/libs+Assemble a single module's JAR (here for solr-core):+gradlew -p solr/core assemble+ls solr/core/build/libsCreate all distributable packages, POMs, etc. and create alocal maven repository for inspection: