Add constexpr to the refrence and favour them over #define

I have seen many arduino programs with many, many #define constants that should be using c++'s constexpr.

Read here: c++ - Constexpr vs macros - Stack Overflow

There should be a page about how to use constexpr on the arduino refrence, and it should be preferred over #define.

Of course, using #define for pre-processor if statements (#if) is a different thing, and should be allowed.

PORTB:
There should be a page about how to use constexpr on the arduino refrence

Feel free to submit a pull request to add one:

PORTB:
and it should be preferred over #define.

We already recommend the use of const instead of #define:

In general, the const keyword is preferred for defining constants and should be used instead of #define.

So now you need to convince me of why the average Arduino user would be better off using constexpr instead of const as an alternative to #define.

Keep in mind that constexpr is C++11 and the Intel Galileo and Intel Edison are using C++98. Yes, those boards are discontinued, but a lot of people own them and it's extremely unlikely their hardware packages will ever be updated. That's not to say that we can never use C++11 features, but only that there needs to be a good reason for doing so.

I have a vague desire to keep most of recommended arduino constructs within the subset of C++ that is also available in C...

Previously, when I thought that there was no Arduino Language and .ino files were written in C++, my feeling was that the Arduino Language Reference only needed to document the Arduino core library API and some fundamentals of C++ to get people started. Once a user became more experienced with programming, they could simply use one of the excellent C++ references to learn the rest of the language.

Now I've been informed by Arduino that .ino files are not written in C++. They are written in the Arduino Language. The Arduino Language Reference is the only existing documentation of the Arduino Language. I feel that it's essential for a programming language to be documented 100%.

I've been informed by Arduino that .ino files are not written in C++.

If that becomes true in a technical sense, rather than just as some marketing sound-bite, it will be very sad. :frowning:

The Arduino Language Reference is the only existing documentation of the Arduino Language. I feel that it's essential for a programming language to be documented 100%.

And THAT will become a huge task.

I believe, according to my software engineer son, that you program in the IDE in C++ using Arduino defined Libraries, Macros, Functions, etc. that are also written in C++ when desired.

The Reference takes you to those Arduino defined things, and the AVR Gnu compiler that is called behind the scenes
https://gcc.gnu.org/wiki/avr-gcc
will pretty much let you pull in C or C++ as you desire.

westfw:
If that becomes true in a technical sense, rather than just as some marketing sound-bite, it will be very sad. :frowning:

I wouldn't concern yourself about this statement indicating any plans for a technical change. It's simply a philosophical stance. Arduino's official opinion is that the sketch preprocessing done on .ino files justifies calling it a new programming language:

  • Add #include <Arduino.h> to the primary .ino file (if the file doesn't already contain that #include directive.
  • Add function prototypes for any functions in .ino files that don't already have a prototype.

After preprocessing, the sketch is indisputably C++ and is compiled using a standard C++ compiler.
Certainly the sketch preprocessing allows you to write code in .ino files that is not valid C++ (though valid C++ will always work too).

The doubts in my mind:

  • Does sketch preprocessing represent a significant enough difference to justify calling it a new language? I don't know whether there is a formal definition for what makes a new programming language or if it's merely a matter of "it's a new programming language if I say so".
  • Even if it is technically permitted to call it a new language, is doing so beneficial to the users?

westfw:
And THAT will become a huge task.

I agree. Things with the documentation were so much more simple when I thought .ino files were written in C++. Several times over the years, I've responded to suggestions that more advanced documentation be added to the Language Reference by saying something like: "The Arduino Language Reference is not intended to be a complete documentation of C++. Excellent C++ references already exist elsewhere on the Internet so there's no need for us to attempt to duplicate all that content." It sure is great to be able to pass the buck!

On the other hand, the C++ references I mention (e.g. cplusplus.com) have a lot of information that is not relevant to Arduino users and may not be written in quite as beginner friendly a manner as Arduino users have come to expect. So I suppose that a custom tailored complete C++ whoops, Arduino Language reference would be helpful.

