How to avoid odd naming rules for Arduino when writing a library?

Question

I'm building a small library that will be used and production and released open source. I'm paying a lot of attention to the "best practices" to make sure this code is reliable and easy to use. I also would also like to make this easy to edit. I'm having an issue with the naming scheme of the whole project.

There are a few Arduino naming quirks. If I have a sketch called mylib:

• ...I can't create a tab called mylib.cpp. However, I can create a file called mylib.h...
• ...The folder and main sketch file must be the same name as the folder it is in
• ...The sketch name (and folder) cannot contain any spaces.

Well, why are you creating a sketch for a library? The Arduino IDE won't open a .cpp file unless there's a sketch in that folder (and you have to open the .ino/.pde file in that folder). I'm trying to get this to work with the Arduino IDE so, if users need to edit the library, then can just open the file and go to the correct tab. If they use an external editor, they won't be able to compile it to see if there are any errors.

I'd ideally just do this structure:

my_lib
   |- my_lib.ino
   |- mylib.cpp
   |- mylib.h

However, a user might see that the folder is called my_lib and try including the file my_lib.h.

I think this is a major oversight in the Arduino IDE, but I need to have this work with the Arduino IDE. If it was just me working on this code, I might consider making the library directly in a project directory, but that isn't ideal. Is there anything that I can do to bypass this/make it easy for users to edit? Is there any "standard"/"convention" that defines how to do this?

Answer 1

Yep, the Arduino IDE kinda sucks eventually. There is no best practise really, as Arduino *.ino files aren't proper c / c++ anyway. I would hope that people who know how to write C++ classes (as opposed to Arduino) would be able to do it outside the IDE.

My suggestion would be to make the *.ino file a test file. That is, it runs a set of functions to check that the library behaves as desired. It could also include example code, so people who use the library know how to include it in their programs.

All that being said, time to fly Penguin... Ditch the Arduino IDE and go with embedXcode or some other third party IDE template :P

(I just wanted to put a pic of a penguin)

Answer 2

For anyone curious what I did, I ended up doing a naming convention like this:

my_lib_v1_2
   |- my_lib_v1_2.ino
   |- mylib.cpp
   |- mylib.h

Then, the user could include mylib.h still, and people with the Arduino IDE could edit it.

Answer 3

The Arduino IDE's restriction of not allowing you to create a .cpp tab with the same name as the sketch has been removed since the 1.6.12 release.

In fact, older IDE versions would happily open and save sketches that contained, e.g., mylib.ino and mylib.cpp. You just needed to create the .cpp file outside of the Arduino IDE.

The reason for this restriction in previous IDE versions was that the file in the temporary build folder generated from the preprocessed sketch was named {build.project_name}.cpp, which would be overwritten by the other .cpp "tab" file of the same name. Of course that is not an issue for your desired usage of the Arduino IDE simply to edit library source files. Later, the Arduino developers changed to the much more sensible system of naming the preprocessed file {build.project_name}.ino.cpp. Thus the restriction was no longer necessary.