Manage compatibility with standard IDEs

Projects developed by embedXcode are highly compatible with the standard Processing-based Wiring-derived Arduino-like IDEs.

The standard IDEs will open and compile most embedXcode projects successfully.

  • Double-click on the main sketch of the embedXcode project, embed1.ino on the example.

  • Compile with the standard IDE, Energia on the example.

However, unlike the standard IDEs, code with embedXcode is true C++. The main difference is, embedXcode buils and links the code directly, while standard IDEs process the code before building and linking it.

The table below lists the points to ensure compatibility betwen embedXcode and the standard IDEs.

Category Point embedXcode Standard IDE
Main sketch Functions prototypes If needed Optional
Core library #include Required Optional
All used libraries #include Optional Required
Main Makefile All used libraries listed Required Not available
Libraries Local libraries Optional Not available
Pre-compiled libraries Optional Not available
.hppheader files Optional Not available
Energia MT rtosGlobals.h file Optional Dedicated .ino
setupRtos() function Optional Dedicated .ino
Portability Code for multiple MCUs Optional Optional
Projects names and paths Spaces and special characters Not recommended Not recommended
embedXcode Pre-processing variable Available Optional

Ensure compatibility for the main sketch

Declare functions prototypes on main sketch

The main consequence of true C++ is the need for declaring prototypes of the functions in the main sketch.

In the example provided below, the prototype for functionB() is required, as functionB() is called by functionA() but defined after.

// Prototypes
void functionA();
void functionB();

// Functions
void functionA() 
{
    Serial.println("functionA");
    functionB();
}

void functionB() 
{
    Serial.println("functionB");
}

Without prototyping functionB(), compilation would raise an error. The standard IDEs add the prototypes on the main sketch.

Prototypes aren't required for libraries as they are already included in the header file.

Prototypes are fully compatible with the standard IDEs.

Include core library on main sketch

The same #include statement to the core library is required on each header file of each library, as it is recommended for the standard IDEs.

// Core library - IDE-based
#if defined(WIRING) // Wiring specific
#include "Wiring.h"
#elif defined(MAPLE_IDE) // Maple specific
#include "WProgram.h"
#elif defined(ROBOTIS) // Robotis specific
#include "libpandora_types.h"
#include "pandora.h"
#elif defined(MPIDE) // chipKIT specific
#include "WProgram.h"
#elif defined(DIGISPARK) // Digispark specific
#include "Arduino.h"
#elif defined(ENERGIA) // LaunchPad specific
#include "Energia.h"
#elif defined(LITTLEROBOTFRIENDS) // LittleRobotFriends specific
#include "LRF.h"
#elif defined(MICRODUINO) // Microduino specific
#include "Arduino.h"
#elif defined(TEENSYDUINO) // Teensy specific
#include "Arduino.h"
#elif defined(REDBEARLAB) // RedBearLab specific
#include "Arduino.h"
#elif defined(RFDUINO) // RFduino specific
#include "Arduino.h"
#elif defined(SPARK) || defined(PARTICLE) // Particle / Spark specific
#include "application.h"
#elif defined(ARDUINO) // Arduino 1.0 and 1.5 specific
#include "Arduino.h"
#else // error
#error Platform not defined
#endif // end IDE

The #include statement

For more information on library development,

Include all used libraries in main sketch

The standard IDEs require including all the libraries in the main sketch, even those not used by the main sketch but used in libraries, while embedXcode allows naming only the libraries which are directly called by the main sketch.

In order to ensure compatibility with the standard IDEs, including all the libraries in the main sketch is thus highly recommended, as the standard IDEs require it. It doesn't affect embedXcode.

List all the used libraries in main Makefile

The standard IDEs include an automatic procedure to list the libraries used by a project, while embedXcode requires a list of those libraries in the main Makefile.

Two variable are provided: the APP_LIBS_LIST variable list the application libraries and the USER_LIBS_LIST variable the user's libraries.

The embedXcode+ edition adds a third variable, the LOCAL_LIBS_LIST variable, to select the local libraries, if they are located inside sub-folders on the project folder.

Ensure compatibility for libraries

Manage local libraries

