Posts | Comments

Planet Arduino

Archive for the ‘makefile’ Category

Arduino now has an officially supported command-line interface. The project, called arduino-cli, is the first time that the official toolchain has departed from the Java-based editor known as the Arduino IDE. You can see the official announcement video below.

Obviously this isn’t a new idea. Platform IO and other command-line driven tools exist. But official support means even if you don’t want to use the command line yourself, this should open up a path to integrate the Arduino build process to other IDEs more easily.

The code is open source, but they do mention in their official announcement that you can license it for commercial use. We assume that would mean if you wanted to build it into a product, not just provide an interface to it. This seems like something Arduino expects, because a lot of the command line tools can produce json which is a fair way to send information to another application for parsing.

The command line interface doesn’t just build a sketch. You can do things like install and manage libraries. For example, to create a new sketch:

arduino-cli sketch new HackadayPgm

You can update the installed platforms, list the connected boards, and search for board support:

arduino-cli core update-index

arduino-cli board list

arduino-cli core search mkr1000

If you don’t already have the board support, you can install it and verify that it is there:

arduino-cli core install arduino:samd

arduino-cli core list

That last step will give you the FQBN or unique name for the core. So to compile and upload you have this mouthful:

arduino-cli compile --fqbn arduino:samd:mkr1000 Arduino/HackadayPgm

arduino-cli upload -p /dev/ttyACM0 -fqbn arduino:samd:mkr1000 Arduino/HackadayPgm

Unlike, say, PlatformIO, this is clearly better for building into a tool, even if it is a makefile. We’d like to see a .build.json file or something that allows you to just issue short commands that do the right thing in a working directory. Of course, you could build that with a little shell scripting. Hmm….

It is nice to see the release of an official method and we hope this will lead to more editors being able to handle Arduino seamlessly.

Arduino now has an officially supported command-line interface. The project, called arduino-cli, is the first time that the official toolchain has departed from the Java-based editor known as the Arduino IDE. You can see the official announcement video below.

Obviously this isn’t a new idea. Platform IO and other command-line driven tools exist. But official support means even if you don’t want to use the command line yourself, this should open up a path to integrate the Arduino build process to other IDEs more easily.

The code is open source, but they do mention in their official announcement that you can license it for commercial use. We assume that would mean if you wanted to build it into a product, not just provide an interface to it. This seems like something Arduino expects, because a lot of the command line tools can produce json which is a fair way to send information to another application for parsing.

The command line interface doesn’t just build a sketch. You can do things like install and manage libraries. For example, to create a new sketch:

arduino-cli sketch new HackadayPgm

You can update the installed platforms, list the connected boards, and search for board support:

arduino-cli core update-index

arduino-cli board list

arduino-cli core search mkr1000

If you don’t already have the board support, you can install it and verify that it is there:

arduino-cli core install arduino:samd

arduino-cli core list

That last step will give you the FQBN or unique name for the core. So to compile and upload you have this mouthful:

arduino-cli compile --fqbn arduino:samd:mkr1000 Arduino/HackadayPgm

arduino-cli upload -p /dev/ttyACM0 -fqbn arduino:samd:mkr1000 Arduino/HackadayPgm

Unlike, say, PlatformIO, this is clearly better for building into a tool, even if it is a makefile. We’d like to see a .build.json file or something that allows you to just issue short commands that do the right thing in a working directory. Of course, you could build that with a little shell scripting. Hmm….

It is nice to see the release of an official method and we hope this will lead to more editors being able to handle Arduino seamlessly.

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.


Filed under: Arduino Hacks, Featured


  • Newsletter

    Sign up for the PlanetArduino Newsletter, which delivers the most popular articles via e-mail to your inbox every week. Just fill in the information below and submit.

  • Like Us on Facebook