Arduboy minimal library?

Development
#1

Hello Arduboy frens,

I’d like to discuss an idea with you that I became very excited about, but lack the skill (knowledge of low level and Arduboy HW) to make it happen myself without a lot of effort, while someone skilled could bring it to existence in a day.

The idea is a minimal library for Arduboy, in the spirit of Unix and suckless philosophy, to offer extra performance as well as some other things.

@FManga has started this project for Pokitto (see here), but it’s not finished yet and I think there are many improvements still possible (i.e. it can be made more minimal).

What does it mean?

Well, a bare minimum library that’s extremely easy to use, contains only the initialization of HW plus a few functions (setPixel, buttonPressed, writeSound, …), is as small as possible, with minimum memory footprint, minimum compiled size, fast and simple compilation and so on. It should NOT contain things like drawing shapes, rendering text, button management, managing sprites and their formats, managing FPS, main loop etc.

It should be in a single header file if possible, written in C – it should run as C++ (i.e. be a C subset of C++) as well, but for a few functions C is enough and some people (like me) want to simply write in C.

As such a small and simple file it should ideally be public domain under CC0 as to be as simple to use as possible also legally, i.e. simply take it, copy paste it, edit it, hack it, improve it, without having to document the changes or write correct attributions, attach license text etc. Licenses like MIT are of course an option too, but they still have burdening requirements that are maybe appropriate with bigger SW, but not very good for a simple small file with a few functions.

Why?

This library wouldn’t replace the current library. It would only be an additional option for those who could benefit from it, i.e. people who want to optimize, have control, get the best performance out of Arduboy, tailor their functions (like shape rendering) to specifically fit their project, or keep it simple. Most developers would keep using the current library.

It would also be a simple interface that could be implemented on other platforms like native PC, emulators/simulator or browsers, so that the games would be more portable and potentially easier to develop and debug etc.

Anyone who has programmed for Arduboy knows it has very limited HW resources and so every byte counts if you’re trying to create a serious game. The official library offers comfort and safety but sacrifices some performance and control for it. The minimal library would be an option to willingly give up this comfort and get the performance back, save space and CPU cycles and allow complete control and optimization and as a result better games from the skilled people .

I think such a library is even more appropriate for Arduboy than Pokitto, because Arduboy in itself is a symbol of minimalism. It should have this extremely minimal library available.

What do you think? Is there anyone who could do this?

#2

You’d be hard pressed to get better performance from a minimal library. I’ve done a lot of work optimising Arduboy2. That’s assuming you don’t go wild with assembly code, which would go against your goal of portability.

If you can find any bloat or inefficiencies in parts of the Arduboy2 library that would have equivalents in a minimal library, let me know. I may be able to improve them.

As for size; any function that you don’t use doesn’t get compiled into the sketch.

You can do that now. Write your own functions and just use Arduboy2 to initialise the hardware, or when it has a function that does exactly what you want it to.

2 Likes
#3

It seems we have a different definition of what a minimal library should be like.

  • Pokitto and Arduboy, being MCU-based devices, don’t have an OS. As such, it’s up to the games to contain things that are required by players. In the case of Pokitto, making a game that doesn’t allow entering the loader or change the volume is bad usability, despite it not strictly being a technical requirement. In the case of Arduboy, that’d include the bootup logo, flashlight mode, etc.
  • A library, especially a single-header one, should never dictate the organization of the rest of the program. As such, if including the header forces the program to be entirely/mostly in the same compilation unit, then the library is a hindrance, not a feature.

What’s are the burdening requirements of MIT? Basically the license states that it was put there by someone with the authority to do so (the copyright holder) and a “don’t sue me” clause. The only burden, then, is that you agree not to sue the author.

The methods you don’t need in the Aruboy lib will be removed by the compiler. You won’t gain anything from a minimal lib on this platform. Pokitto, on the other hand, has many different ways of doing things (multiple screen modes and image formats, for example) and there are trade-offs to each method. The lib makes it easier to write software that has uncommon constraints, such as the loader or emulators. Generally, it results in software that is less portable, but finely tuned to a specific platform.

2 Likes
#4

I know, still this doesn’t prevent inclusion of all unneeded stuff, see below.