This section requires the embedXcode+ edition.

The embedXcode+ edition allows to select local libraries when they are placed into sub-folders.

Standard IDEs do not manage sub-folders for libraries. The content of the sub-folders should be moved to the main folder of the project.

For more information on using sub-folders for local libraries,

For more information on selecting local libraries,

Manage pre-compiled libraries

This section requires the embedXcode+ edition.

The embedXcode+ edition allows to include pre-compiled libraries with extension .a along with their header files and a .board file.

Standard IDEs do not manage pre-compiled libraries. The pre-compiled library should be unarchived by running the Unarchive target to obtain the source code files.

For more information on pre-compiled libraries,

Manage .hpp extension for header files

This section requires the embedXcode+ edition.

The embedXcode+ edition supports the .hpp extension for header files.

Standard IDEs do not manage the .hpp extension for header files.

  • Change the .hpp extension of all the header files for .h.

  • Update the #include statements accordingly.

Make Energia MT projects compatible

embedXcode includes some exclusive features for the Energia MT framework.

Check the name of the functions of the tasks

Each task includes its own setup() and loop() functions with the name of the task.

When embedXcode allows any combinations of setup and loop in the names of the functions,

void TaskCode_setup()
void setup_TaskCode()
void setupTaskCode()

The latest release of Energia requires loop and setup to be mentioned as prefixes.

void setup_TaskCode()
void setupTaskCode()
  • Rename the setup() and loop() functions of the tasks with loop and setup mentioned as prefixes.

Delete the setupRtos() function

The setupRtos() function isn't supported by Energia MT yet.

To make the project compatible,

  • Create a new sketch rtosGlobals.ino.

  • Copy-paste the setupRtos() function.

  • Add an empty LoopRtos() function.

void LoopRtos()
{
    ;
}

Delete the rtosGlobals.h file

Similarly, global variables and constants are defined on the main sketch in Energia, while embedXcode relies on the rtosGlobals.h header file.

If global variables and constants are defined,

  • Move the global variables and constants from the rtosGlobals.h header file into the main sketch. The main sketch has the same name as the project.

  • Delete the rtosGlobals.h file.

Finally, embedXcode uses the specific variable ENERGIA_MT, which is not available on the standard IDE.

If the specific variable ENERGIA_MT is used,

  • Add the pre-processing statement on the impacted header files. 
#define ENERGIA_MT

Because an Energia MT project has ARDUINO and ENERGIA already defined, those variables need to be tested in a given order.

#if defined(ENERGIA_MT)
// Energia MT specific
#elif defined(ENERGIA)
// Energia specific
#elif defined(ARDUINO)
// Arduino specific
#endif

For more information about Energia MT,

Manage code for multiple platforms and MCUs

embedXcode allows great flexibility on customising the code, especially when developing for different platforms and MCUs.

An easy solution is described at the section Insert #include statements from code snippet .

For more information,

The standard IDEs often require to close one IDE and open another.

Avoid spaces and special characters in projects names and paths

The standard IDEs, as well as the tool-chains an utilities they use, don't support spaces and special characters in the name and path of the project, although embedXcode manages them.

A good idea is to replace spaces by underscores. For example, rename embed 1 to embed_1.

In order to ensure compatibility, it is highly recommended to avoid spaces and special characters in the name and path of the projects.

Similarly, avoid spaces in the name and path of the sketchbook folder.

The iCloud drive contains special characters, it is thus recommended not to store projects inside.

Use embedXcode pre-processing variable

A project using embedXcode includes the pre-processing variable EMBEDXCODE, with the release number as value.

EMBEDXCODE = 105

The variable and the value are passed on to the compiler and the linker as a -D variable.

-DEMBEDXCODE=105

This allows to manage conditional pre-processing statements as #define and #include based on the IDE you use, either Xcode or one of the large Processing-based Wiring-derived Arduino-like IDEs family.

This also allows to open an embedXcode project with a Processing-based Wiring-derived Arduino-like IDE and compile it.

The EMBEDXCODE variable is already used in the main.cpp code file so it is only considered when compiled by Xcode, and ignored by the other IDEs.