add documentation for the zig build system

[andrewrk]

extracted from #367

• explain purpose, it's supposed to replace make/cmake
• example of building a zig executable
• example of building a C library
• go over all the API in std/build.zig and make sure it's all documented
• fix #1035

[andrewrk]

After reviewing #4402 I realized this is actually a rather difficult issue, and so removed the "contributor friendly" label. Sorry about that.

[matjam]

If we could document at least the bare minimum things people might want to be able to do, that would be cool.

• build an executable
• build a zig library
• build an executable that depends on a zig library somewhere else
• build an executable that depends on a header not in a standard path
• link to a library that is not in a standard path

[paulespinosa]

@MasterQ32 has a "zig build explained" series at https://zig.news/xq/zig-build-explained-part-1-59lf which I think the contents should be moved, with @MasterQ32's permission, to either a page on ziglang.org or added to the language reference depending on length. I lean towards having it a separate page because it documents the tool more than the language.

[janie314]

Does this resolve the issue? https://ziglang.org/learn/build-system/

[matjam]

It does for me. Awesome work! Thank you!

[carlosneves0]

• How to execute an external shell command?

If the purpose is to replace make, I believe this is a missing point. I don't yet know how to spawn a child-process with zig.

Also, inevitably, the build system relates to the dependency management system. The reason I want to execute an external command is to git clone an external dependency as an automated build-step.