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
	`.hpp` header 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,

Please refer to Writing a Library for Arduino .

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.

Please refer to Select the libraries for compilation .

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.

Please refer to Select the libraries for compilation .

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,

Please refer to Create folders for local libraries .

For more information on selecting local libraries,

Please refer to Select the libraries for compilation and Select the 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,

Please refer to Locate the pre-compiled libraries and Generate the 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,

Please refer to the Multi-tasking page at the Energia website.

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,

Please refer to the section Write specific code for multiple platforms .

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.