jRuby Discussion

Add-ons Other
1

@rlkoshak: I’d love to get additional feedback from you on these (constructive!) criticisms. You’re a definite (spiritual, if not official :wink: ) leader in the community.

I know UI rules are supported now, and have been for some time. They’re probably not the primary method that any of the people that maintain the JRuby/OpenHAB libraries use, but we’re at least aware of them. So let’s assume that’s no longer an issue…

As for the gem installation method - I’m kind of surprised. I’ve always felt the gem method was ingenious and super friction-free. But maybe that’s because my comparison was trying to install the JavaScript and/or Python helper libraries in the super early days of support for non-DSL rules of any type in the first place, where you had to do git clones and modify files, and then updating them was all-but impossible. And I’m also partial to and very familiar with gems, since I have a very deep Ruby background. So… how do you think we could make this better? At the moment, the workflow is the install the org.openhab.automation.jrubyscripting add-on, then go and configure it to tell it which gem(s) you want installed by default, including version constraints. I think there has been hesitancy in the past by maintainers of the JRuby/openHAB libraries to too-strongly endorse their own gem. But it seems like maybe that’s misplaced. How would you feel if we changed the default configuration for the add-on to install a helper library gem? Would eliminate one more step. I can’t imagine anyone using any of the JSR223 languages without a helper library nowadays. After working on the helper library extensively the past few months, I think I finally could write some rules without it, but it would be a lot of work.

Next up … inter-rule caching. I assume you’re referring mainly to UI rules, no? Because if you’re writing file-based rules, it’s excessively simple to just have a variable (there are several types in Ruby) that lives at the top level outside of any particular rule, just like you would in DSL. There’s not currently a way to access a global variable between files, because each file gets its own instance of JRuby (unless you tweak some configuration that the add-on at least lets you tweak, but hasn’t really been tested to work well that way). Okay, so back to UI rules - wouldn’t all languages have the same problem? It seems that https://github.com/openhab/openhab-core/pull/2887 is really what we need, and it’s still pending. As soon as it’s in, I’d be happy to quickly add idiomatic support to it for the JRuby libraries. If you really think this is a major obstacle to adoption of people using JRuby actions, I could even jump in and try to get the core PR through. I’ve been gaining some experience in core and a couple of other addons lately too, so I’m feeling like I could get to that.

And finally… documentation. I totally hear you here. For the past month or two I’ve been working on major refactoring of the JRuby scripting libraries, and part of that was motivated by dissatisfaction with the documentation (both using it, and writing it). You can see the new docs for my release candidate at Redirecting to YARD documentation.../. It’s now strictly in the primary code-documentation tool for Ruby (YARD), so the class, method, and parameter details etc. are guaranteed to be up to date with the library’s actual code, and the examples are now inline so you don’t have to jump back and forth between example and narrative documentation to the technical documentation. It is still not on Introduction | openHAB, but given that the library evolves on a very different schedule from openHAB itself, I don’t think that’s necessarily a bad thing – and wouldn’t really be possible I don’t think, given how it’s generated via YARD. We could definitely improve the theming to look more like the official documentation site. So, given that, would a link to this documentation from the add-on’s README and main configuration page in openHAB proper improve the discoverability enough?

Oh, and one more thing. Would you recommend that we try to get the gem’s repository moved into the openHAB org on GitHub, instead of hosted on our own personal account? It doesn’t really matter to me where it is, as long as we can continue to maintain it ourselves. But it would give even more air of endorsement of “this is how you use Ruby in openHAB”. And the docs could move to https://openhab.github.io/openhab-jrubyscripting/ - a slightly better URL.

Let me know your thoughts, I definitely want to appeal to as broad of an audience of openHAB users as possible.

1 Like
2

Except for the lack of a cache (unless that’s what local_contex is about, though from reading the description I’m not sure). In the UI, there is no “outside the rule” where you can define and save variables from one run to the next or share between rules. That eliminates a number of use cases from being supportable in the UI.

Ideally there should be something in core to handle this and you pointed to the PR that I’m anxiously awaiting being merged to better solve this than what JS Scripting offers (see below).

Make it part of the add-on itself. JS Scripting requires no additional steps to obtain and use it’s helper library (openhab-js). When you install the add-on, you get the library automatically. Should you want to be on the bleeding edge or there is some bug that you need fixed that is available in a newer version of the library, you can install the helper library using npm. But that’s optional, not required.

In my advocating for treating UI rules as “first class citizens” as opposed to “something that only non-technical people will want to use and they’ll use Blockly anyway”, I came to the conclusion that forcing these users to have to go to the command line, install a bunch of stuff they may not already have installed so they can access gems and then installing the helper library even before you can write your first rule is not a good way. That’s a pretty steep barrier to climb to even get to where you can write your first rule. Though…

maybe that’s not how it works. It’s been a bit since I last looked at the jRuby docs. It’s good to see that at least you can install gems without going to the command line. That’s a really big improvement for sure. It’s not super clear what one needs to install to get the helper library but the example in the doc showing

For example this configuration will install the latest version of the openHAB JRuby Scripting Library (opens new window), and instruct the scripting engine to automatically insert require 'openhab' at the start of the script.

is enough direction to help users find and pick one.

