LUCENE-10230 make demo builds easier to execute

[hendrikmuhs]

Description

Setting up and executing the demo is complicated, but it should be as easy as starting luke. This change adds build steps to create a jar for executing the demos easier.

#11266

Solution

The change is mainly gradle and some documentation adjustments.

Note: I followed/copied logic from https://github.com/apache/lucene/blob/main/lucene/luke/build.gradle.

Tests

Does not apply, the change only affects build code.

Checklist

Please review the following and check all that apply:

• [x] I have reviewed the guidelines for How to Contribute and my code conforms to the standards described there to the best of my ability.
• [x] I have created a Jira issue and added the issue ID to my pull request title.
• [ ] I have given Lucene maintainers access to contribute to my PR branch. (optional but recommended)
• [x] I have developed this patch against the main branch.
• [x] I have run ./gradlew check.
• [ ] I have added tests for my changes.

[dweiss]

I'm not a big fan of the manifest-based solution, even if I initially wrote it. If you use the module path, starting demos is fairly simple - see here: https://github.com/apache/lucene/blob/main/dev-tools/scripts/smokeTestRelease.py#L661-L665

It should be the module system that takes care of resolving dependencies, eventually (it works now but we don't leverage its full potential).

Also, I don't think the demo has to be runnable from the source module directly - it'd be better to modify the docs to instruct how to build the binary distribution and run the demo from there. This does not add any new build code and makes for a single point of failure. If somebody is desperate to run from the source distribution they should build the binary release first and then follow regular demo-launching instructions from there?

It should really be simple. Something like:

If you'd like to run Lucene demos, build the binary distribution with:
gradlew -p lucene/distribution assembleBinaryTgz
cd lucene/distribution/build/packages
tar -zxf lucene-*.tgz
cd lucene*

and then run:
java --module-path modules --module lucene.core/org.apache.lucene.index.CheckIndex [arguments]
java --module-path modules --module lucene.demo/org.apache.lucene.demo.IndexFiles [arguments]
java --module-path modules --module lucene.demo/org.apache.lucene.demo.SearchFiles [arguments]

I honestly see little point in adding source-level demo application assembly or direct launchers. If you work with source code, you probably use an IDE and it takes care of the dependencies for you. If you don't use the IDE... well, then the above four lines assemble everything for you. Fewer gradle build code = better.

What do you think?

[hendrikmuhs]

@dweiss

Thanks for the feedback. I agree about avoiding gradle magic. The module suggestion is great and helped me finding a better solution for me (I want to run things from the source tree, but that's another story and you are right, most users don't).

Following up on the story about making the demo's easier to setup. I will change the documentation according to your suggestion. I wonder, I just found scripts for luke which simply wrap the commands you gave: https://github.com/apache/lucene/tree/main/lucene/distribution/src/binary-release/bin

May I add similar scripts for the demo apps? Alternatively it could be 1 script that takes the demo name from the command-line, e.g.

demo.sh IndexFiles [arguments]
demo.sh SearchFiles [arguments]

[dweiss]

I think some of these "demo" classes come from different modules - this is legacy and highly unstructured... But feel free to provide a patch, sure. I was thinking about it myself.

[github-actions[bot]]

This PR has not had activity in the past 2 weeks, labeling it as stale. If the PR is waiting for review, notify the [email protected] list. Thank you for your contribution!