Best practice example suitable for a template

[Zethson]

Dear @remkop ,

I am planning to create a cookiecutter based java command line tool template. Picocli is of course perfect for that. However, I would like to offer a best practice template and don't have enough experience with picocli to be able to claim that.

Do you have a best practice example lying around? I saw some of your examples, but am not sure which one would suit best.

Thank you very much!
Best

[Zethson]

Ideally it would even have a few (unit) tests ready.

[remkop]

That is great, thank you!

For stand-alone programs, the Checksum example in the Introduction section of the user manual can be considered a canonical example: it has an option, a positional parameter, demonstrates mixinStandardHelpOptions to get help and version options, and demonstrates how implementing Runnable/Callable allows applications to use the execute method and get an exit code. That is a nice overview of a number of features that many applications are likely to need.

For Checksum unit tests, see this project: https://github.com/remkop/picocli-native-image-demo
This project is intended to demonstrate creating native executables with GraalVM, but it also has tests for the Checksum app.

Another common usage for picocli is command suites: commands with subcommands like git.
(Perhaps that should be a separate cookiecutter template?)

For command suites, the "best practice" is to use a @Command-annotated method for subcommands that have few (if any) options and perhaps not much code, and a @Command-annotated class for subcommands that have more options. The picocli user manual has this example: https://picocli.info/#_executing_subcommands

I don't have any example unit tests for an application using subcommands to point to. I usually have separate unit tests for each subcommand.

I hope this is useful. Thanks again for advocating picocli! 👍 😃

[Zethson]

Awesome, sounds like exactly what I need.
Maybe I will offer both options through a few if statements :)

I will update you again as soon as it is ready so that you can try it if you want to.

[remkop]

@Zethson How did it go? If you have a link I can point to it from the picocli readme or other docs.

[Zethson]

Dear @remkop

we were (and are) working a lot on the core code and implemented templates for other languages, but the JVM templates are our next target.
We're currently not quite sure how we should approach them.

We would like to implement the JVM templates as modules and also allow them to be easily packaged and distributed. Moreover, we would like to offer the choice of either Maven or Gradle.
We currently have a modular JavaFX template with Maven, which we are then packaging using an integrated version of Warp into single binaries.
However, the MacOS binaries tend to be broken (Linux works flawless).

Hence, we turned our eyes to the badass jlink plugin, but it seems to be heavily Gradle oriented and uses JPackage. JPackage has a few shortcomings:

1. It requires Java 14+ (our templates are supposed to be cutting edge, so I can live with that)
2. Linux binaries are deb or rpm packages, which not all Linux flavors support out of the box (e.g. Arch Linux)
3. It does not support everything:

"The following features of the javapackager tool will not be supported:
- Java Web Start application support,
- JavaFX-specific features,
- jdeps usage for determining required modules, and
- the Ant plugin."

I don't care about Ant, but JavaFX-specific features may sound evil.

We would rather not distribute Jars, but binaries with custom (platform dependent) JREs. We can script slightly more complex workflows for creating them into our templates, since they will ship with Makefiles anyways (every template has a Makefile which wraps language/framework dependent commands into consistent commands such as make test to run tests).

I would be very interested in your take on that. Do you have any suggestions, links or thoughts?
As you may notice we are not super deep into the JVM ecosystem, since our tool will support all domains and languages.

We do however want to do things right and not distribute half baked solutions.

Thanks!

[Zethson]

Actually, you've pointed me into the right direction already and I forgot about that:

https://github.com/remkop/picocli-native-image-demo and https://github.com/remkop/picocli-native-image-maven-demo should be example what I'm looking for.

I will explore these and keep you updated. ETA ~< 4 weeks :)

Edit: The CI of those 2 repositories doesn't seem to pass for all cases. @remkop would it be possible that you fix them up or do you expect everything to still work flawlessly?

Edit2: I played around with them and could get them to work. However, I had to fix a few things to make it work and opened a respective issue in the repositories @remkop .

[Zethson]

@remkop
It is now cookiecuttered:
https://github.com/Zethson/picocli_graalvm_cookiecutter

I will integrate it into our tool this week and then I can either add you to our tool so that you can test it or you can wait for the release (~4 weeks or something?) and enjoy the show.

[remkop]

I took a quick look, looks awesome! 👍 😍
Thank you very much for working on this!

[remkop]

Quite exciting! When do you think the next release will be (roughly)?

[Zethson]

Dear @remkop,

we had to postpone the release several times, since we want to add a couple of features before our first release.
We're planning to hit very early next month at the moment.

However, here's a small preview with a subset of our tools' features:

[remkop]

The preview looks very nice! Looking forward to the release!

[Zethson]

@remkop
https://github.com/cookiejar/cookietemple

ready now!
Feel free to try it out and to provide feedback if you want to.

Thanks!

[remkop]

Hi @Zethson, thanks for letting me know! I will add a link to https://cookietemple.readthedocs.io/en/latest/available_templates/available_templates.html#cli-java to the picocli README.

Question/request: Would it be possible to also mention Picocli in the Included frameworks/libraries list for cli-java?

---

Putting my editor/review hat on 😜 , I found what looks like a typo:

A platform dependent (of the current running operating system!) can then be build by invoking:

this should probably be

A platform dependent executable (for the current running operating system!) can then be build by invoking:

I also found this error message under linting your code/cli-java, not sure if this is the intention:

File not found. This error occurs when your project does not include all of cli-python’s expected files.
Please create the file and populate it with appropriate values. You should also critically reflect why it is missing, since at the time of the project creation using cookietemple this file should not have been missing!

---

Overall, very nice! Thanks for getting back to me!

[Zethson]

Question/request: Would it be possible to also mention Picocli in the Included frameworks/libraries list for cli-java?

Oh absolutely. We likely forgot it somehow.

And thank you for the other comments! We will fix everything.