I haven’t look in detail at the code yet (will do), but maybe e.g. these?

  • Start Arduboy logo is unneeded, takes a lot of storage memory and is forced into the program.
  • The button management keeps the button state in order to be able to tell e.g. when exactly a button has been pressed (change of state from up to down). Is this correct? If the game is only interested in whether the button is pressed at given moment, I suppose the class still accesses this state memory so it will take up RAM even though it is be unneeded?
  • I’ve found virtual functions in the code, which means vtables.

And also from a purely statistical point of view, even if you’ve optimized a lot, with such a huge code you’ve probably also missed a lot and even if I can’t find these spots, they’re likely there. On the other hand with a 100 LOC code you’ll be able to optimize much more. Is this correct?

It doesn’t have to be a playable game, it can e.g. be just a helper program for developers that needs all the storage memory you can have, it doesn’t have to have a loader page. It can be there as an option, but shouldn’t be forced, and should be as minimal as possible (no logos, text etc.).

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

#5

That’s why there’s boot() as an alternative to begin(). It’s documented in the Remove boot up features sub-section of the Ways to make more code space available to sketches section of the Arduboy2 library documentation main page.

The state info is kept in 2 bytes of RAM. It’s only used by pollButtons(), justPressed() and justReleased(). If you only use pressed() and notPressed(), no code is generated using the states. RAM space is generally not a limiting factor on the Arduboy.

The only virtual functions are for the text handling and the boot logo. If you use the Arduboy2Base class, instead of Arduboy2, to eliminate the text functions (which I assume wouldn’t be part of a minimal library), and use boot(), instead of begin(), to eliminate the boot logo, then there should be no vtables.

Probably only in the functions that you wouldn’t want to include in a minimal library, so they wouldn’t end up being compiled into your sketch. Define your minimal library then find the equivalent Arduboy2 functions and see if there’s any code there that can be better optimised.

2 Likes
#6

Okay, that sounds reasonable, thank you.

Still I’d like to see this, at least for these reasons:

  • Comparison with the current lib, I’d really like to see it in practice.
  • Licensing.
  • As an elegant non-C++ library that doesn’t need to be linked, that can fit into a comment on forums etc., for minimalists and idealists like myself.

After I’m done with my current project I’ll try to do this.

#7

You’ll want to be aware that the Arduboy name is trademarked and so long as the projects are free and open source then that’s within fair use.

#8

I know but thanks for pointing out :slight_smile: The lib I have in mind wouldn’t display the logo and wouldn’t contain the word anywhere else, not even in its name (could be something like ABminlib or similar), even if it’s possible thanks to fair use. By licensing I meant using CC0 and being completely public domain without any IP restrictions (which implies it can’t contain trademarks).

#9

In all honesty I think you’re probably the only person who actually wants this.

Print can theoretically result in smaller code,
but only if more than one class inheriting from Print is being used,
which is actually an uncommon situation on the Arduboy.
Some programs might use both Arduboy2 and Serial in which case it would (theoretically) be a benefit,
but that’s an edge case rather than a common case.

However, I can think of a number of more appropriate solutions to that problem than ‘introduce an alternative to Arduboy2’.

No, this is not necessarily correct.
The number of lines of code in a source file does not have a direct correlation with the amount of machine code generated.

As FManga points out, C++ only allocates resources for the functions and objects that are actually referenced by the code.
Anything that isn’t referenced isn’t included in the generated .hex.
(“You don’t pay for what you don’t use.”)

I could include a header with 128 images marked to be stored in progmem,
but if I only actually used one of them then only that image would be included in the .hex,
the rest would be discarded.

Unrelated to the actual library:

Code in the sense of source code, object code or machine code is a mass noun, and thus uncountable.
I.e. ‘a code’ is ungrammatical.

1 Like
#10

Sorry @drummyfish, I agree with @pharap on this.

I am also convinced you would have a hard time optimizing any of the Arduboy2 library to make it smaller - thanks @MLXXXp and other contributors - and the included base functions are already done. You can choose not to use the Sprites or sound libraries and the basic graphics functions in the core library are perfect without being over the top.

3 Likes
#11

