Compiling and Debugging

What happens when you upload a new program to a connected Arduino?

The first thing that happens is that the code is tested for detectable errors. The syntax must be correct and the appropriate data types used where the compiler thinks that is significant. Essentially, the code must be valid C and C++.

If your program uses multiple tabs then these are assessed. Those with .c or .cpp as extensions to the related file name are compiled separately but any tabs with file names that lack an extension have their content appended to the contents of the main .ino code file for the program. Tabs with an “.h” file extension are selectively applied where an include statement makes their content required.

A collection of library header files (such as Arduino.h) are automatically included into your main program to make available the Arduino and generic C core functions and definitions. The IDE then seeks out all function definitions and creates and inserts prototypes for them into the code. (You may recall that the programmer has to insert prototypes for functions definitions with default arguments but all others are automated for you).

The process then appends the contents of one of the pre-defined “hardware” files supplying support for the specific Arduino that is the current program target.

The main program code together with all additions is then compiled using the C++ compiler. Similarly, any C or C++ code tabs are also compiled and all of the compilations stored in a single (temporary) file folder. The file format is known as “object code” and the file extension is .o

The object code files are then linked together and with any external library references prior to generating a hex format code file that is uploaded to the Arduino. The hex encoded compiled program is received by the Arduino bootloader and, when loaded, verified. If all is well, the Arduino board re-sets and program execution starts.

Debugging

What should you do if the IDE reports errors and the compile fails?

The short error message displayed towards the bottom of the IDE window might make the error immediately obvious. A missing semicolon at a line end, a mistyped keyword or variable should be quickly resolved as the IDE will also highlight the error line. In some instances, the highlighted line in the code window may follow the actual mistake as the syntax error may not have become obvious to the compiler until the start of the next statement.

If the error is not immediately obvious, the next step is to click the button that pops up marked “Copy error messages” (note the plural – there might be more than one bug to fix).

After clicking the button, you can paste the full text of the error messages into something like notepad (on Windows) or any other available text editor.

The full error message should help you home in on most errors. I would suggest you resist the advice towards the bottom of the full message suggesting that you "Show verbose output during compilation". You can give it a try of course but in all likelihood the volume of output will just make your debugging more difficult. If “verbose output” is unlikely to help then where do you turn next if you can’t figure out the problem?

The next step is often to start commenting out lines in the code until the error goes away. You don’t have to keep trying to upload the program to your Arduino during this stage as you can use the “Verify” button (with a check mark) of the IDE to re-check your code after making a change. You have to be selective at this stage as there is a risk that commenting out a particular code statement will generate a whole new raft of errors. Removing a variable declaration, for instance, would usually have this result while failing to advance your bug search unless you also comment out all statements addressing that variable.

Hopefully, you have either resolved the bug or at least identified the line in error. If you can’t relate the error message to the line of code identified with the bug then it is probably time to run an Internet search. If you copy the most significant words in the error message and then paste them into your search engine of choice then there is every likelihood that there will be more than one result that looks like it relates to the same issue.

Search results from StackOverflow can be particularly helpful although there is an assumption that most users of that site have better than a bare minimum of programming skills. It is always worth scrolling down any sequence of “answers” to a particular issue. Sometimes the most helpful (or most complete) answer is languishing at the bottom having being contributed after any initial rush of interest in a question.

If an Internet search does not find you an answer (or maybe does not find you one that seems entirely understandable) then you might try the Arduino “on-line” forum and raise the issue there. I have asked a couple of very naïve questions there and received truly helpful and courteous replies from the forum participants. Try and keep your question focused and provide all of the relevant code. This will be appreciated by everyone. One thing you could do is to try and demonstrate your bug in a very short program that removes all other extraneous issues. In fact, doing that may help you resolve the issue for yourself.

Good luck and good (bug) hunting

Some extra notes relating to this chapter are available here.