Bunch of small bugs and docs inconsistencies for a Windows dev

SDK Bug Reports
,
1

Hello folks! I'm a new developer using Windows 11 and I would like to share the bugs I found on my setup process. Basically everything that I found strange on my journey going from "Playdate is cool!" to a Hello World running on my PC. In this case I wanted to run a hello world in both Lua and C to check if I was 100% ready for doing actual work, regardless of what lang I choose.

Here they are:

  • There is no mention on the dev docs about the examples/ and c_api/examples folders (apart from mentioning that's one of the contents of the SDK). I feel that most of the commands mentioned on the docs must be ran inside one of these, especially those commands in the C docs that doesn't teach you how to build your project from scratch like it's done in inside docs section 3.2 structuring your project.
  • PlaydateSDK installer doesn't ask to add stuff to the PATH or to add the PLAYDATE_SDK_PATH envvar
  • No mention that the dev should add /bin to PATH to access pdc from cmd
  • C docs say "Add a CMakeLists.txt file to your project using the one from this project as a template" but what project is it?
  • CMake instructions to run cmake (C docs section 3.3) fails on windows when using on a barebones project

> cmake ..
CMake Warning:
Ignoring extra path from command line:
".."
CMake Error: The source directory "C:/Users//Documents/playdate-game" does not appear to contain CMakeLists.txt.
Specify --help for usage, or press the help button on the CMake GUI.

There is no mention (outside the CLion docs) on where to get or how to create your own CMakeLists.txt

  • On inside playdate docs, would be good to have an example of a Hello World project between sections 3.2 and 3.3 (or pointer to the /Examples folder)
  • On inside playdate docs, creating a new project from scratch, adding the snippet from section 4.1 to /source/main.lua and compiling using pdc source game.pdx compiles successfuly, but doesn't run on the simulator (lacks the images that code references). Lacks any mention that this won't run correctly.
  • Tried to follow C docs section 3.3 on /C_API/Examples/Hello World and got an error

> make
'make' is not recognized as an internal or external command,
operable program or batch file.

Maybe its because this section is not meant to be followed by Windows devs, but that's not written anywhere

  • On C docs section 4.3 "Open the Visual Studio project generated in the build directory." which one? Any one?
  • On C docs section 4.3 "In the Solutions Explorer within Visual Studio, select the target with the project name, not a meta target." Do you mean the VS project with my projects name? How do I select? Do you mean Set as Startup Project?
  • Following C docs section 4.3 from /C_API/Examples/Hello World generates an error:

Unexpected parameter 'World/hello_world.pdx'

I guess its a bug when the project name has a space on it. Maybe using quotes would help.

  • On C docs section 4.3 there's no mention on how to clean the project. Tried deleting the pdx folder but building again didn't work. Maybe mention the "Clean" button on VS

  • On C docs section 4.3 there's no mention on how to build for release. Is choosing the "Release" on the VS solution configuration enough

  • On C docs there's no mention of VS 2022 (VS 2019 is not easy to find on the VS home page anymore). Is it unsupported? Known bugs?

Looking forward to develop games for the playdate! Good luck with the project =D

2 Likes
2

  1. this could be better represented for sure, but the intention isn't really to run from examples so much as it is "create a source folder and add a main.lua then go" examples seem to be for people who have figured out the basics already. The C stuff is way harder and I am 89% sure is not at all complete, the experience isn't great and I have worked on improving that but it is a hard problem in general and varies in many many ways. The toolchain needs to be more cemented for that to flesh out.

  2. I am not sure why it would, does a typical windows installer provide that?

  3. Now I am a little confused myself, how do you have PATH on windows?

  4. All projects as of 1.9.3 include cmake files in the C_API/examples folder. You can use any of these as a base for your own project.

  5. Did you use one of the examples or make your own CMake project?

  1. Not true, but yes.
  2. It would be preferred if you could quote the section in this instance since the reference can change. But yeah, that is annoying.
  3. You don't have make installed, why would you expect it to work? seems self explanatory and was covered way earlier in the docs.

edit: I think this post would be more valuable if it was split up. Lua for one and C for another. Some of the points in this documentation are very much so "I have never touched a computer" vs "I definitely know how to use make". There is no way that the docs as they stand today can address both and I don't think they should, either. I'd also say its better to remove outdated information than leave it while trying to figure out how to update it. When it comes to C, I think it shouldn't even be mentioned in the Lua docs. But that is a greater discussion to be had.

3

Thanks for the feedback. There is a certain amount of knowledge that is assumed which we should flush out in the docs. We've been steadily improving them and we'll incorporate your feedback!

A few points:

  1. you don't need to add pdc to PATH. While it may be more convenient, it's not necessary.
  2. We could look into setting PLAYDATE_SDK_PATH with the installer, however setting that up is well documented in the docs.
  3. We could explicitly point people to the examples in the docs & create a barebones template project (there are some on Github already)
  4. Running the Hello World example inside of VS is, in fact, a path quoting bug. I've fixed it in our CMake file. Sorry that one snuck though.
  5. We could add more explicit instructions for VS users (e.g. Release/Clean) but you can expect those things to work as-expected.
  6. VS 2022 is relatively new and our docs haven't been updated to reflect it

Again, thanks for taking the time to provide feedback!

4

  1. Yes, it was harder specifically for C stuff

  2. Sure. Have you read the playdate docs on windows? It even says to, when installing cmake and the tool chain on windows, to let the installer change env vars when they prompt it.

  3. Hmm...yes? That's how CMD know where to search for binaries. You can see it by running echo %PATH% . PDC is not available on CMD unless you add it's binary to the path.

  4. Now I know. If you only read the docs, this isn't explicit. Also, what do I need to copy and what do I need to change to make it work? Not explained there as well. A "project structure" and a "minimal example" section would suffice on the C docs.

  5. Did it on a new project, following the structure suggested by the inside playdate docs. But that's the thing: the docs ask for you to run this but it doesn't teach what to setup before that.

  6. What's not true?

  7. For reference (in case someone from the future is reading this) it's version 1.9.3 of the docs at this current date

  8. That's the thing: is that section even supposed to work on windows? Installing make was never mentioned (cmake was but thats not the same, maybe that's the confusion). Also: what make should I install? MS stuff? Mingw?

5

A "project structure" and "hello world app" sections (maybe pointing to a template) for both lua and c docs would have saved me a lot of time. Other stuff is pretty minor.

6

You can run pdc from any location using the full path or running it from the bin directory.

While you can use the Make files on Windows, it's not supported in our example projects. CMake is much more straight-forward (if you can believe that :slight_smile: ) that is why it's only mentioned when talking about building on Windows in the docs.

Thanks again for taking the time to provide feedback.

1 Like
7

this is great I agree! ty.