The non-portability of Arduino programs

I just got an Arduino Robot and started playing with it. However, I felt great pain of developing Arduino programs from the non-portability across different Arduino IDEs.

I used 3 Arduino IDEs:

• v.1.0.5 via apt-get on Ubuntu 14.04 
• v1.0.6, downloaded from Arduino website, compiled 
• v.1.5.8 Beta, downloaded from Arduino website, compiled

And I simply wanted to test a trivial motor rotation code from Arduino Robot's Getting Started Guide:

#include <arduinorobot.h> // import the robot library

void setup(){
  Robot.begin(); // initialize the library
}

void loop(){
  // move forward for one second
  Robot.motorsWrite(255,255);
  delay(1000);

  Robot.motorsWrite(0,0); // stop moving
  delay(1000);

  // move backwards for one second
  Robot.motorsWrite(-255,-255);
  delay(1000);

  Robot.motorsWrite(0,0); // stop moving
  delay(1000);
}

Here came the non-portability of Arduino programs:

1. This code couldn't get compiled by v.1.0.6 nor v.1.5.8 because the libraries Wire.h and SPI.h for some reason couldn't be included from ArduinoRobot.h. I had to manually include the two libraries in the code above to compile it. Namely, the macro must look like this:
   

   #include <ArduinoRobot.h> // import the robot library
   #include <Wire.h>
   #include <SPI.h>

   No such a problem when using v.1.0.5.
   Compatibility, if not portability, issues caused by this is floating around the Internet, such as this post
   
2. There is no mechanism to prevent double include or double definition (e.g., using #ifdef) in source code of Arduino Robot library. If I happen to include Wire.h and compile using Arduino IDE v.1.0.5, I will get the error of duplicated definition.
3. The inconsistent behavior of Arduino IDE/Compiler. Arduino defines its own modified C syntax. Its IDE/compiler first converts an Arduino sketch (a program, of suffix .ino) into a regular C code and use avr-gcc to compile. But it is very unclear how this conversion is done. From the discussion above, one can see that the conversion is done differently across different Arduino IDE versions. Sometimes it even mis-converts, like in this post.
4. Configurations that cannot go with the code. Arduino IDE requires you to select Arduino target device before compilation. But such configuration info does not go as a file (a separate file or part of your C code) when you port the code. Arduino IDE does not generate a configuration file for each project. For people who are new to Arduino, they have to remember this step which is about using the IDE instead of programming itself. A misconfiguration or forget-to-configure can cause frustration to beginners, like in this post.

It's very difficult to troubleshoot the issues above. For example, if Arduino IDE/compiler filed to find a header file, how do you know whether the location of your library is on the search path of Arduino compiler or avr-gcc? Arduino IDE does not keep files generated from your source code (e.g., converted C code, Makefile, logs) at a place clearly known to users. It creates a temporary folder somewhere and you had to find that place by swamping thru the verbose logs printed on the screen. Frankly, I really don't know why it is designed so.

I am gradually realizing that Arduino IDE makes it very difficult to be used for large projects. Another pain for me is importing libraries. But the non-portability of code is a bigger pain. I wasted about 30 minutes tonight to get a hello-world code work on my Arduino Robot due to it.

Comments and critics are all welcome. I might have biases in this post.