Questions about retooling code base to newer/better tools

ProffieOS
1

So sorry about cross posting on the fb proffieboard support group and rebel armory… I was advised that the was the best place to post.

Secondly, like all of you I’m a huge fan of star wars and lightsabers, and I love that proffie is an open source board and OS and I’m really appreciative of all the works that’s been done already.

So I just downloaded proffie OS6.7 and started looking at the code. And excuse me for talking like someone who’s job title includes the phrase “R&D computer science” but that’s who I am in real life, so this is largely a set of questions about the choice of build/test/documentation/etc. harness/infrastructure.

I mean I’m assuming there are very good reasons behind the current choices for and im just ignorant of what the historical motivation for those choices are. Then again it could have just been organic opensource development over a long period of time and the quality of software infrastructure tools have dramatically improved in the last 1.5 decades, and maybe switching to better tools hasn’t been done because of inertia/the cost (in terms of man hours) of retooling the code, because that’s true of a lot of projects I’ve been on at work and this is just something people contribute to as a hobby. So that’s the context of the following comments/questions.

So maybe I’m blind and/or just missed it in my very cursory examination of the code base but I’m not seeing a whole lot of documentation to help proffie OS newbs like me get a big picture of the os, how things connect (the folder structure is useful thoug).

Is there a reason the project is isn’t using doxygen (to autgenerate api docs from marked up comments?) Is there something about the compiler used by ardunio that the comments wouldn’t be stripped out during compile and they’d result in a bigger image to load?

Because doxygen opens the door to doxygraph. Doxygraph auto-generates uml diagrams from source code and when you load the web page you can checkbox what you want to see or not (so the amount of complexity of the diagrams is somewhat controllable) … normally I consider doxygraph pretty “meh” (you get what you pay for and you’re getting the uml for free) but in an open source project like this free documentation is a lot better than no documentation.

Also is there any reason that CMAKE (cross platform make) wouldn’t work with ardunio. With CMAKe you have these very small CMakelists.txt files that cmake turns into Makefile’s to it’s a like a better, more general, easier to maintain version of the configure automake paradigm for Linux.

With CMAKE you also get the ctest harness, and while I haven’t drunk the test driven development kool-aid (largely because tdd omits the design phase from consideration in favor of emergent design) I do see merit in the idea of “test everything” with an automated test suite and ctest is one standardized testing framework.

At work I rely on a Infrastructure wizard to handle all of that for me including lcov code coverage (I do most of my professional code development on linux) and CI, so I can focus on algorithm development, but I probably ought to increase my hands on experience with setting that stuff up (rather than just using it). Or maybe I can get my guy to do the retooling really quick in exchange for taking him and his family out for dinner or something. That’s if there’s even a willingness to switch too a “better” toolset… Are the things I’ve mentioned the community/powers that be would even be interested in?

2

Ask a cross-post question, receive a cross-post answer:

I’m an old-fashioned developer, I use Linux, my editor is emacs and “make” is pretty much all I need for a build system. :)

