How should we deliver relevant code examples to users?

Currently, the OMS CAL includes tests & examples in the generated code. I don’t know the specifics for OMS, whether this is required for a complete OMS CAL or if it’s just something Tangram decided to do. However, the same doesn’t exist for LMCP at least, and probably not STANAG either.

This topic begs the question “Should we deliver code examples”, and my answer is of course “yes”.

But where should that happen?

  • To a brand-new user of Tangram or of a particular CSI, the first thing they’ll probably do is look at the generated code. For that user, having examples built-in (like OMS), as well as a solid README, is probably a must-have.

  • For a user ready to generate production code, there’s no reason to include extra code or other files in the generated output.

  • It’s also certainly possible that we could provide some obvious pointers to the user, directing them to a different section of the site which provides downloads for example code.

My personal opinion is that we should build in a code-gen flag for example/test components, and have that option exposed to the user as a plugin option. The option defaults to true, so the new user sees what they need to see when they download code. The experienced user can just uncheck the box when they’re ready. I prefer this to having examples downloaded in a different place, because it reduces complexity and allows examples/tests to more easily link with the generated code & libs.

What are your thoughts? Is there a better way? Is the overarching question misguided?

@eric.zwirner @benjamin.kyrlach what’re your thoughts, from a code-gen perspective?

@fred.gillenwater and @mark.stadtmueller, also interested in your thoughts here from a customer-facing point of view.

A few thoughts:

  1. There still is a need/desire to generate test code along with “production” code. We are currently doing some capture work where that kind of code will be part of the overall pipeline where Tangram Pro is just one part of that cycle. But I would think for any kind of critical code you’ll always want that test code generated and executed with proof of that for your accreditor. I guess I’m not seeing why we wouldn’t always generate the test code but I don’t see harm in making that configurable either.

  2. We are also working toward generating run-time hooks for monitoring of events of interest. That same capture work calls that “run-time assurance.” For this case, we are talking about some kind of configurability as to whether this should be built into the code or not. For any kind of run-time hook there could also be a security consideration. Run-time hooks currently under consideration for OMS include for events when messages are read and/or written as well as created and/or destroyed. Still looking for other thoughts for more.

  3. We are also generally trying to sell code-gen as a means of generating test cases whether or not we generated the interface code due to how time consuming and error prone that can be when done manually. Obviously it will vary from situation to situation whether this makes sense but there are several upcoming opportunities where that’s a beneficial capability.

There are plans for more OMS test work including specific API test cases and to add the run-time hooks and we have some wiki pages in that repo with more details. Unfortunately program work is keeping the team from getting to do that any time soon.

I guess a few thoughts. I kind of take it from the point of view of a “newbie” that would like to accomplish something. I.e. I would like to reproduce what Jake did with the Aerres demo. So, to me, what I would like to see is a Tutorial on how to do that with each step. Just a side note, but as a newbie and on a readily available tutorial, understood that we would have to change from OMS to LMCP in the Tutorial. One of the things we would have to work out is whether we would walk through with someone on how to do the Flex transform from the NMEA message used in the demo to the LMCP (OMS used in demo) message. Part of me thinks that this is a future part of the demo when Flex available and for now we just provide the transform in the platform (so no code generated for that). But, then another part of the tutorial will be code gen. I am not sure we should give examples but in the tutorial we should show what to expect and that what to do with that code. I.e. load it in the listener and connect to the python script. I think the tutorial should provide the instructions (and python code) to do all that. But, then invariably someone’s set up will be different and they will have trouble. In this case, I think code snippets and dialog should provided here…Not sure if this answers the question…But, kind of how I think about it.

I’m a little late to the party, but for a little background on what was generated with the OMS CAL. I wrote those tests (now called the end-to-end) tests because I needed something to verify that the entire execution path (ceate message->seerialize->send->receive->deserialize->access data) worked. After hand-writing a few of them, I realized that our code-gen team had a great system for generating code based on the types in the model so I added templates to generate test code. While the test code here is fully functional and an example of how to use the API, I think for a new user, some better defined example code (either generated, or provided in documentation somewhere) would accelerate someone’s ability to make something useful out of the CAL or CSI.

As for whether or not to generate them all the time, I agree with @eric.zwirner that there is no reason to not generate the test code. There is little cost here and it is optionally compiled so there is also no impact on compiled size of the CSI library. I completely agree with @brandon.henry in that better documentation around the use of the CSI is needed. Once again, is this a generated product, or something else?

1 Like

I talked w/ Brandon re: this and previewed the new docs site.
There is a super early preview of what is coming here: https://docs.tangramflex.io/docs/vm/use#building-oms-end-to-end-test

We plan to have the docs static-site as a part of the product as well. More to come later.

2 Likes

As far as better example programs, I created notional Radar, Navigation, and Status components around August 2018 which employed the OMS CAL interface. Getting that working with the OMS CAL generated by our current code-gen capability may require a few Makefile changes but other than that it should work out of the box*. I can send that to you or whoever is interested via email.

*Of course, that’s after you also get the right version of ncurses and whatever other C++ dependency annoyances you have to deal with.

@joe.richardson, I would be interested in looking at those components that you created if you can email. Thanks!