doc: document zig compiler commands and environment variables

[perillo]

Currently there is no documentation about the zig command (excluding zig build documented in the language reference).
There is also no documentation about supported environment variables:
ZIG_LIB_DIR, ZIG_GLOBAL_CACHE_DIR, ZIG_LOCAL_CACHE_DIR and ZIG_LIBC.

Another problem is the interaction of the global and local cache:

1. Why there is the need of a local cache?
2. Can they point to the same directory?
3. Why "build output type" commands honor ZIG_LOCAL_CACHE_DIR
   but zig build ignores it?

Thanks.

[nektro]

running zig with no arguments will display a help menu

[matu3ba]

Why there is the need of a local cache?

libcs, which are compiled lazily upon request, belong into global cache. Same goes for compiler_rt routines.
Project things generally dont belong into the global cache, unless the user specifies so.
These things feel alot like implementation details, not language details to me.

Can they point to the same directory?

Yes. See my PR and surrounding code for planned changes, although not finalized (outstanding question on libstd wrt. TmpDir https://github.com/ziglang/zig/pull/11743/files#diff-d924ca21d81d7d5a59eb9e10d3e2689c4c58a7e28e6ecce6a064701666f5a730R2582, exposing functionality in libstd etc).

Why "build output type" commands honor ZIG_LOCAL_CACHE_DIR but zig build ignores it?

Environment variables are quick hacks, whereas a build.zig is a declarative user-configurable build system library. There is a proper interface for setting the cache_dir and you can hack around with environment variables all you want by reading them with some code.
You can also set a more readable and explicit override, so I dont see the use case.

To me these things belong into a guide on the build systems, which are tightly connected to the cache system. And not into the language reference. However, for now it might make sense to add them nevertheless into a dedicated section and later move them.

UPDATE: Some basic overview should go into the langref though. This feels like details creep, which does not keep focus on the language aspects though.

[perillo]

@matu3ba Thanks for the clarification.
Just some additional info:

1. About the global/local cache: currently the problem is that I don't want cached data to be written where user data is (the main reason is to exclude cached data from the backup). It should simply go to the user cache directory.

2. About the guide on the build system, currently it is available in https://ziglang.org/documentation/master/#Zig-Build-System
   IMHO, the language reference is different from the language specification, so some details about the language driver should be ok.

[matu3ba]

It should simply go to the user cache directory.

Without a build.zig and with the PR it will go into the user cache directory as global cache.
Otherwise, an override is needed for zig build. The main problem such a change would create is that you will have either the global cache cluttered with all builds and the need to regenerate the libcs and compiler_rt every time (not only when you work on compiler development).
Also, it makes searching content in cache more annoying or an annoying cache to find the cache will be needed (think of directory with hashes instead of zig-cache as name). Otherwise, the path would need to be represented in directory structure, which is a horrible user experience.

Though personally I feel like adding stuff to /tmp or the tmp directory on Windows could be more convenient.