Don't use JBang runner for examples

[rvansa]

I don't like that the examples are running through another runner using JBang. java -jar qDup.jar should be just enough - if you need it e.g. to obtain username, rather than reading it from system properties in the runner you should support ${{SYS.user.name}} as the default.

IIUC JBang does not even run qDup in the current dir but instead fetches qDup 0.6.12

[johnaohara]

You do not need to use jbang to run the examples, the first section in examples docs shows exactly that:

java -jar ../../target/qDup-*-uber.jar -b wildfly.yaml

But, Java is an implementation detail of qDup. We can not assume that users of qDup are java users, or maven users, or have java toolset installed in their machines.

using jbang, users do not need to learn how to download java, install java, build a java proejct etc, they just have a one-line command that installs a JVM for them if it is missing, downloads the qDup maven artefacts and executes the qDup script. This happens without them having to know anything about Java

jbang fetching an older version of qDup is an issue and it should be using the latest release

[rvansa]

Anywhere I've seen qDup used it's used directly (in the user guide as well); we should not recommend a tool (the runner) that we don't use ourselves. That approach leads to different UX and problems as the old version being used.

Having java pre-installed in the system (and available on the classpath) is the same level of requirement as with jbang, and Java is more 'standard' one. I agree that Maven might be too much.

[johnaohara]

Having java pre-installed in the system (and available on the classpath) is the same level of requirement as with jbang, and Java is more 'standard' one. I agree that Maven might be too much.

I don't agree with this statement. in order to set up an environment a user needs to

1. download and install a Java runtime and ensure the classpath is correctly setup
2. download the qDup binary from (know where to look for that binary)
3. know how to start a Java program with that binary file. there is risk that they have put the jar in the wrong directory

There is nothing stopping you, as a Java developer, invoking the jar directly. But for users we shouldn't expect them to have any knowledge of the Java runtime, it is a distraction for their learning.

We need to put ourselves in the position of someone new to qDup, who does not have any Java experience, their aim is to run a qDup script. Just because we always written documentation assuming that we are writing for Java devs, we shouldn't continue to make that assumption, esp if we want non-java users to use qDup (and there are a lot of non-Java users)

[johnaohara]

I suppose my point is, leaving it as is does not impact your use of the tool.

But taking it out makes life more difficult for a new user

[johnaohara]

@rvansa In #130 you mention;

And the current jBang command does not work with 0.6.12...

I checked the jbang script with the hello-world example. There is an error in the hello-world.yaml, but once that is fixed, i don't see an error;

$ ./runQDup.java 
[jbang] Building jar...
16:37:23.201 [main] INFO  io.hyperfoil.tools.qdup.QDup - Starting with output path = /tmp/20220914_163723
16:37:23.320 [main] INFO  io.hyperfoil.tools.qdup.JsonServer - listening at localhost.localdomain:31337
16:37:23.365 Running qDup version 0.6.12 @ unknown
16:37:23.367 run-1663169843146 starting state:
 GREETING = Hello qDup!
 USER = johara
 HOST = localhost.localdomain

16:37:23.369 [main] INFO  i.h.tools.qdup.cmd.Dispatcher - starting 0 scripts
16:37:23.439 [qdup-command-1] INFO  o.a.s.c.u.s.e.EdDSASecurityProviderRegistrar - getOrCreateProvider(EdDSA) created instance of net.i2p.crypto.eddsa.EdDSASecurityProvider
16:37:23.472 [qdup-command-1] INFO  o.a.s.c.i.DefaultIoServiceFactoryFactory - No detected/configured IoServiceFactoryFactory using Nio2ServiceFactoryFactory
16:37:23.476 [qdup-command-1] INFO  o.a.s.c.c.h.DefaultConfigFileHostEntryResolver - resolveEffectiveResolver([email protected]:22) loaded 1 entries from /home/johara/.ssh/config
16:37:24.181 [qdup-command-0] INFO  i.h.tools.qdup.cmd.Dispatcher - starting 1 scripts
16:37:24.181 [qdup-command-0] INFO  i.h.tools.qdup.cmd.Dispatcher - starting nanny
16:37:24.183 hello-qdup:10@localhost:script-cmd: hello-qdup
16:37:24.183 hello-qdup:10@localhost:hello-qdup
16:37:24.493 hello-qdup:10@localhost:echo Hello qDup!
Hello qDup!
16:37:24.499 [qdup-command-6] INFO  io.hyperfoil.tools.qdup.Run - run-1663169843146 runPendingDownloads
16:37:24.500 [qdup-command-6] INFO  io.hyperfoil.tools.qdup.Run - run-1663169843146 -> /tmp/20220914_163723.queueCleanupScripts
16:37:24.500 [qdup-command-6] INFO  i.h.tools.qdup.cmd.Dispatcher - starting 0 scripts
16:37:24.501 [qdup-command-7] INFO  io.hyperfoil.tools.qdup.Run - run-1663169843146 runPendingDownloads
16:37:24.501 run-1663169843146 closing state:
 GREETING = Hello qDup!
 USER = johara
 HOST = localhost.localdomain
 localhost.localdomain : 
   hello-qdup : 
     id=5 : 

Finished in 01.141 at /tmp/20220914_163723
16:37:25.509 [shutdown-abort] WARN  io.hyperfoil.tools.qdup.Run - Skipping cleanup - Abort has been defined to not run any cleanup scripts
16:37:25.509 [shutdown-abort] WARN  i.h.tools.qdup.cmd.Dispatcher - ignoring stop call when already stopped

Do you see an error message?

[rvansa]

Ouch, mea culpa - I had an older version of qDup checked out. It really works, even with 0.6.15 as the last version.

[johnaohara]

I was also thinking about the possibility to expose the script as jbang alias, so a user could run

$ curl -Ls https://sh.jbang.dev | bash -s - app setup
$ jbang qDup@run https://raw.githubusercontent.com/Hyperfoil/qDup/master/docs/examples/helloWorld.yaml

That way they would not need anything pre-installed (even java), they would not even have to clone the repo