Move global declarations to a namespace

[sergeuz]

Problem

Particle APIs get pulled into the global namespace and cause conflicts with an application code. This behavior cannot be overridden by application developers.

Solution

Add PARTICLE_NO_GLOBAL_NAMESPACE macro that can be defined by applications to avoid having Particle APIs declared in the global namespace.

Note: This PR doesn't attempt to move all current APIs to the particle namespace, and many existing classes and functions are still declared in the global namespace directly. I suggest we start moving such declarations to namespaces iteratively, on occasion.

Steps to Test

wiring/api test should compile successfully.

Example App

#define PARTICLE_NO_GLOBAL_NAMESPACE

#include "Particle.h"

// I just need my own WiFi class
class WiFi {
};

void test(WiFi&) {
}

References

• fixes #1267
• [ch8449]

---

Completeness

• User is totes amazing for contributing!
• Contributor has signed CLA (Info here)
• Problem and Solution clearly stated
• Run unit/integration/application tests on device
• Added documentation
• Added to CHANGELOG.md after merging (add links to docs and issues)

[monkbroc]

That's a good idea. 👍

Due to how the wiring preprocessor works, it needs to be documented that both the new define and the Particle include need to be added. For a refresher on how the preprocessor works, see the preprocessor description in the docs.

For example this wouldn't work in the Web IDE:

#define PARTICLE_NO_GLOBAL_NAMESPACE
class WiFi {};

This would work:

#define PARTICLE_NO_GLOBAL_NAMESPACE
#include "Particle.h"
class WiFi {};

We also document using #include "Particle.h" not #include "application.h". I know they are equivalent but that's the documentation choice right now. (BRETT: Edited the example app with this)

[sergeuz]

That's a good point, Julien. Good to know that the Web IDE is smart enough to not pre-include any header files unconditionally.

[m-mcgowan]

It would be nice to see tests affirming that global symbols such as Message and Promise are no longer taken by default.

[m-mcgowan]

Is this a safe change? is it something we should queue up for the 2.x release in case there are breaking changes? I would like to see the API test suite expanded to cover the entire API and become our definitive reference of what is in the global and particle namespaces.

[monkbroc]

Let's document the macro in https://docs.particle.io/reference/device-os/firmware/photon/#preprocessor