Add constexpr to the refrence and favour them over #define

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.

pert:
You won't find any further documentation of the Arduino programming language anywhere else.

Actually, it's at the bottom of the first page.

Looking for something else?

See the libraries page for interfacing with particular types of hardware. Try the list of community-contributed code. The Arduino language is based on C/C++. It links against AVR Libc and allows the use of any of its functions; see its user manual for details.

It tells you specifically to look at C and C++. It would be easier to recommend rewording for this section instead of asking for a large amount of documentation that must be maintained.

pert:
Anything on the Forum is extremely difficult to find because the Forum is a huge disorganized mess.

I personally like stack overflow because users rate the value of answers, supports tags, allows user changes and comments. Maybe you can talking them into moving to a better forum.

Regards, Jon.

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?

files with the .c extension are compiled as C, rather than C++. So, for example, if I change the definition of HIGH in Arduino.h to use constexpr, I get:

/Applications/Arduino-1.8.7.app/Contents/Java/portable/packages/arduino/tools/avr-gcc/5.4.0-atmel3.6.1-arduino2/bin/avr-gcc -c -g -Os -Wall -Wextra -std=gnu11 -ffunction-sections -fdata-sections -MMD -flto -fno-fat-lto-objects -mmcu=atmega328p -DF_CPU=16000000L -DARDUINO=10807 -DARDUINO_AVR_UNO -DARDUINO_ARCH_AVR -I/Applications/Arduino-1.8.7.app/Contents/Java/hardware/arduino/avr/cores/arduino -I/Applications/Arduino-1.8.7.app/Contents/Java/hardware/arduino/avr/variants/standard /Applications/Arduino-1.8.7.app/Contents/Java/hardware/arduino/avr/cores/arduino/wiring_pulse.c -o /tmp/ArduBuild/core/wiring_pulse.c.o
In file included from /Applications/Arduino-1.8.7.app/Contents/Java/hardware/arduino/avr/cores/arduino/wiring_private.h:31:0,
                 from /Applications/Arduino-1.8.7.app/Contents/Java/hardware/arduino/avr/cores/arduino/wiring.c:23:
/Applications/Arduino-1.8.7.app/Contents/Java/hardware/arduino/avr/cores/arduino/Arduino.h:41:11: error: expected '=', ',', ';', 'asm' or '__attribute__' before 'int'
 constexpr int HIGH = 0x1;

User code is also permitted to be C...

jperryma:
Actually, it's at the bottom of the first page.

Please post a link to where you found that. I can't find it anywhere. I know the old version of the Arduino Language Reference did have some additional text like that, and there is an old version of that which is still online only by accident:

but that page doesn't contain the same text you posted.

jperryma:
I personally like stack overflow because users rate the value of answers, supports tags, allows user changes and comments. Maybe you can talking them into moving to a better forum.

I also like Stack Exchange a lot, though the moderation of Arduino Stack Exchange is a big struggle due to most people who submit questions not bothering to take the time to understand how to use Stack Exchange. However, Stack Exchange and the Arduino Forum serve two separate purposes. This forum it works well enough for the purpose it's intended to serve. The forum is not suitable for documentation, but it was never intended to be used for that.

pert:
Please post a link to where you found that. I can't find it anywhere. I know the old version of the Arduino Language Reference did have some additional text like that, and there is an old version of that which is still online only by accident:

Apparently the online reference has been reorganized but the information is still there.

STRUCTURE

The elements of Arduino (C++) code.

While this is not the best way to document this, they are certainly trying by reorganizing the reference. There's a link on the page for recommending documentation changes. Maybe that would be a good location to make recommendations. I would suggest you limit the suggestions to focus on beginners to make this acceptable.

Regards, Jon.

jperryma:
Apparently the online reference has been reorganized but the information is still there.

Only still there in an obscure orphan page that will be deleted as soon as someone from the website team gets the time. In the real Arduino Language Reference, the information is certainly not still there:

jperryma:
While this is not the best way to document this