CrossRoads:
I believe, according to my software engineer son, that you program in the IDE in C++ using Arduino defined Libraries, Macros, Functions, etc. that are also written in C++ when desired.

This is what I always believed as well, but now that I work for Arduino I'm required to change my mind and do my support and documentation work based on that belief.

pert:

  • Add #include <Arduino.h> to the primary .ino file (if the file doesn't already contain that #include directive.
  • Add function prototypes for any functions in .ino files that don't already have a prototype.

Is that the full extent of the "few subtle differences" that @pnndra refers to on the github thread?

This is one of those category questions which tax people but ultimately probably doesn't make much practical difference. Practically, there is some conversion required to turn a valid Arduino sketch into a valid C++ program, even if it is minimal.

This leads to conversations like:

"My Arduino sketch doesn't compile in my C++ IDE"
"Well, you need to make some changes"
"Oh, I thought Arduino was C++?"
"Well, it is, but not quite..."

Anyway, if the founders think it is a new language then whatever we say will not change what they think. All we can advise is that an Arduino language sketch is very similar to a C++ program, and outline the differences.

There is one other thing I think should be added: If there are multiple .ino files in the sketch folder (shown as tabs in the IDE), concatenate them starting with the file that matches the sketch folder, followed by the rest in alphabetical order. Add the .cpp file extension to the resulting file.

That's it. It really isn't a huge difference. Now, there are a couple other things mentioned in that thread which might appear to some to be additional differences, but they're really not:

Arduino Language has its own data types and functions.

These are declared in Arduino.h so this is covered by the explanation of the preprocessor inserting the #include directive for that file. It's just a C++/C library, no magic. The "own data types" (byte, boolean, word) are just typedefs for C++ types.

necessity to "restrict" user to a init and loop function

@pnndra meant to say setup, not init. C++ programs must have a main() function but Arduino you don't need to have this function in .ino files, which might seem like a significant difference from C++. But this is not a difference at all. C++ allows multiple source files and Arduino's main() just happens to be defined in a separate file. That main() function calls setup and loop:

int main(void)
{
 init();

 initVariant();

#if defined(USBCON)
 USBDevice.attach();
#endif
 
 setup();
    
 for (;;) {
 loop();
 if (serialEventRun) serialEventRun();
 }
        
 return 0;
}

You could define setup() and loop() in a .cpp instead of a .ino file in the sketch if you like. So this is nothing specific to the Arduino programming language, it's just C++ being used exactly as it was intended to be used. You can define your own main() in the .ino file if you don't like the default main() so it's incorrect to say "restrict".

bobcousins:
Anyway, if the founders think it is a new language then whatever we say will not change what they think. All we can advise is that an Arduino language sketch is very similar to a C++ program, and outline the differences.

I think that's a reasonable approach. I realized that I'm no expert in whether those three differences I mentioned are sufficient to claim a new programming language so I have no ground to argue. My interest is in making it as easy as possible for people to learn this programming language, whatever you want to call it. I've been giving a lot of thought about how that can be done. After some good discussion in another thread:
https://forum.arduino.cc/index.php?topic=620437
I submitted an issue report to the repository that contains the Arduino Language Reference content:

I'm hoping to get some input from some people at Arduino on that issue and then start improving the documentation in this respect.

Arduino language is a greatly simplified make language. Make tools such as cmake are too much for beginners. In this sense of make, it is a language.

The ino and h files are pure C++ which allows c. Nothing gets translated or modified in the ino files.000 As mentioned before, an include is inserted for arduino.h. Serial, Serial1, Serial2 & Serial3 are C++ objects which means all ino files must be C++ even when no C++ functionality is used.

As for header files, they are not automatic and you must write #includes. Since the ino files are merged, you can do a single include before setup() and they will apply to all subsequent ino files. The Arduino language only merges ino files and adds include for arduino.h.

You can also have c and cpp files that the Arduino language will compile separate from the ino files. The drawback is you must have the appropriate includes (e.g. try using Serial.print).

