Consider lifting limitation that primary ino file must be named after directory

[matthijskooijman]

Bug Report

Currently, the Arduino tools (including arduino-cli) require that a sketch, which is a directory containing one or more .ino files and optionally additional files, includes a "primary" .ino file which shares the same name as the directory it is in.

This requirement has surprised users in the past, judging from various bug reports and questions over the years.

In the discussions of one such issues (arduino/Arduino#10755), the thought occurred that this requirement could maybe be lifted, in a mostly backward compatible way. A sketch would still need to be a directory (so this is not about compiling single .ino files), but it would no longer need to contain a .ino file named after the directory.

Currently, the primary .ino file is (AFAIK) only relevant when deciding the order in which .ino files are merged into a single .cpp file. This ordering is:

1. The primary .ino file
2. All other .ino files, sorted alphabetically

Now, if no primary .ino file is present, one could just skip point 1. This means that any sketch that is currently valid will still be valid and compiled in the same way, you just add more flexibility in defining a sketch.

There is one problem here: If you have a sketch with a primary file, then rename the sketch directory, then the primary file will likely become non-existent, changing the order of compilation and possibly breaking the build. In the current situation, such a rename will cause the tooling to reject the sketch with an error, rather than potentially breaking the build, which can be considered better. Note that a related problem already exists currently: If you rename the directory to the same name as a secondary .ino file, the sketch is still valid but might fail to build as well. This is of course a smaller chance.

One alternative approach would be to introduce a special filename, say "Main.ino" (or maybe "Sketch.ino" or "Primary.ino") and use either that file, or the .ino file named after the directory as the primary file. This leaves two further choices:

• If both Main.ino and a file named after the directory is present, which one to prefer. Using Main.ino is makes sketches that contain it completely robust against directory renames, but also has a small compatibility problem for existing sketches that contain a Main.ino.
• If neither are present, should the sketch still be valid? If not, then sketches not containing Main.ino are more robust against renames, if they are valid, you have more flexibility in naming your files.

Personally, I like the "Main.ino" approach, together with "Prefer Main.ino over directory-named .ino" and "Require either Main.ino or directory-named .ino". Using a Main.ino file could also become the default/recommended structure for sketches (maybe after some transition period), with a fallback for directory-named .ino files kept, of course.

This approach still poses limitations on sketch names, but I suspect that "You need a main.ino file" would be easier to grasp than "The main file must be named after the directory". It also is a lot more reliable when renaming sketch directories, and easier, since you can just rename the directory, without also having to rename the .ino file.

[matthijskooijman]

If this is indeed implemented, this should be implemented in all Arduino tools, of course.

[drstevenhale]

Issue #765 is relevant to this problem.

I like the idea of a default main.ino file. If one of the aims of the arduino-cli is to simplify connection with "professional" tool chains, then I'd like to see support for those of us not using .ino files at all. It used to be possible to specify which file to compile, but that doesn't work since v0.11.

Having played around with this some more, I can see that if I have a file structure such as

src/
--- src.ino
--- main.cpp

where src.ino is just a blank file, then everything compiles just fine. It's a bit messy having to have the placeholder default file for the "src" sketch, where as I used to be able to specify main.cpp directly, but it's not a huge issue.

Still, it would be nice to have a default file, possibly configurable via the arduino-cli.yaml file, or simply able to be specified on the command line like it used to be prior to v0.11.

[matthijskooijman]

then I'd like to see support for those of us not using .ino files at all

At first glance, I like this idea. However, it has a significant risk of making it more ambiguous what is an Arduino sketch. If we start accepting directories without .ino files, then people will start using them and distributing them as well. When a novice Arduino user finds such a sketch, they will no longer be able to open it by double-clicking a .ino file inside the sketch directory, or even recognize it as an Arduino sketch. One could still modify the Arduino IDE to allow opening such sketches through file -> open, but that means that essentially any directory can be an Arduino Sketch, so that opens more possibilities for novice users to accidentally open up the wrong directory (e.g. the sketchbook dir rather than the sketch dir) and get treated by a ton of compilation failures, rather than a clear messages that says the selected directory is not a valid sketch.

Still, it would be nice to have a default file, possibly configurable via the arduino-cli.yaml file,

I think you're saying that the name of the main.ino file could maybe be configurable? That has pretty much the same issue: If you allow this then what is a valid sketch on one system is considered an invalid sketch on another system, which I think we should try to avoid. So if a "main.ino"-style default filename is added, I'd be inclined to make it non-configurable for consistency.

[drstevenhale]

I guess the issue is that Arduino was intended for a beginner audience, and has done such a great job that it's become used in more professional environments purely because the compilation tool chain is so convenient. I'd like to think we could trust developers to write towards their target audience. If the intention is sharing something useful for beginners then it would use the .ino structure, whilst something more sophisticated that quite possibly wouldn't be accessible to beginners in any case, could use a more standard file structure, for want of a better phrase. I do see your point that it could get confusing. For me at least, I'm happy with the workaround of including a blank .ino file and this becomes a non-issue.

I think changing the primary .ino name is a good idea, purely for the benefits and being able to change directory name without breaking everything. My vote goes for main.ino, with a search order of directory.ino first for compatibility even if both names are present. Possibly with a deprecation warning, and changing the search order to main.ino first at a later date?

[paschlie]

I'd even suggest considering the .ino file as the project file, which maintains whatever metadata is required for the project; and properly name the source files using .cpp / .h suffixes as appropriate (possibly arduino.cpp, as main.cpp implies it should contain the function main(), or main.cpp if meant to do so). So the resulting directory structure for a project may become:

SomeProjectDirectoryName: (as desired, no restrictions)

• myProject.ino (as desired for name of project/executable)
• arduino.cpp (which should #include <arduino.h>, or main.cpp if implementing main() & including whatever)
• something.h (as may be desired ...)
• something.cpp (as may be desired ...)

[per1234]

Previous discussion: arduino/Arduino#7543

[a7hybnj2]

Couldn't in the case of arduino-cli the main file be indicated with a -flag. Or in the arduino ide it could be in preferences or maybe a info.txt file. I don't like the idea or forcing the filename to "main" or "arduino" or whatever the other suggestions has been since you might as well keep the current functionality if your going to require a specific file name.

Alternatively it would be very easy to find the .ino file that had the setup and loop functions.

[matthijskooijman]

Couldn't in the case of arduino-cli the main file be indicated with a -flag. Or in the arduino ide it could be in preferences or maybe a info.txt file.

That is an option, but also means that sketches become non-portable. If I have it configured to use "Main.ino" and you have "Sketch.ino", then if I send my sketch over to you, it might not compile properly. Of course I could tell you to use "Main.ino", but that would require extra information to be remembered alongside each sketch, and cause you to change the preference based on the sketch you want to compile, neither of which I would consider acceptable.

I don't like the idea or forcing the filename to "main" or "arduino" or whatever the other suggestions has been since you might as well keep the current functionality if your going to require a specific file name.

This a valid point, but not entirely true: Using a fixed filename allows renaming the directory without consequences, unlike the current "same as directory" requirement, which breaks the sketch when (just) the directory is renamed. So that would be the gain in this case.

Alternatively it would be very easy to find the .ino file that had the setup and loop functions.

I really not want to do more preprocessing and source inspection than we already do, since reliably parsing source is not actually easy and has lead to significant problems already (consider multiple loop functions in multiple files switched by #ifdef guards, or loop in one file setup in another, etc.). Also, this would possibly make things even trickier for third-party tools.

[matthijskooijman]

I just realized one other implementation for this: For sketches with a single .ino file, allow any name, regardless of the directory name. For sketches with multiple .ino files, apply the current requirement that one of them must be named after the directory.

[adamkdean]

Has there been any update on this @matthijskooijman? Seems to me like a very arbitrary restriction. Sure, there are a lot of beginners using arduinos, but there are also many seasoned professionals who just enjoy using various arduino-compatible boards for fun. This, however, is a frustrating limitation when trying to keep projects tidy.

In almost every other setting where a path is presented to a cli tool, passing a filename directly would override any assumed entry point or default file. Passing in a directory would usually assume some sort of default. I understand that it will make sketches less portable, but consider that not every sketch is going to be ported to others.