Skip to content

Write the sketch

The newly created project contains various files:

  • The file main.cpp calls the appropriate core libraries, initialises the board, includes the sketch. The main() function calls the setup() and loop() functions from the sketch. Do not alter this file.

  • The embed1.pde or embed1.ino file is where you write the sketch, with the setup() and loop() functions and all the additional ones.

  • The files LocalLibrary.h and LocalLibrary.cpp are the header and the code for the LocalLibrary library. They are provided as example.

  • The file makefile is the entry for the compilation processes. Do not alter this file.

The files you can play with are the embed1.pde or embed1.ino files for the sketch, and the LocalLibrary.h header and LocalLibrary.cpp code for the LocalLibrary library.

A project can only have one .ino file, except for Energia MT on the LaunchPad MSP432 and CC3200.

The files of the newly created project include links to the online user manual. The links are labelled !!! Help:.

// Core library for code-sense - IDE-based
// !!! Help:
#if defined(WIRING) // Wiring specific
#include "Wiring.h"
// ...
  • Press Cmd and hover the cursor of the mouse over the link.

The cursor of the mouse changes for a hand :fa-hand-pointer-o:.

  • While maintaining Cmd pressed, click on the link to open the related page, or Cmd+Left Button.

Other files also feature help links, including the main Makefile and the Doxygen file.

Main sketch template
Include core library on main sketch
Declare functions prototypes on main sketch
Write specific code for multiple platforms
Local library template
Write comments for projects and files
Include core library on main sketch
Comment a function
Task template
Add a task
Board configuration file template
Define a new board for the Wiring / Arduino framework
Define a specific programmer for a new board
Main Makefile
Select the Application Libraries
Select the User’s Libraries
Select the local libraries
Exclude libraries
Select scope for warning messages
Define compiler options
Change the path for standard IDEs
Manage the serial console after upload
Set Teensy USB type and keyboard layout
Set Teensy CPU speed and optimisation
Change the upload serial port
Change the serial console speed
Change the optimisation options
Select the output format

Use code-sense

Code-sense is a major feature of Xcode.

Apart from pretty colours on the code and enhanced visibility, code-sense brings many features that speed up coding.

However, code-sense faces some limitations. For example, macros calling other macros are poorly indexed, resulting in lines with standard black characters.

Use auto-completion

First, check auto-completion is turned on:

  • Call the menu Xcode > Preferences,

  • Select the tab Text Editing > Editing,

  • Check Suggest completions while typing.

To use auto-completion,

  • Type the first letters and Xcode completes.

  • Select one item of the list and press tab.

To use code-snippets and check-as-you-type code monitoring,

  • Type the first letters and Xcode completes.

  • Fill-in each parameter and press tab to go to the next one.

Get Quick Help

The Quick Help feature displays on the Utilities panel all the available documentation for the function under the cursor:

To use click-to-definition,

  • Place the cursor on a function.

  • Press Cmd+Left Button to access a function definition.

Notice the hand :fa-hand-pointer-o:.

Xcode displays the function.

As a variant, to use the contextual help,

  • Place the cursor on a function.

  • Press Alt+Left Button to display the definition.

Notice the question mark :fa-question:.

Xcode opens a dialogue box with all the information.

Sometimes, the index of keywords needs to be re-indexed.

For the Cosa object-oriented framework, the documentation is automatically provided in embedXcode when typing.

Help provides detailed documentation on a specific function.

Help lists the functions of an object.

Use code live check

This section requires the embedXcode+ edition.

Xcode checks the code on the go and prompts error and warning messages.

In the example shown below, pinMode(myPin, OUTPUT); raises an error because the variable myPin hasn’t been declared.

When uint8_t myPin = RED_LED is declared, the issue vanishes.

The same logic applies for warnings.

In the example shown below, uint8_t i; raises a warning because the variable i isn’t used.

When the variable is used with i = 3;, the warning vanishes.

Code live check always waits for a period of inactivity to run.

  • Code live check may require closing the current project and reopening it.

  • Please refer to Enable code live check to turn it on.

Beware of false warnings

Code live check may raise false warnings.

In the example below, the compilation variable ARDUINO isn’t set with a specific value. As a consequence, the pre-processing statement #if...else...endif branches to #include "WProgram.h". Because WProgram.h doesn’t exist, code live check mentions an error.

However, during compilation, the variable ARDUINO is populated with 10807. The pre-processing statement #if...else...endif branches to #include "Arduino.h". Building and linking succeed.

Similarly, some functions like Serial.println() may be reported as an error under the Semantic Issue category. Again, building and linking succeed.

The environment for editing and the environment for compiling are different. For editing and thus performing live code check, Xcode uses its own tools. For compiling, Xcode relies on the external building system of embedXcode, which provides the exact environment to complete the task successfully with the Wiring / Arduino framework.

To disable code live check,

Use the Touch Bar

Xcode provides useful short-cuts if your Mac features a Touch Bar.

However, with Xcode on any Mac, call the menu Window > Show Touch Bar or press Cmd+Shift+5 to display the Touch Bar on the screen.


  • Install and use a utility like Touché .

Use bookmarks

We can use the breakpoints as bookmarks.

To display the bookmarks,

  • Click on the Breakpoint Navigator button:

To add a bookmark,

  • Select the line:

  • Click on the line number, here 113 of function loop(). The bookmark is added.

Multiple bookmarks can be added. They are grouped by file within the project.

To reach a position,

  • Just click on the bookmark you want to go, here line 104 of setup().

Bookmarks are actually breakpoints. They may conflict with the debug mode.

None of the Processing-based Wiring-derived Arduino-like IDEs has implemented debugging yet, except Energia for the LaunchPad boards.

To disable or remove the breakpoints,

Commit and compare code versions

Xcode manages versions if source control has been checked when creating the new project.

Alternatively, if the option hasn’t been check when creating the project,

  • Call the menu Source Control > Create Git Repositories…

Commit a new version

To commit a new version,

  • Either call the menu Source Control > Commit,

  • Or press Cmd+Alt+C.

  • Select the files to commit.

  • Enter a comment.

  • Click on Commit the Files.

Compare versions

To compare versions, use the dedicated version editor.

  • To display the version editor, call the menu View > Version Editor > Show Version Editor or press Cmd+Alt+Shift+Enter or click on the button shown below.

The current and previous versions are displayed alongside.

In this example, line 103 has changed:

The button allows to discard changes.

The versions can be selected among the previously saved versions.

For more information on this feature and on others,

  • Please refer to the Xcode help.

Re-index the keywords for code-sense

Code-sense is a major feature of Xcode. Sometimes, keywords need to be re-indexed.

Apart from pretty colours on the code and enhanced visibility, code-sense brings:

  • Auto-completion,

  • Code-snippets and check-as-you-type code monitoring,

  • Click-to-definition

If code-sense doesn’t work, we need to force a re-indexing of the keywords.

To do so,

  • First close the project.

  • Call the menu Window > Projects.

The Projects window opens and shows the list of the projects.

  • Select the project.

The blue dot close to embed2 means this project is open.

  • If a blue dot appears close to embed1, close the project first.

The index is saved within the Derived Data folder.

  • Click on the Delete… button to delete the index.

  • Confirm the deletion with Delete.

  • Load the project again.

There’s no code-sense yet: everything is in black-and-white, except standard C++ keywords in red, pre-processing statements in brown, comments in green and numbers in blue.

The index is being built again.

Once the index is built, code-sense shows pretty colours.