Document intended use case

[andybalholm]

One thing that is missing from the project goals section in the documentation is the target use case. The use case makes a huge difference in how you approach the task of transpiling C to Go. Consider the difference between github.com/rsc/c2go (use case: convert Go compiler and runtime to Go, and leave the C version behind) and modernc.org/ccgo (use case: call C libraries, like sqlite, from Go without using CGo).

I found this much explanation of the use case in a Reddit comment:

The main idea for this project was to have cxgo download the latest commit, transpile it, and then push it to the go repo. Then by hand a developer can write an idiomatic and stable api on top of that others can use. This way future updates to the c project can be incorporated by just running the tool again.

So the use case appears to be basically in the "call C libraries without CGo" camp.

[dennwc]

You are totally right, use cases should be in the projects goals section.

But having said that, my main use case for writing this tool was to actually convert one large C project and leave it behind. Thus, the tool can actually cover both.

[andybalholm]

That makes sense. The principles of operation are broadly similar to rsc/c2go, so it's not surprising that it was developed for a similar project.

A tool developed for permanently converting a project to Go can be used for calling libraries without CGo, but not the other way around. The reason for this is that in the library use case, universality and and automatic operation are inevitably prioritized above readability and maintainability.

So if you want cxgo to remain usable for permanent conversions, you will need to clearly state that goal, and consistently refuse "improvements" that make it easier or more universal, but make the output more like what I call "asm.go" by analogy with asm.js.

[dennwc]

Definitely! I currently list as "keep output human-readable", but that might be ambiguous indeed. Will change that.