The rationale here is that we don't want to pollute the include paths of user projects by any of the new include files that we add to https://github.com/kripken/emscripten/tree/master/system/include/emscripten. I'm reading through build notes from a partner and they have documented a custom hack where they rename header file in system/include/emscripten: vector.h -> em_vector.h so that it doesn't conflict with a filename vector.h that they have in their own project.

We have some awfully general names in the system include directory: bind.h, html5.h, threading.h, trace.h, val.h, vector.h, vr.h and wire.h. It would be nice to spread the practice of always including these with #include <emscripten/foo.h>, that way we can safely add headers there without risking name pollution. This would allow dropping the include to system/include/emscripten and just have system/include instead. (this will need an option to not break existing users, but could be configurable)

I see, makes sense.

The one exception I'd suggest is to allow #include <emscripten.h>, as it shouldn't conflict with other things, is convenient, and is consistent with C practices. So maybe the solution here is to create a subdir emscripten and move everything but emscripten.h into that subdir?

(Or move emscripten.h one lower.)

I suppose allowing #include <emscripten.h> should be fine, as long as we treat that file as the only special case.

We can't move emscripten.h one lower though, because that would break #include <emscripten/emscripten.h>, which is already widely used.

But I think we can do a stub emscripten.h in one directory lower, that just does #include "emscripten/emscripten.h" to route to the actual file. That would allow using both #include <emscripten.h> and #include <emscripten/emscripten.h> while keeping the rest of the include files in their own subdirectory. How does that sound?

The method has more options I guess, we could also just add the parent dir and the emscripten/ dir to the include list. Anyhow, I'm not picky about the technical details, but I think it makes sense to require including to prefix emscripten/ as you suggest, but to allow emscripten.h as the only one that works without it.

+1
We can just include a parent directory in the include path, which contains a directory emscripten and a file emscripten.h. The subdirectory can have all the files (including the real emscripten.h) and the emscripten.h in the parent directory can just include emscripten/emscripten.h.

Oh btw, have you guys given any thought to having a more distro-like/SDK-like layout to the includes and libs? Right now we have system/include/<foo> for a whole bunch of different ports, which presumably means you have a ton of includes on the command line. It might make sense to have an include and usr/include for the system includes and port includes (and where users could add their own stuff if they wanted to).

Updated PR. Tiny changes remain, I believe this should be all good, so merging directly.

The changes related to <emscripten.h> will be part of a second PR.

@dschuff: So far that kind of structure has not had appeal, for one because the directory under emscripten/ is considered read-only for users, so workflows don't generally involve adding custom includes there. The ports system works somewhat transparently so that users don't need to manually add the include directories, so optimizing down the number of include directives has not been a concern there. Not sure though if this might have been a conversation elsewhere that I haven't seen.