For ProffieOS, the primary goal is to make it easy for the users to compile and install ProffieOS. That means using an easy-to-install and easy-to-run IDE. Today, that is pretty much Arduino. Arduino also uses it’s own build system and does some weird things with subdirectories, which is why all of ProffieOS is compiled in one single compilation unit. (Everything uses #include<>, there are no actual libraries.) If we used cmake, or any other such tool to build ProffieOS itself, it would be just to invoke the arduino builder, and a shell script / bat file would be simpler for just doing that. I’ve also used cmake on some other projects, and I don’t like it. It’s not really helping much with the cross-platformness, the syntax is really weird and the documentation is terrible.

Arduino doesn’t have any support for tests though. I do however have makefiles that have unit test targets in them. The unit tests are pretty much written in posix-style C++, and should compile on most unix-like platforms. This includes github, and those unit tests compile and run for every checkin on github. They do not currently offer very good coverage, and they cannot test arduino or hardware integration, so there is a lot of limitations there.

Doxygen might be interesting to use, in particular for documenting the style templates. Most of our users don’t really need API level documentation for the code though. Also, I don’t think I have ever seen automatically generated documentation that was actually good, and this includes some stuff I wrote myself a long time ago… (I had to document a language called Pike once, and the automatically generated documentation wasn’t good enough, so I ended up writing a 600-page book instead.)

I’m not sure why anybody would want UML though. It reminds me of BSP, which was the scourge of software development when I was young. Also, ProffieOS goes to great length to avoid using malloc(), which means there are no deep data structures being passed around.

Arduino also doesn’t have any kind of support for generating or using doxygen-generated documentation, so whatever strategy we would use here would need to include an easy path for generating, publishing and hosting the documentation as well.

Ultimately, I think it’s fine if the API-level documentation is in the form of comments in the code.
For non-programmers who are just trying to build a saber though, the documentation should be elsewhere, and doxygen may be a way to bridge that gap, but without figuring out how to combine that information with the information that is currently available on the wiki, it’s not really a complete solution.

3

I should also mention that the code structure for ProffieOS is relatively simple, it’s basically:

Input → Prop class → SaberBase → outputs

So there isn’t that much document.
That said, the comments in the code can always be improved, and the preferred way to do that is that when someone (like you) ask specific questions, I will not just answer the question, but also add comments to the code that answers that question to make it easier for the next person reading the code.

4

You can do a

<a href="put wiki web page address her">link text</a>

in the doxygen comments to link to the pages and host the auto-generated api documentation on the wiki to get integrated documentation, so that you’re not duplicating effort.

The advantage of doxygen over normal comments in code is better organization/display for users (and its prettier than comments in files)

So I would advocate for a doxygen based solution for proffie.

I think I might have started using emacs (eight megabytes and constantly swapping, joke acronym) circa 1996. 5 or 6 years back I switched to sublime because it’s easier and prettier, with plug-ins it’s almost an ide.

The best compiled documentation I’ve seen is asciidoctor. You can essentially get report quality stuff out of it.

Given your comments about not integrating with ardunio, it makes sense not to use cmake as the build harness. But… cmake has gotten a lot cleaner and easier than it used to be over the last several years, so it might (or might not) be worth your time to give it another chance, even if only as a separate build and test harness of everything except integration with ardunio or the board.

Lcov gets me line and function coverage for my work project (color-coded line coverage says what is/isn’t covered so I can target uncovered lines) in most of my projects I’m targeting greater than 95% line coverage. In progress Stuff I’m actually developing typically has mid 70’s to mid 80’s percent coverage.

5

Having a hard time figuring out how to edit my previous post,

Meant to do back ticks and did single quotes for a small code block

You can do a

<a href="wiki web page address">link text</a>

in the doxygen comments to link to the pages and host the auto-generated api documentation on the wiki to get integrated documentation, so that you’re not duplicating effort.

The advantage of doxygen over normal comments in code is better organization/display for users (and its prettier than comments in files)

So I would advocate for a doxygen based solution for proffie.

I think I might have started using emacs (eight megabytes and constantly swapping, joke acronym) circa 1996. 5 or 6 years back I switched to sublime because it’s easier and prettier, with plug-ins it’s almost an ide.

The best compiled documentation I’ve seen is asciidoctor. You can essentially get report quality stuff out of it.

Given your comments about not integrating with ardunio, it makes sense not to use cmake as the build harness. But… cmake has gotten a lot cleaner and easier than it used to be over the last several years, so it might (or might not) be worth your time to give it another chance, even if only as a separate build and test harness of everything except integration with ardunio or the board.

Lcov gets me line and function coverage for my work projects color-coded line coverage says what is/isn’t covered so I can target uncovered lines. in most of my projects I’m targeting greater than 95% line coverage. In progress Stuff I’m actively developing typically has mid 70’s to mid 80’s percent coverage.

​ ​

6

Putting links to the wiki pages in the code can be done just as well without doxygen. The purpose of doxygen (and similar) is to extract the comments and place them in a document outside of the code. But that really only adds benefit if the documented code is a library or interface that the user is expected to use without caring about it’s implementation. Since ProffieOS is single source base, there is generally no such expectation, as most programming tasks in ProffieOS requires changing and updating code on several layers.

Making documentation “pretty” has almost no value IMHO. However, if it means having a way to embed pictures and make tables, that can be useful.

But who do you see actually using this documentation?
ProffieOS has thousands of users, but almost none of them are programmers.
Most ProffieOS users needs step-by-step instructions and videos for how to write a configuration file, not API-level documentation.

That doesn’t mean that we don’t need API-level documentation of course, but for that set of users, which I would currently estimate in the low teens, spending lots of effort is not really worth it. Simpler solutions (like just using comments) might be better because there is less overhead and maintenance.

As for cmake; I used it last month and didn’t like it. It seems like a step down from autoconf+make to me, but lots of new projects use it, so I suffer through it.

lcov integration might be nice, but I wouldn’t expect high coverage numbers, ever. Some of the code would require some sort of Proffieboard emulator to test properly. Ideally whatever code coverage tools we use would also be part of the github test run so that it gets updated automatically whenever new code is checked in.

Sorry if this seems negative; I do think that some of these tools might be useful, but only if integrated in a way that fits with the way ProffieOS works. Complete retooling is not an option, but there is no reason why there can’t be multiple ways to compile ProffieOS. Apart from arduino, you can already compile proffieos with “make” on linux. I also have scripts that let you build ProffieOS from a configuration file online, and PlatformIO might also work, although I haven’t actually tried that.

7

I really hate cmake. I use it all the time, not by choice! I support researchers on a HPC cluster.

I find that ProffieOS is well written, and documentation is enough for most people. It was easily to modify the code, to do what I wanted, without asking anyone questions. I am electrical engineer, so easy for may not be easy for everyone else. However that may not really matter, since most people will not need to modify the code!

The web tools available to generate the cofig files are enough for most users.

1 Like
8

It can always be better though. :slight_smile:

9

Very true!

10

Speaking of Docs. Is Proffie OS documented? I mean beyond the comments. Like a manual of functions.

11

Generally speaking, the answer is no, the comments provide most of the documentation.
For some functionality, there may be wiki pages that are helpful, but those are mostly meant for people writing config files, not for people making modifications to the code directly.

A long time ago I wrote a comment at the beginning of ProffieOS.ino that gave a bit of an overview for how things work. That comment needs a major overhaul though. (And maybe I should transfer it to a wiki pages instead.)

12

Ok. Well I unfortunately write technical docs as a big part of my job so I get how long it would take to produce documentation. Which OS file can I look at to see a list of the different, I’m calling them functions, and maybe get an idea about the syntax. Or maybe just looking at some example profiles would be faster?

13

All of the files that make up proffieOS have functions in them. If you give me a little direction as to what you are trying to do/learn, then I can point out where to start reading.

1 Like