Hardware and software combined, Arduino does many things right. It lowers the entry level into embedded systems development with a nifty hardware abstraction layer. It aims for cross-platform compatibility by supporting Windows, Mac OSX, and Linux operation systems. It throws out the need for an external programmer to get you up-and-blinkin’ those LEDs quickly.

One thing most of us never cease to curse about, though, is the IDE. Many have cried out wildly against the Java-based text-editor for its cryptic compiling-and-linking process, its inability to accommodate bare C or C++ source files, and (shh!) its lack of Vim keybindings. Fortunately, our cries have been heard, and the like many community-based projects, the community fights back with a custom solution.

Calling all Grumpy Engineers: The Arduino-Makefile

Enter the Arduino Makefile.

What began as [Sudar’s] lightweight program to escape the IDE has become a fully-blown, feature rich Makefile that has evolved and adapted to grow with the changes of Arduino. With a community of 47 contributors, the Makefile enables you to escape from the IDE entirely by writing code in the cushy text editor of your choice and compiling with a simple incantation of make into your terminal, be you in Linux, Mac, or Windows.

Without further ado, let’s take a walking tour of the project’s highlights.

Cryptic Shortcuts–Begone!

For many beginners, writing (or even editting) a Makefile can cause some serious confusion with most Makefile authors’ shameless shortcut use. Make no mistake, the cryptic syntax of many Makefiles forms a concise list of instructions for compiling and linking your executable, but this recipe does seem a bit hard to parse for the uninitiated. What’s more, Makefiles also tend to throw bizarre errors (trailing whitespace anyone?) that are difficult to track down–especially when we want to spend most of our time bringing up embedded systems, not understanding the mechanics and syntax of a Makefile. Fortunately [Sudar] and the rest of the development team have made the interface very human readable.

Their solution: A two-part Makefile. For a simple project, your Makefile need be no longer than this snippet (inspired from the Makefile Examples):

BOARD_TAG    = uno
include $(ARDMK_DIR)/Arduino.mk

Project-specific settings (like which board you’re using) are outlined in this brief Makefile that then includes the larger Makefile which contains the actual nuts and bolts for building your code. The assumption here is that you’ve defined two environment variables, both ARDMK_DIR and ARDUINO_DIR that point towards the (1) Arduino Makefile directory and the (2) Arduino Installation directory. In addition, if you have additional libraries, you can include them with a line in your top-level Makefile that defines the filepath.

 USER_LIB_PATH += /home/my_username/my_libraries_directory

You’ll also need to add all libraries you’re using (both user-added and built-in) to the list of libraries like so:

ARDUINO_LIBS += Wire \
                SPI \
                my_custom_lib

The benefit of a “split-Makefile” setup is that the short, top-level Makefile hides the gritty compiler gymnastics involved in compiling and linking against the default and user-added Arduino Libraries. On the flip-side, this “mini” Makefile becomes a brief, informative summary of a few minor details, such as which Arduino Libraries are being used, that are likely more relevant to the author and future developers.

Raw C and C++ is In–if you prefer such things

Tired of that *.ino file extension? Tired of having to constrain yourself into those setup and loop functions? With the Makefile, you can quickly wish these away and write your code in raw C or C++. You can even neglect to #include <Arduino.h> if you want to work in vanilla C or C++ and disregard the Arduino libraries altogether.

That said, if you’re mixing C and C++, keep in mind that you’ll need to insert guards around your C header files like so:

#ifdef __cplusplus
extern "C" {
#endif

/// the rest of my C header file 

#ifdef __cplusplus
}
#endif

Adding Project Libraries

Possibly my favorite aspect of the Arduino Makefile is its flexibility to accomodate a richer file structure and painlessly split your project into multiple files. Let’s say I have a one-off project where it makes sense to include a custom library. Given the flexibility of the Makefile, you can define:

    USER_LIB_PATH+=.
    ARDUINO_LIBS += my_custom_library

in your project Makefile and produce a directory tree like so.

 ├── main.ino
 ├── Makefile
 ├── my_custom_library
 ├── my_custom_library.cpp
 └── my_custom_library.h

If you need more flexibility, you can also split your source code across several directories, keeping the Makefile in the same directory of your code that acts like a “main.” (In this case, main.ino defines setup  and loop.) To do so, your Makefile will, instead, have:

    USER_LIB_PATH+=../libs
    ARDUINO_LIBS += my_custom_library

in your project Makefile, and your directory structure will look like so:

 ├── libs
 │   └── my_custom_library
 │     ├── my_custom_library.cpp
 │     └── my_custom_library.h
 └── src
  ├── main.ino
  └── Makefile

Finally, we don’t need to constrain ourselves to writing just C++ classes to split projects into multiple files.  Since we’re really working with vanilla C++, you can freely split your project into multiple source (*.c, *.cpp, *.ino, *.pde) and header (*.h, *.hpp) files that live in the same directory as the Makefile, and the Makefile will compile them into one executable.

Other Micros are Fair Game Too

Finally, the Arduino-Makefile is also compatible with a host of other microcontrollers and programmers, not just the ATMEGA328P on the Uno. In short, this feature is an exposition of the features of AVRDUDE, the program for downloading and uploading code to various AVR microcontrollers. Last, but not least, it’s also Teensy-compatible.

Define Our Standard

If you’re looking to get comfortable with the Arduino-Makefile workflow, have a quick look at their examples directory for a host of different use-cases. You can also take a peek at my i2c_demultiplexing_demo source from a couple weeks back for yet another example. At the end of the day, Arduino, with its giant library collection, makes project prototyping fast. For bigger projects, though, we don’t tend to see any standard practices for file organization to make projects easier to navigate. That’s where you come in. With the flexibility of the Makefile, you get it all: the text editor you always wanted, the separate header and implementation files, a clean directory… Now it’s your shot to take this tool and refine your workflow into a method worth sharing with the rest of us.