Regards, Jon.

I forgot to mention constexpr vs #define. In principle, const or constexpr is preferred. For arduino, it doesn't really matter although #define sets a bad example for noobs. The names used are global regardless of #define or const. As for constexpr vs const, is there a difference for arduino because accessing data in program storage is non-standard (see F( ) macro).

Regards, Jon.

jperryma:
Arduino language is a greatly simplified make language. Make tools such as cmake are too much for beginners. In this sense of make, it is a language.

I'm having trouble understanding what you mean by this, but I'm interested. Could you provide an example of some Arduino language code as it applies to your definition of the Arduino language?

jperryma:
Nothing gets translated or modified in the ino files.000

I think that would be a good thing to mention in my proposed documentation of the difference between Arduino programming language and C++. The sketch preprocessor adds things to the content of the .ino files, but it does not modify the existing code.

jperryma:
The drawback is you must have the appropriate includes

This is because sketch preprocessing is only done on .ino files. The rest are compiled just as you write them using a standard C++/C/Assembly compiler. It's absolutely certain the non-.ino files of the sketch are not written in Arduino language. For this reason, you also have to write your own function prototypes in those files.

Sorry it's taken so long but I tried replying several times without success.

I was wrong about build generating the function prototypes being generated. Since it didn't handle moving my class headers, it was not doing the function prototypes.

The build process is clearly documented at Build Process · arduino/Arduino Wiki · GitHub. It merges the files, adds function prototypes for functions declared in the INO files and add the include for arduino.h.

Make is a language that programmers use to compile their programs. Arduino has changed this process so that the user only specifies the board. The make language has been reworked so that the board manufactures and arduino ide has created the required make information for the user.

This is real C++.

It is legal to call this Arduino language even though they didn't make any changes to the the language. Common examples would be Android and Ubuntu are actually Linux. In fact, there are several Linux distributions that don't state they are Linux.

I think it's a good idea that this is called Arduino language because beginners are still missing several key concepts.

Regards, Jon.

jperryma:
The build process is clearly documented at Build Process · arduino/Arduino Wiki · GitHub. It merges the files, adds function prototypes for functions declared in the INO files and add the include for arduino.h.

Yes, that's great documentation, but that information is not very accessible to someone trying to learn about the Arduino programming language.

jperryma:
Make is a language that programmers use to compile their programs. Arduino has changed this process so that the user only specifies the board. The make language has been reworked so that the board manufactures and arduino ide has created the required make information for the user.

I'm well aware of what the make language is. What I don't understand is what that has to do with the Arduino programming language. The only thing I can think of is that your opinion is that boards.txt, programmers.txt, and platform.txt are written in the Arduino programming language, rather than the code in the .ino files. Is that what you're saying?

I don't think it's accurate to say "the make language has been reworked", since Arduino never started with the make language to begin with. Sure they have a build system, but it's not based on make.

jperryma:
I think it's a good idea that this is called Arduino language because beginners are still missing several key concepts.

I don't understand what you mean by that. Please explain further.

great documentation, but that information is not very accessible to someone trying to learn about the Arduino programming language.

My perspective is that Arduino should remain simple so beginners won't get overwhelmed. As more advanced discussions occur, web searches will be difficult to determine the relevance.

I'm well aware of what the make language is. What I don't understand is what that has to do with the Arduino programming language.

#include arduino.h is standard C. Arduino programmers can easily combine files and create function prototypes. The only uniqueness comes with the build process. We were discussing what is the uniqueness of the Arduino language. Maybe the only justification is to search for Arduino versus C++.

I think it's a good idea that this is called Arduino language

For beginners, searching on "Arduino" returns far more useful results than C or C++.

Regards, Jon.

