DocsOpen the editorEditor

The sketch does not compile

Reading the Build tab, and the four things that usually cause it.

Read the Build tab first

It is under the file strip in the code pane. It lists the steps with their timings, then the compiler's own output as clickable lines. Click a line and the editor jumps to that file, line and column.

The diagnostics are real clang diagnostics, unedited. A position in your sketch is a position in your sketch: the file is compiled under its own name, so the line numbers are yours and not some wrapper's.

A linker error has no position. ld.lld: error: undefined symbol: loop() appears as a line without a jump, because there is nothing to jump to.

1. A missing include

The most common one, and it has a symptom of its own: clang stops hard on a missing header. The build panel treats that as a failed build and shows the diagnostic rather than reporting a crash, so look for the file not found line.

Only the headers of your own project and the runtime's own are there. There is no package manager, no Arduino library folder and no network in the build.

The runtime's own include the stock libraries tutorials use most, under their usual names: Servo.h, Wire.h, SPI.h, EEPROM.h, LiquidCrystal_I2C.h, Adafruit_GFX.h, Adafruit_SSD1306.h, Adafruit_NeoPixel.h and DHT.h (the list, and what each covers). Header names are case-sensitive, so servo.h is not found where Servo.h is, and the Build tab says so. For any other library it names the Mokxi header that does the same job, or says there is none yet.

2. A function that is not in this runtime

The runtime is ours: freestanding C and C++ with the Arduino language reference's API. It carries pinMode, digitalWrite, digitalRead, analogWrite, analogRead, millis, micros, delay, delayMicroseconds, pulseIn, shiftIn, shiftOut, tone, noTone, attachInterrupt, Serial with parseInt and readStringUntil, String, floating point and the math library, the character tests, and sprintf with the rest of the C library tutorials use, plus shared drivers for the displays and the WS2812 strip (the list).

It is not avr-libc, not the Arduino core and not ESP-IDF, and none of those are fetched at build time. A call that resolves on a real Arduino may still not exist here (analogRead on a board whose converter is not modeled, say), and the build will say so.

3. The wrong file is main

A project has several files and one of them is where the compiler starts. If you renamed the sketch, check that the file you expect to be the entry point still is.

4. It compiled, but Run ran something else

Three things can happen when you press Run, and only one of them is a build:

  • the board runs a prebuilt example or an uploaded ELF, and nothing is compiled;
  • the board reuses the last build, because not one byte of the files changed;
  • the board is built.

An ELF you uploaded was not built from these files, so it wins. Clear it in the board's properties panel if you meant to compile your own code.

5. It compiles in the Arduino IDE, but not here

Two things the Arduino IDE does for a sketch, Mokxi does too, so a sketch copied from a tutorial does not trip on them.

  • Functions can be called before they are defined. The Arduino IDE writes a prototype for every function in the .ino tabs before it compiles them, and so does Mokxi, so loop() can call a function defined further down. Several .ino tabs are joined into one file, main tab first, as the IDE joins them. A few functions get no prototype: templates, functions inside a class or namespace, and a function whose parameter types are declared further down the sketch. For those, a call above the definition is use of undeclared identifier: move the function above the code that calls it, or put a one-line prototype such as void blinkTwice(); at the top.
  • Warnings do not stop the build. Your files are compiled with -Wall -Wextra, and the Build tab lists what they find, but the sketch still builds and runs, as it does in the IDE. An unused variable or parameter and a signed and unsigned comparison (int i < sizeof(pins)) can wait. if (x = HIGH) is worth fixing: a single = assigns, so the condition is always true, and you meant ==.

What is left is usually a library Mokxi does not carry, or a function that board's runtime leaves out: sections 1 and 2 above.

Arduino compile errors explained goes through the common messages one by one, in both GCC's words and clang's.

If the first build hangs

It is not hanging, it is downloading. The toolchain is about seventy megabytes of clang and it streams once, then lives in the browser's cache. The steps in the Build tab say where it is. A return visit is about a second and a half, and an edit and run after that is a fraction of a second.

Still stuck

Compiling in the browser is the full contract: the command list, the cache keys and how the runtime is assembled. Or write to us from /support with the diagnostic.