A word on Arduino/PlatformIO compatibility

[codekrolik2]

Hello flatcc team.
First and foremost, let me express my utmost gratitude to all of you for building and maintaining such a great project.
I struggled a lot with Google's official C++ codegen and it just didn't work fully for me. Moreover, it introduced some nonsense related to root objects, which shouldn't be there, but most importantly, it wouldn't serialize and deserialize FlatBuf objects as expected (at least on PlatfromIO/RP2040).

So I was super-happy to find flatcc and migrated immediately. Predictably, the reader worked immediately and out of the box. And as much is denoted in your documentation:

Arduino (at least reading buffers)

Yesterday night, however, I stumbled upon the following parts of the docs:

Building a Buffer - Note that the runtime library is required for building buffers, but not for reading them.
Generated Files - The reader does no rely on any library but all other generated files rely on the libflatccrt.a runtime library.
Trouble Shooting - Make sure to link with libflatccrt (rt for runtime) and not libflatcc (the schema compiler), otherwise the builder will not be available.

And only later I found the following information in a rather unlikely section:

Unix Files - In addition the runtime library source files may be used instead of libflatccrt.a

Significantly, before finding that last bit of information, I sort of "rediscovered" the same approach by trial and error and ended up doing just that to add builder support to my PlatformIO project, which so far worked flawlessly and without a single issue.
Given that experience, I'd like to provide a bit of feedback, all of which is IMO.

1. Messing with binaries at the age of "everything is code" doesn't look great.
2. While your docs contain a phrase (very hard to find) that the binary lib can be replaced by the code itself, but (IMO) that's worth mentioning whenever binary lib is mentioned.
3. Ideally, the generated code shold be self-contained and portable. In an ideal world I'd like to just add the generated files to the project, and not think of anything else, i.e. the generated files themselves would contain all the needed code (like in Java version of FlatBuf). That would make the setup super simple and migrating to new versions a bliss. I understand it's much easier said than done, but that comes directly from comparing my Java and C experience (in my case the same FlatBuf schema is shared between the two).

And lastly, since builder worked for me on Arduino, the following line in your docs can be updated:

Arduino (reading buffers; builder - use library source files instead of libflatccrt.a)

Here's my proof-commit: flower-org/phraser@2ba30cb
Apologies for the emotional comment there.

And huge thanks to all the flatcc team again, you're doing an amazing job!

[codekrolik2]

Clarification: Java is actually using a binary library, too
implementation 'com.google.flatbuffers:flatbuffers-java:24.3.25'
but since it's being auto-linked via single line in Maven/Gradle config, it still counts like everything is code, I guess.
At least the dev experience is seamless and cross-platform.
I suppose what I meant was that it would be great to achieve the same ease of use and portability across platforms with flatcc.

[mikkelfj]

Thank you for the kind words and heads up on Arduino - I will update that doc section.

Yes I agree that building just from source should be more directly accessible. It is an important aspect. I is just difficult to keep all the important information first in the document, so some things have migrated downwards over time.

I think the C++ team is doing a great job, but they target modern C++, not every conceivable compilation target, which is a key difference between flatc and flatcc. If you are aware of actual issues in C++ that are not merely platform support related, I think you should make a bug report.

I cannot commit to a major overhaul of the doc. I have updated it whenever users have had issues, and this seems to work, since I hear about many of the usability issues that appeared more frequently earlier on.

If anyone are up for reworking the doc with materials for mkdocs, and test the code examples in the builder (which are not 100% correct in all cases), that would be a great contribution.

As for everything is code: I'm not sure about that. I think everything should be easily compilable from source, but not like GB+ javascript libraries.

As you have discovered, essentially all languages have a library part. But to be fair to FlatCC, the common files are an attempt to generate as much as is reasonable so the core library routines essentially never change.

Flatbuffers for C++ has the advantage of C (at least used to) that it can have read-only in a single template based header file. This does not work for C because:

• there is a limit to how much you want to be static inline vs shared compiled code on small targets,
• the macro magic needs to be distinct (common files) to make the schema specific code small and readable
• C uses a schema file to generated file family approaches, suitable for large incremental compilation
• C has a reasonable expansive portable include sub library to support most any platform

Especially the requirement for the include/flatcc directory can be annoying. It is low overhead once compiled, but it is necessary to deal the many platforms out there, which C++ does not handle as well. The single builder .c file is actually pretty trivial in comparison since you can just add it to your project (if you know about).

Overall, FlatCC is really pushing the C language to its limits when trying to support generic generated code without exploding the generated output.

[mikkelfj]

I added

https://github.com/dvidelabs/flatcc?tab=readme-ov-file#integrating-flatcc

And removed the at least reader part for the Arduino mention.