There is a correlation between LOC and executable size, see e.g. this, page 3.

I think my statement is correct, just as there is a correlation between the amount of code and number of bugs, there is definitely a correlation between amount of code and number of “optimization bugs”. It’s pure probability. Optimization bugs are furthermore more invisible, you can usually only spot them in the source code.

I agree, that’s why I am not suggesting optimizing Arduboy2 library, I am suggesting writing a new library with a design that will allow what’s almost impossible with the current library.

Of course, they’ve done a great work. As I say, the goal is not to replace the current library or even compete with it, the goal is to create a different library for different purpose, offer developers a choice.

I think so, that’s why I’ll have to do it myself as my next project.

But thanks for your opinions anyway, I hope you’ll at least assist me here on forums in case I get stuck on something. I would be really glad.

#12
The data presented in this paper is not generalisable (and may not even be valid anymore) for a number of reasons:
  • This only tests C code, so it’s not necessarily generalisable to other languages
    • Theoretically C++'s template system would have the potential to blow this out of the water because it can cause a lot more machine code to be generated for the amount of source present.
  • It says nothing about the code it was using to derive this data
    • E.g. how much code was tested, whether it was all from the same source
  • It only tests two compilers, one of which doesn’t seem to be in common use anymore
  • The test is 15 years old, both compilers would behave quite differently now
  • Only Windows is mentioned, no other operating systems were tested
  • The architecture in question is not stated (though it can be assumed to be x86) - CPU architecture plays a big role in what can and cannot be optimised

There will always be a correlation between the amount of code and the number of bugs,
but that’s not really a valid argument for claiming that less code is necessarily better or more optimal,
particularly because there are other factors that contribute more to the presence of bugs or the optimality of code.

To name just a few: the expertise of the people involved, the number of people involved, the quality of review systems or lack thereof.

‘Lines of code’ isn’t even well-defined to begin with, simply changing the brace style could skew the recorded ‘number of lines’ by a significant percentage.

What precisely is ‘almost impossible’ with the current library?

Pre-emptive rebuttals:

'I can't put code in the public domain'

That wouldn’t be fixed by replacing the Arduboy2 library, you’d also have to make an alternative Arduino and avr-libc - LGPL and BSD 3-clause, respectfully.

'I can't compile pure C code, I have to use C++'

Again, Arduino uses C++ liberally, so you’d have to do away with that too.

Don’t get me wrong, if your heart’s set on it then by all means go ahead with it,
I’m just struggling to imagine what tangible benefits it could possibly bring,
and it would be disingenuous of me to pretend otherwise.

Of course.

I doubt I'll be of much help for a number of reasons...
  • You’ll be writing it in C, so all my ‘language lawyering’ capability goes more or less out the window
  • The documentation is already exceptional
  • Your mathematical ability probably excels mine

But if there is something I might be able to help with then I’ll certainly try.
(It would take more than a disagreement about the premise to convince me not to.)

2 Likes
#13

Can I ask what the actual goal is here? It honestly just seems like this is an effort to write a compatible library with licensing restrictions you can author.

#14

No, I want the exact opposite, it should be without any license, restriction and owner. It would also be incompatible with the current library.

This is all because I and many other people want to strictly adhere to the suckless philosophy, and think Arduboy is a great place to show it. C++, IDEs, unnecessary dependencies and other bloat are incompatible with this philosophy.

All I want is a choice, but it seems like on these forums I am the only one, so I’ll have to do it myself, but I now see it as an opportunity to learn something new.

#15

At the very least even if you end up being the only person your library is useful to it’ll be a good experience and I’m sure you’ll end up learning quite a bit. Most of my libraries are for specific micros and I’ve never publicly released them, but they were sure fun to write and test!

2 Likes
#16

@drummyfish Good luck, but I agree with everyone else here. You’ll be the only one using it. The community has benefited a lot from the monoculture of a single well loved and supported core library - and will no doubt continue to do so. So if you’re just doing it for fun, or learning, or philosophy, that’s fine - but don’t be disappointed if you’re the only person to ever use your library. :slight_smile:

Sometimes I do imagine a super tight ALL assembly library, but I don’t have the time and it’d be hell to maintain. :slight_smile:

2 Likes