Sharpmake needs better documentation

[Zathyy]

Note: i really love this build tool, but its lacking documentation.

its very unclear how to do things.

only way i can find out how to do things is either create a issue wait a few days or go through source
or just typing conf. and seeing what suggestions vs gives me, its very unclear.

[bchampoux]

The typical way we use it at Ubisoft in a large project: we write CommonProject and CommonSolution base classes that do most of the multi-platform setup we want, and then we add project classes derived from CommonProject for each module/vcxproj we want to generate. We do a LOT of copy-paste and typing conf. or target. to see what auto-completes. After a while, you get used to the Configure overload pattern (we have some ideas in our samples).

[Zathyy]

i mean ye, thats how i have it now kinda, but it would still be nice with more examples and more documentation.

[Sharlock93]

I have been using Sharpmake professionally for more than 3 years. Used it across multiple platforms and engines. If you have a set of questions and/or areas you want better documentation for, more than happy to help write down some stuff.

[xoorath]

Hey,

I agree with @Zathyy on this. I have also used Sharpmake professionally and have heard similar grumblimgs from my colleagues at Ubisoft, Turn 10 and Playground Games.

For me there are two main areas that I would want better docs for:

1. An exhaustive API reference. What types, attributes, functions and members exist.
2. For the special strings that get replaced: what are all of the valid substitutions, an example value from that substitution, and what contexts can they be used?

I think FASTBuild is a good example of a project with similar complexity that does a decent job documenting it's features exhaustively. It's imperfect, gets out of date, but it's an essential resource for writing bff files.

I will say the detailed examples provided are very helpful. I think that's a great starting point but I would advocate for some more in depth docs.

[jspelletier]

Hi,
I agree that the docs are not really good(some parts are in fact very bad). I also would like eventually to put a fake game engine as a sample.

The problem is we don't have any Sharpmake development team. We only have a few maintainers. I put generally around 1-4h of my time each week on sharpmake except for some development burst about once a year to improve performance of our sharpmake projects generation with the anvil pipeline game engine.

[xoorath]

Very understandable; thank you for your open source work.

Have you considered spending some of your limited time outlining help requests for the community? For example requesting cleanup of particular documents, design of a new game engine sample, a pitch for doc generation, etc?

[bchampoux]

That's actually a good idea.
We know the weak spots, we just lack the resources to address them. We barely have enough time to tackle our own internal requests. We're happy that Sharpmake is alive though, and for us there's nothing that can replace Sharpmake at what it does so it's going to live for a long time.

[jspelletier]

I plan to try to use claude code for improving docs and samples. Hopefully I can come out with something much better than we currently have. But if some people want to help on that subject we would be dumb to refuse any help!

[Sharlock93]

I have most of my evenings free, more than happy to take on the challenge. We can create some tasks to track.
My plan was to first go through the main 5 classes most people deal with, Project, Solution, their configuration and Target.
Then document Options and the global options classes.

[jspelletier]

Then I say, go for it!