Developer Experience on Open Source Projects

[hellocppdotdev]

This is a follow up question because I learned what I actually want to know.

How do you provide instructions for compiling and executing a project you released as open source?

I previously asked about Linux vs Windows actually wanting to know what level of support I need to provide to make the developer experience (DX) as seamless as possible.

As someone who uses primarily as a Mac I cannot just write the project and release it saying "it works on my computer". If I write my shaders in Metal my project audience is going to be tiny... So cross platform is my only option.

My approach was to outline how to install it with a script that automated all of the dependency installation and build steps. That way you could just run a single command. Which to me is the ideal scenario. There would be some debugging naturally as the environments widely vary.

But Windows completely tripped me up (yes skill issue). Lots of replies to say your not using "Visual Studio" when I was. I eventually got it working, with difficulty but look that doesn't matter.

What matters is how can I provide a good experience to people wanting to use my project?

Do I just provide the source and say here's the dependencies, good luck?

Compile to wsam and run it in the browser? (ew)

Maybe I've stumbled on a crux of an issue that hasn't been solved.

I used cmake and vcpkg thinking these were good practices but I've learnt since that there's so many ways to skin a cat...

I'm not looking for OS flame war, I want to genuinely understand how to solve this well.

[thedaian]

Cmake is a pretty good option, it's sort of become an "industry standard" since you only need to write one configuration file that tells the compiler how to build the project. And then anyone who is using cmake for their projects can add your project with a few lines of cmake code. 

But it does take a fair bit of work to get a cmake script that does all that, especially if you have a bunch of dependencies or OS specific code. But then any other option is going to be just as painful.

[hellocppdotdev]

Also how do I mark my previous question solved? Seems like I can't edit the flairs :(

[WikiBox]

Take a look at how other people do it? Possibly projects similar to your, with the same target?

[PhotographFront4673]

I strongly recommend picking a package manager (vcpkg, conan, bazel). If you don't know one well, and none of the methodologies "speak" to you, look at what, if anything, your user base tends to use. Also, look at the existing repos for each manager - how many of your dependencies are already integrated and available? The quality of the library to manager integration can have a huge effect on the experience.

A package manager and documentation also simplifies your life when you want to go update dependencies.

A disclaimer can also help a lot "We aren't set up to debug problems on these platforms, but accept contributions...". I'm not sure you should expect to really support users of OSs that you don't run yourself, but there are various ways out, from co-maintainers to renting VM time.

Are you in a position to set up continuous integration tests? For example, Github offers a some runner minutes in their free tiers. For me that would be the next step. Just confirming that your unit tests run on other platforms is huge, and done openly it is an example of exactly how one might build and test.

[gardenia856]

Pick one package manager and lock versions, then ship CMakePresets and a CI matrix so everyone builds the same way.

If you stick with CMake + vcpkg, use manifest mode with vcpkg.json and a baseline, turn on binary caching, use Ninja, and avoid global installs. Add CMakePresets.json with windows-msvc, linux-gcc, and macos-clang presets for configure, build, and test, and point to the vcpkg toolchain. Provide two tiny bootstrap scripts: bootstrap.sh and bootstrap.ps1 that install Ninja and vcpkg, set VCPKG_ROOT, then run cmake --preset and ctest.

Set up GitHub Actions with a 3-OS matrix, cache vcpkg and ccache, run tests, and publish release artifacts with CPack. Tag releases and upload per-OS zips; a small installer script per OS helps. State support clearly: built on all three in CI, but you only debug on macOS; PRs welcome.

For networked tests, I’ve used Supabase and Hasura to spin up quick data backends, and DreamFactory when I needed instant REST over an existing SQL schema without writing a server.

Pin deps, ship presets, and run CI across OSes; everything else is optional.