The overarching mistake here is not using a proper build toolchain (build system and package manager). I especially take issue with this assertion:
The correct SDL2 include is the following:
#include "SDL.h"
Including headers with the library prefix (#include <SDL2/SDL.h>) is our only hope to have an inter-operable ecosystem of C/C++ libraries. Let me illustrate this with a concrete example. What the article suggests is having the header search path (i.e., -I option from sdl2-config) pointing to the location of the SDL.h header (say, /usr/include/SDL2). But there are other headers in there. Thankfully, most of them have the SDL_ prefix (by all means an exception rather than the rule, when it comes to C/C++ libraries), but not all. For example, there is the generically-named begin_code.h header.
Imagine now that your project is using another library with the same arrangement which also contains a bunch of generically-named headers and one of them happened to be called begin_code.h. Now which one gets picked up depends on the order of the -I options that are passed to the compiler.
The SDL wiki is not authoritative documentation, merely a convenient web-linkable — and downloadable (see “offline html”) — information source. However, anyone who’s spent time on it can tell you it’s incomplete. The authoritative API documentation is the SDL headers, which fortunately are already on hand for building SDL applications. The SDL maintainers themselves use the headers, not the wiki.
Seems like a good side project, a project that just pulls out the documentation from the SDL headers and puts that on the web.
It’s of course great to be able to jump into headers and see proper documentation there, but there’s a hell of a lot of value in being able to link to docs when discussing things with other people.
Unfortunately there are hoops to jump through in order to edit the documentation wiki, making it harder for an outsider to volunteer to just do this. And SDL2’s API is still being actively worked on, so in order to stay current it should really be part of the release process itself.
It’s disappointing because the previous major version, SDL1.2, had excellent standalone documentation – complete, thorough, and (best of all!) available as man pages.
SDL has grown on me over the past year. I didn’t understand its value until viewing it in the right lens: as a complete platform and runtime replacing the host’s runtime, possibly including libc.
From this perspective it sounds a lot like Justine’s “Cosmopolitan” library and Actually Portable Executables, except the latter lets you keep using regular C/POSIX APIs (mostly) instead of learning new ones, and the same binaries magically run on all supported platforms.
On the other hand SDL has a bunch of higher level APIs for graphics and games, of course, but judging by the OP’s other blog posts I’m guessing that’s not the part that interests him?
The overarching mistake here is not using a proper build toolchain (build system and package manager). I especially take issue with this assertion:
Including headers with the library prefix (
#include <SDL2/SDL.h>) is our only hope to have an inter-operable ecosystem of C/C++ libraries. Let me illustrate this with a concrete example. What the article suggests is having the header search path (i.e.,-Ioption fromsdl2-config) pointing to the location of theSDL.hheader (say,/usr/include/SDL2). But there are other headers in there. Thankfully, most of them have theSDL_prefix (by all means an exception rather than the rule, when it comes to C/C++ libraries), but not all. For example, there is the generically-namedbegin_code.hheader.Imagine now that your project is using another library with the same arrangement which also contains a bunch of generically-named headers and one of them happened to be called
begin_code.h. Now which one gets picked up depends on the order of the-Ioptions that are passed to the compiler.Yeah, that advise seemed puzzling to me. Even
sdl2-config- in a world with CMake and pkg-config…Seems like a good side project, a project that just pulls out the documentation from the SDL headers and puts that on the web.
It’s of course great to be able to jump into headers and see proper documentation there, but there’s a hell of a lot of value in being able to link to docs when discussing things with other people.
Unfortunately there are hoops to jump through in order to edit the documentation wiki, making it harder for an outsider to volunteer to just do this. And SDL2’s API is still being actively worked on, so in order to stay current it should really be part of the release process itself.
It’s disappointing because the previous major version, SDL1.2, had excellent standalone documentation – complete, thorough, and (best of all!) available as man pages.
From this perspective it sounds a lot like Justine’s “Cosmopolitan” library and Actually Portable Executables, except the latter lets you keep using regular C/POSIX APIs (mostly) instead of learning new ones, and the same binaries magically run on all supported platforms.
On the other hand SDL has a bunch of higher level APIs for graphics and games, of course, but judging by the OP’s other blog posts I’m guessing that’s not the part that interests him?