That’s my point exactly. None of these languages are usable in OH without a helper library. And that’s why I feel strongly that:

  • the add-on should ship with a helper library

  • the helper library should be a repo under the openHAB project with more than one maintainer (so we don’t end up in the same situation we found ourselves when @5iver disappeared and there was no one with the ability to keep the repo going without forking

  • the docs for the helper library should be a part of the official openHAB docs. Users should not have to go somewhere else to learn how to write OH rules in the language.

It’s more than just a usability issue to me. It’s also a longevity issue. And it feels off to have an add-on that requires a third party library that doesn’t ship with the add-on to use it.

If there is more than one helper library, at least one of them should be part of the OH project. But that doesn’t preclude someone from installing and using an alternative if they choose. But there should be at least one that is the “official” one, the default one, and it should be a part of OH, not third party.

Of course, that’s just my opinion which doesn’t count for much.

Yes indeed.

Yes and for JS Scripting they added a cache to the add-on which is a Hashmap (I think) that lives inside the add-on itself and injected into the rules. This give a place outside the script actions and conditions to store and share stuff. Of course it’s not perfect. It was always just a stop gap until something like the PR I mentioned above comes along.

But without this, one cannot even share a variable between a script condition and script action for the same rule. Timers become a problem when you can’t cancel or reschedule them. etc. That eliminates whole classes of use cases.

The JS Scripting reference docs are generated using a third party tool similar to this. And @Confectrician has a way to update docs for certain pages outside the release cycle. @florian-h05 can provide some details on how it’s done I think from the JS Scripting side. There too the library advances outside the schedule of OH releases.

The theming isn’t that much of a concern as them being a part of the OH project itself and integrated somehow with the official OH docs.

Absolutely. See above.

1 Like
3

Fantastic responses! Definitely gives me a direction to work towards. I’ll check out how the JS docs are integrated in. That seems like the biggest hurdle to me. The rest are just work to be done.

@Lolodomo, @Kai, @J-N-K : are anyone of you the ones to get a repo created in the openHAB GitHub org (preferably named openhab-jrubyscripting), with myself (@ccutrer on GitHub) and @JimT (@jimtng on GitHub) as maintainers? Or point me to who can?

1 Like
4

I write all my jRuby rules in the UI. Everything seems to work a treat.
Glad to see jRuby getting some attention, I love it, I had never seen jRuby in my life but it is so easy to learn

1 Like
5

At JS Scripting/openhab-js, we have our docs at two locations:

  • Docs for the most common functionality provided by openhab-js are written down inside the openhab-js README. Those are not auto-generated, but as we want to keep our APIs stable, we don‘t have to update these too often.
  • Advanced docs auto-generated from the comments by JSDoc (the JS equivalent of YARD) and hosted at Home - Documentation. These are heavily linked from the README.

Our README API docs are written inside the openhab-js repo, we copy the content of the openhab-js README to the add-on README when we release a new version and upgrade the add-on to this new version.
At the moment, the updates to the add-on docs are done manually, but we want to automate that (@Confectrician has a look at that).

So, the JS Scripting add-on docs always refer to the openhab-js version included in the add-on, while Home - Documentation is the bleeding edge.

I think @Kai is the one to ask, if I remember correctly, he created the openhab-js library.

1 Like
6

I would go for openhab-jruby to keep it in the same style like openhab-js. :slightly_smiling_face:
Let’s see if i can reach out to kai, to get this started short-term.

It’s on the list and i did not yet have a deeper look yet, to be honest. :see_no_evil:
This is kind of a special case compared to the existing solutions for ecosystem components like alexa and google.

For the intrested one (click for details)

The currently existing workflows are based in the fact that content gets fetched from the external source into the openHAB docs repository, which is holding the original files.

In this case this will be different, because we have to fetch the stable docs from the openhab addons repository (so, an external source from the docs point of view) and also allow the docs to be changed from another external source. The openhab-js repository in this case.

But anyway it makes sense to solve this one time in a stable way and directly abstract the workflow for follow up solutions.
I would assume, that jruby (and any other scripting addon) will be the next repo with the identical usecase for different doc versions living in parallel.

A little bit off-topic:

I am not happy with having “official” doc contents on a github domain (even if it is placed in the openhab organisation), to be honest.
It totally makes sense, to have this generated and under control of the openhab-js maintainers,
but we should check what we can do to integrate this properly into the official docs.

I will talk to kai and we should at least get a proper openhab.org domain (with a cname entry in the openhab-js repository) for it on short term and check how to integrate the pages into the docs website on mid term.

1 Like
7

:+1: sounds good, thanks!

openhab-jruby is fine with me. I had chose jrubyscripting to match the name of the add-on. But it looks like js has the same dichotomy - the add-on is org.openhab.automation.jsscripting, and the repo is openhab-js.

3 Likes
8

shared cache is done (not quite merged yet; need to write more tests and expand on docs): Shared Cache by ccutrer · Pull Request #83 · ccutrer/openhab-jrubyscripting · GitHub, since the core PR was merged last night.

2 Likes
9

Update:

  • caching is done and merged
  • a major documentation refactor is pending review (refactor documentation by ccutrer · Pull Request #105 · ccutrer/openhab-jrubyscripting · GitHub), which will allow me to run YARD, and then copy it over to the add-on as a single README a la jsscripting. I even modeled the structure of it somewhat after jsscripting so it will be familiar.
  • After ^ is merged (and possibly after waiting for the not done below), I plan on doing a PR for the add-on to update its readme, and also set the default values for the gem to auto-install the helper library.

Not Done:

  • Creating a repo in the openhab org for the gem (and thus hosting the docs on openhab.github.io).
  • Hosting docs underneath the openhab.org domain.
1 Like