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?

• Ignacio Vazquez-Abrams: I'm currently trying to spin the thoughts going through my head into something not quite so negative (about the Arduino IDE), but... nothing doing.
• Anonymous Penguin: @Ignacio after a few things like this, I couldn't agree more. I'm really confused why it does this...
• user588: Usually you would not expect a user to be editing library code.
• user2973: Why not just have them edit the library in an external editor? If they want to compile, they just open the example you include with the library inside Arduino IDE and press verify. Alt-tab back and forth, I use that a lot.
• Anonymous Penguin: @user2973 but how would you open the .cpp file in the first place to see if it compiles? You can't, and the command line isn't ideal (even if it supports compilation from non .ino files)

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

enter image description here

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

• Anonymous Penguin: +1 for that penguin :) Anyway, I still need the compile with the Arduino IDE, so I don't know if a third party IDE would really work...
• geometrikal: I forgot to add i'm in the same situation - writing code that others might have to maintain using the Arduino IDE. I never thought to including an ino file in there, so thanks for the question.
• Anonymous Penguin: ...well thanks for the penguin! :) Anyway, there doesn't seem to be an ideal situation. I think I'm going to use the naming rule [in my answer] for my main GitHub code and then just rename and move the .ino` file to an "examples" folder when making a release... that way users can get the best of both worlds.
• Pharap: @AnonymousPenguin I know I'm late to the party (as usual) but there's a setting on the Arduino IDE called 'use external editor' that blocks you from editing in the IDE and lets you use an external program (e.g. notepad++) to edit your code, and then you just use the IDE for compiling and uploading. Also creating the .cpp in the directory it's supposed to be in works too if you reboot the IDE afterwards. (These are the sorts of terrible problems you get when you target a tool for programming circuits at non-programmers.)

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.