The lead technical writer at Arduino has this to say about that text:

I will investigate why we have this "The elements of Arduino (C++) code." sentence that is not how it should be.

My understanding is that it's their intent to remove the "(C++)" from that text.

jperryma:
they are certainly trying by reorganizing the reference.

There was no reorganization of the reference. What happened is a few years ago Arduino created an awesome new system where the content of the Arduino Language Reference is stored in a GitHub repository as asciidoc files so that anyone can contribute to it by submitting pull requests to that repository. The Arduino Language Reference web pages are automatically generated from that content. It wasn't a reorganization, it was just a change in the way the content is published. During that change, some of the text was removed from the home page, but the structure and content of all the other pages in the Language Reference were left as they were.

I fail to understand how you can interpret the removal of the sentence "The Arduino language is based on C/C++" from the reference home page as "trying".

jperryma:
There's a link on the page for recommending documentation changes. Maybe that would be a good location to make recommendations.

I'm well aware of this. I'm the top contributor to the arduino/reference-en repository and the lead maintainer of the project. But I'm glad you brought it up because I would love to see more of the Arduino community take advantage of this excellent opportunity to collaborate on such important documentation. There is a tutorial here:

jperryma:
I would suggest you limit the suggestions to focus on beginners to make this acceptable.

This is the sole documentation of the Arduino programming language. It needs to provide for the needs of all users, not only beginners. Making things beginner friendly is essential, but the goal is to help people eventually progress beyond the beginner stage. Too often in technical subjects I see these knowledge gaps that can be such a huge barrier. I think the attitude people have is "someone will tell you about that". That someone would traditionally be a professor, mentor, or coworker. But the people who are teaching themselves these subjects often don't have access to the gatekeepers who judge whether they're worthy of receiving the secret knowledge that allows them to move to the next level. Maybe they'll be able to sort through mountains of garbage on Google until they find that information buried in some random comment thread, maybe they won't. The only purpose of a system like that is to prevent anyone outside the inner circle of universities and industry from gaining proficiency. Arduino is about freeing the knowledge to make this stuff accessible to everyone. That means providing proper documentation.

you could argue the C is not a language, but a simplification of assembly. you can still use assembly in C. and C++ builds on C. you can use C and assembly in C++. the reference of C doesn't contain reference of assembly

Juraj:
you could argue the C is not a language, but a simplification of assembly.

You could argue that, but everyone would laugh at you because it's clearly wrong.

Juraj:
you can still use assembly in C

I really don't consider inline assembly in C to be a valid analogy for the situation with Arduino programming language and C++. C and C++ is much closer. You can consider C to be a subset of C++, just as you can consider C++ to be a subset of Arduino programming language.

Juraj:
the reference of C doesn't contain reference of assembly

It will contain documentation of asm(). But as I said already, I reject that analogy. Lets move on to your better analogy of C++ and C, which you conveniently didn't mention in this statement. Any good C++ reference will document the parts of C++ that are shared with C.

pert:
You could argue that, but everyone would laugh at you because it's clearly wrong.
I really don't consider inline assembly in C to be a valid analogy for the situation with Arduino programming language and C++. C and C++ is much closer. You can consider C to be a subset of C++, just as you can consider C++ to be a subset of Arduino programming language.
It will contain documentation of asm(). But as I said already, I reject that analogy. Lets move on to your better analogy of C++ and C, which you conveniently didn't mention in this statement. Any good C++ reference will document the parts of C++ that are shared with C.

gcc first generates assembly and then compiles it to machine code

The "assembly" produced or includable in C is not standardized, and is thus not a "subset" of C in any way.
(whereas C is a standardized subset of C++ (except for divergence), and C++ is a standardized subset of Arduino (if you consider Arduino a separate lanaguage.))

Not all C compilers generate asm on the way to machine code, BTW. I've used at least one where they'd skip that step unless it was "necessitate" by, say, using inline asm in the C code. Which resulted in some very mysterious bugs when the assembler didn't support the same data types as the compiler :slight_smile: