Simplified zig build --help output

Brainstorming
1

I think it would be quite nice if there was a simplified version of the output of zig build --help just displaying the project-specific stuff (steps and options):

$ zig build --help

Usage: zig build [steps] [options]

Steps:
  install (default)            Copy build artifacts to prefix path
  uninstall                    Remove build artifacts from prefix path
  clean                        Delete previously generated files.
  run                          Build and run the main program.

Project-Specific Options:
  -Dtarget=[string]            The CPU architecture, OS, and ABI to build for
  -Dcpu=[string]               Target CPU features to add or subtract
  -Doptimize=[enum]            Prioritize performance, safety, or binary size (-O flag)
                                 Supported Values:
                                   Debug
                                   ReleaseSafe
                                   ReleaseFast
                                   ReleaseSmall

Run zig build --more-help for additional general options.
8 Likes
2

Strong agree. Project specific options get lost in the noise now.

1 Like
3

Another way: zig build help

4

By the way - why does showing this help require build.zig to present in cwd?
I did not want to build anything, I just wanted to get some help about build command,
but I see this:

$ zig build --help
info: Initialize a 'build.zig' template file with `zig init-lib` or `zig init-exe`,
or see `zig --help` for more options.
error: No 'build.zig' file found, in the current directory or any parent directories.
5

I think it’s because zig build is exclusively a tool to build / process / test a project as per the instructions in a build.zig file. It also needs to process the build.zig even for the help output because it tailors the help output based on the contents of build.zig.

1 Like
6

I agree that there is currently a ton of noise. So much noise, that I didn’t realize that half of this is already solved until about a week ago. There is zig build --list-steps (or zig build -l)

$ zig build --list-steps
  test                         Run ziglua tests
  install-example-interpreter  Install interpreter example
  run-example-interpreter      Run interpreter example
  install-example-zig-function Install zig-function example
  run-example-zig-function     Run zig-function example
  docs                         Build and install the documentation

It is missing the Project-Specific Options section though. This seems like a reasonable issue to open on GitHub. Not sure if the --list-steps should include the options output. Maybe a new flag? --info? --project-info? Not sure…

2 Likes
7

I was about to open an issue, but now I’m thinking that a good solution not requiring any new flags would be to just move the Project-Specific Options section up just below the Steps section of zig build --help output. Although you’d still get the tons of other options scrolling by, I think users have come to expect just scrolling up in such long help listings to find the most relevant / frequently-used info at the top.

2 Likes
8

I kind of would like a --list gaps where gaps is a nice mnemonic for:
General (Options)
Advanced (Options)
Project (Options)
[Specific] Steps (Options / Available)

--list ga would only print General and Advanced, you could either pick this order (gaps) or make it depend on the order of the letters.

I think gaps order kind of makes sense, because as a terminal user you expect to get the most important information last, because that is what you can see when you get to write your next command.

As the language gets more stable the general and advanced options will change less often, so the important ones will just be learned over time and you won’t need to look them up. While the Project specific options and Steps will always change and need to be looked up again and again for different projects.

Then when you really need to lookup advanced options, you can take the time to scroll up, or use something like zig build -h | less to pipe the output to a pager allowing you to start reading from the top.

9

I kinda understand this intuitively, but take the list of steps from your example
(install, uninstall, clean and run) - does Zig really need compiling build.zig
to print this list (including descriptions)? I can not see anything that is specific
to particular project in this text.

10

Only the install and uninstall steps are always there, the rest are project-specific:

$ cat build.zig                                                                                                                    
const std = @import("std");

pub fn build(_: *std.Build) void {}

$ zig build --list-steps                                                                                                           
  install (default)            Copy build artifacts to prefix path
  uninstall                    Remove build artifacts from prefix path
1 Like
11

The problem I find with providing this info behind a specific flag and not the intuitive --help or -h is that you have a chicken-and-egg situation where you need to know the flag to list the flags. I do find the idea of moving both the Steps and Project-Specific Options sections down to the bottom so they are visible after the scrolling is done to be a great idea. Rust’s cargo --help does this with what it calls its commands.

3 Likes
12

Another issue with this is you can remove the install and uninstall steps, so it would be inaccurate to assume those are always present. I do this in Ziglua in my reply above

1 Like