Upcoming changes for Mozilla and SpiderMonkey concerning <stdint.h> (with relevance to embedders, and a request for help)

[Jeff Walden]

== The problem: a multiplicity of fixed-size integer types ==

We've long used the NSPR/SpiderMonkey fixed-size types (PRUint32/uint32) with reasonable success. But newly-imported code generally uses different types. Often they use <stdint.h>, hand-rolling typedefs for MSVC (sometimes only <2010, sometimes unconditionally). Others use the SpiderMonkey uint32-style types. No matter the names, definitions must be compatible with typedefs of the same name in other code. Unfortunately this isn't always the case (especially for uint32 and friends), causing two problems.

First, if incompatible typedefs ever see each other, it's a compile error. Some headers therefore enforce specific #include ordering. Such errors are easy to diagnose but not always easy to fix. Fixing a mis-ordering and recompiling works for minor incompatibilities. But if the incompatibility occurs in a mass change, these steps must be repeated: twenty-odd times, in one instance.

Second, incompatible typedefs can cause link-time errors. If an API is defined with int32 = int, but a user of it sees int32 = long, there'll be a symbol mismatch at link time. This has happened to a number of Mozilla developers, invariably wasting much time because the code *looks* right: uint32 in the API, uint32 in the user.

== The solution: <stdint.h>, plus a little more ==

We're fixing all this by moving to <stdint.h>-based types. For now we're simply introducing a <stdint.h>-like header, "mozilla/StdInt.h". We'll use this to address two problems. First, not all MSVC includes <stdint.h>, so StdInt.h will #include a <stdint.h> implementation for older versions of it. Second, we know attempts to do this in the past have broken embedders due to incompatible typedefs, and StdInt.h will provide a hook for an embedding to specify its own <stdint.h> with compatible definitions. Once this header's in place and is proven to work, we'll start switching away from the NSPR types in Mozilla in general.

== What embedders need to know ==

If you're targeting a compiler that ships a <stdint.h>, great! You probably don't need to do anything, because anything depending on <stdint.h> types probably just included that header.

If your compiler doesn't ship <stdint.h>, we've included a reimplementation for MSVC prior to 2010. If your code doesn't define <stdint.h> types, you're probably good to go again. If your code does define such types, and they're compatible with our reimplementation, you're still good.

But if things don't work using <stdint.h>, or if your <stdint.h>-named types aren't compatible with our reimplementation, you'll have to do a little work. First, copy an existing stdint.h implementation (the mozilla/MSStdInt.h in the tree may be a good place to start, depending what platform you're targeting). Modify any incompatible typedefs to suit your code's needs. Then define MOZ_CUSTOM_STDINT_H to a quoted path to that file. When it's included, StdInt.h will see this definition and #include MOZ_CUSTOM_STDINT_H. If things work out, you should be able to be on your way again with this.

== Help wanted ==

I'm hoping to land these changes, which are occurring in bug 704313, Real Soon Now. Before I do that, I'd like some confirmation that this plan will work to avoid conflicts. I've asked one embedder directly, but I could definitely use more embedder help.

Would any embedders be willing to take the time to apply the two patches in that bug and give things a run? I'm especially interested in feedback from embedders who will need to use MOZ_CUSTOM_STDINT_H, because the tactic may well need polishing around the edges.

Jeff