My perspective is that it's essential to provide a gentle learning curve for beginners while also allowing users to to progress as far as they want rather than hitting some point where they grow out of Arduino. It is possible to do both. The language reference currently does a great job of the former, but a horrible job of the latter. The novice will quickly reach the point where they need more from the Arduino programming language, but there is no bridge between the beginner friendly basics of the language we already have and all the incredibly useful features of the language we don't document. The user must get lucky enough to stumble over the information that the entire C++ language is available to them on a random post buried among the millions on this forum or an obscure, non-obvious wiki page on Github. In the other thread where we discussed this, we had someone who had been using Arduino for 4 years and just happened to learn by chance that they could use templates in the Arduino programming language. I don't think that's an acceptable situation.

jperryma:
#include arduino.h

The file is named Arduino.h.

jperryma:
For beginners, searching on "Arduino" returns far more useful results than C or C++.

This discussion isn't about beginners. This is about the more advanced users. They matter too.

Is there a standard mechanism for setting up a .h file so that C++ gets to use constexpr, and plain C gets the closest equivalent that is still plain C? Significant parts of Arduino SW are still written in C...

pert:
My perspective is that it's essential to provide a gentle learning curve for beginners ... The language reference currently does a great job

The language reference is terrible at teaching the Arduino language. If you understand C, then it's a great way to get up to speed. To learn C, there are tutorial sites and youtube videos that are more suitable.

pert:
The novice will quickly reach the point where they need more from the Arduino programming language, ...
In the other thread where we discussed this, we had someone who had been using Arduino for 4 years and just happened to learn by chance that they could use templates in the Arduino programming language. I don't think that's an acceptable situation.

4 years and they never realized this was C++. That's sad but they were at fault.

Documenting constexpr and templates in the Arduino reference is a terrible idea. The Arduino reference is already too large for beginners. Discussing these in the Arduino forums will never do them justice. They are C++ features that are regularly discussed in the C++ forums and often very in great detail. If you truly want to extend your C++ knowledge, you will learn much more there.

Discussing the basics here is fine but people need to learn there are additional resources that can be far more useful.

pert:
This discussion isn't about beginners. This is about the more advanced users. They matter too.

I agree but they can easily learn about advanced features (e.g. templates) in the C++ forums. In fact, they will get exposure to several features that go unnoticed here. If discussed here, it becomes difficult to find important information that is unique to Arduino for those features.

pert:
The file is named Arduino.h.

Sorry, my bad. I'm accustomed to lower case header file names.

Regards, Jon.

westfw:
Is there a standard mechanism for setting up a .h file so that C++ gets to use constexpr, and plain C gets the closest equivalent that is still plain C? Significant parts of Arduino SW are still written in C...

As far as I can tell, everything is compiled using C++. Is there a situation where constexpr is getting an error in the plain C code?

Regards, Jon.

jperryma:
4 years and they never realized this was C++. That's sad but they were at fault.

How are they expected to learn that when it's not mentioned in the documentation?

jperryma:
Documenting constexpr and templates in the Arduino reference is a terrible idea. The Arduino reference is already too large for beginners. Discussing these in the Arduino forums will never do them justice. They are C++ features that are regularly discussed in the C++ forums and often very in great detail. If you truly want to extend your C++ knowledge, you will learn much more there.

If you look at my proposals, the first one is to provide a link to a place where people can learn about C++, rather than fully documenting the language in the Arduino Language Reference.

You'll also see that in my second proposal to document the entire language I say "we would need to have some way of separating the advanced topics that beginners should not be immediately exposed to from the rest".

jperryma:
Discussing the basics here is fine but people need to learn there are additional resources that can be far more useful.

And that's something that is not done at all in Arduino's documentation currently. You won't find any further documentation of the Arduino programming language anywhere else. So it's very easy to come to the conclusion that what is in the Arduino Language Reference is the entire language. We need to somehow provide documentation for the entirety of the language.

jperryma:
it becomes difficult to find important information that is unique to Arduino for those features.

Anything on the Forum is extremely difficult to find because the Forum is a huge disorganized mess. We should not count on information in the forum as documentation. This "information unique to Arduino for those features" is the benefit of my second proposal of documenting the entire language. Currently, we have no official place to document this sort of information so people must be lucky enough to stumble across it in some obscure forum thread or bug ticket.