Maybe this is unique to me, but I've had one heck of a time getting started with C development. Some pain points include:
There are multiple references to the "example Makefiles" and a "Hello World" example project, but no actual instructions as to where to find them. (They're not in the Examples folder, which is where I looked first, but the C_API/Examples folder.)
It's very unclear what build steps are dependencies of each other and which are alternate methods. (e.g. building with CMake vs Make).
Where there are alternative options, it's hard to know which you should choose if you're not already intimately familiar with C build tools (which, let's face it, a lot of Playdate's developer crowd probably aren't). Some advice on what the heck CMake is and why it might be worth using when the example Makefiles seem to work fine on their own would be very helpful.
It's equally unclear what each type of build is meant to produce and where. For instance, section 4.2 describes building a .pdx file for use in the simulator using CMake and Make, then describes running a second command to build for device. What isn't apparent is why you need the second command (since as far as I can tell, the .pdx build in the first case works fine on device). It also makes it sound like, if you're building for device, you ONLY need the second line. This seems to be incorrect — as far as I can tell, the second command builds a .elf file and then copies it into the .pdx generated in the first step. If you don't run that first command, you don't end up with a usable game file.
There seem to be similar issues with the description of outputs from the basic example Makefile in section 4.3. As far as I can tell, the simulator option does nothing (at least, I've never seen it output a .so file). Or maybe it does do something, but it just copies the file into my Source directory, which isn't actually useful for anything until you call a different command to actually package the .pdx?
It appears that .pdx files built on Mac or Linux won't run properly on the Simulator on Windows, but that isn't made clear anywhere. There is a comment about how you need to use __declspec(dllexport) on your event handler on Windows, but it isn't obvious that this affects the built .pdx file and not just the build process itself.
All told, these kinds of organizational issues and missing bits of key information make it really difficult to work out if you've got your build chain set up correctly.
I took an over-simplified Linux approach, so my experience probably isn't characteristic of the C user base as a whole. I'm also the sort to do my programming in a text editor (bonus points if it does syntax highlighting), so I can't speak for how much of an issue it is to get Playdate set up with an IDE. I just did what Inside Playdate with C suggested: point PLAYDATE_SDK_PATH to the devkit and use make starting with one of the example projects. It spits out a .pdx that, near as I can tell, runs in the simulator on any OS. It certainly runs on the hardware.
That all being said, I feel like the C audience is treated somewhat as second-class citizens:
Not counting language differences, the Lua API still gets features that the C API doesn't. (Example, example)
Common situations in C are met with unintuitive error messages that amount to Not Supported™, and which are not mentioned in the documentation. (Example, example)
I don't get the impression the Playdate team are trying to ignore the C side of things, but it's clear that their focus is on Lua. I attempted to reach out and offer to help with revisions to Inside Playdate with C to be more accommodating in various regards, but haven't heard back about that. The offer totally still stands, though.
Thanks for the feedback. It's always a bit of a balancing act to give enough information but assuming a certain amount of C knowledge. Some of the output behaviors you noted could be cleared up in the docs which would help with any confusion.
@GuyPerfect The C API was an additional API which was added after the Lua API. It is our goal to have API parity but as all things, it takes time. Supporting newlib functions are very platform/compiler specific and can even very from machine to machine. Supporting them OOB is not easy and is left to the user if they want to use them (for now).
That makes total sense (and sorry if my first post was terse — I was mostly trying to chronicle things as I ran into them while setting up a C environment on a new computer, so I wasn't thinking a ton about tone).
I think a fairly common scenario is that a Lua developer will get as far as they can using Lua, then discover that some system isn't performant enough on Lua and start using the C API to port that system specifically. (That's certainly the bucket I fall into.) For these people, it might be helpful to assume less familiarity with existing C knowledge and potentially call out certain gotchas that arise when transitioning from Lua to C (such as that built .pdx files are suddenly no longer platform-agnostic).