Add all options to mach run -- --help

[peterjoel]

The full list of options is at:
https://github.com/servo/servo/blob/master/components/util/opts.rs#L514-L553

These should be documented in mach --help.

Possible libraries that could be used to handle this:

• https://crates.io/crates/clap
• https://crates.io/crates/argparse
• https://crates.io/crates/docopt / https://crates.io/crates/docopt_macros

[cbrewster]

I would like to work on this one.

[frewsxcv]

@ConnorGBrewster Go for it! Let us know if you need any assistance 💁

[cbrewster]

Currently you can print out the list of these options using

./mach run -d -- --help

My question is, should this be called to get the run options and append them to the end of the normal ./mach --help or should this same option list be maintained separately in python just for the purpose of printing the options?

If we go with the first option, it would require Servo to have been built at least once for ./mach --help to print the running options.

[jdm]

I don't actually know if we can get ./mach help to work the way the original comment describes. I think we should focus on ./mach run -- --help to start.

[jdm]

Although the fact that ./mach run -d -- --help is required to get to this list is really sucky from a UX point of view.

[cbrewster]

@jdm Currently running ./mach run -d -- --help already outputs:

Usage: servo [ options ... ] [URL]
    where options include

Options:
    -c, --cpu           CPU painting (default)
    -g, --gpu           GPU painting
    -o, --output output.png
                        Output file
    -s, --size 512      Size of tiles
        --device-pixel-ratio 
                        Device pixels per px
    -t, --threads 1     Number of paint threads
    -p, --profile [10]  Profiler flag and output interval
    -m, --memory-profile [10]
                        Memory profiler flag and output interval
    -x, --exit          Exit after load flag
    -y, --layout-threads 1
                        Number of threads to use for layout
    -i, --nonincremental-layout 
                        Enable to turn off incremental layout.
        --no-ssl        Disables ssl certificate verification.
        --userscripts []
                        Uses userscripts in resources/user-agent-js, or a
                        specified full path
        --user-stylesheet file.css
                        A user stylesheet to be added to every document
    -z, --headless      Headless mode
    -f, --hard-fail     Exit on thread failure instead of displaying
                        about:failure
        --devtools [6000]
                        Start remote devtools server on port
        --webdriver [7000]
                        Start remote WebDriver server on port
        --resolution 800x600
                        Set window resolution.
    -u, --user-agent NCSA Mosaic/1.0 (X11;SunOS 4.1.4 sun4m)
                        Set custom user agent string (or android / gonk /
                        desktop for platform default)
    -M, --multiprocess  Run in multiprocess mode
    -S, --sandbox       Run in a sandbox if multiprocess
    -Z, --debug         A comma-separated string of debug options. Pass help
                        to show available options.
    -h, --help          Print this message
        --resources-path /home/servo/resources
                        Path to find static resources
        --content-process servo-ipc-channel.abcdefg
                        Run as a content process and connect to the given pipe
        --pref dom.mozbrowser.enabled
                        A preference to set to enable
    -b, --no-native-titlebar 
                        Do not use native titlebar
    -w, --webrender     Use webrender backend
    -G, --graphics gl   Select graphics backend (gl or es2)

[frewsxcv]

Is there a way to make the run flags appear in addition to the mach flags?

e.g., when one runs ./mach run --help, then the (current) output from ./mach run --help and ./mach run -d -- --help get printed

[jdm]

That would probably require special integration with mach. Maybe the place to start looking is _handle_main_help in python/mach/mach/dispatcher.py?

[cbrewster]

If one runs ./mach run --help should the options be printed from running the debug or release build of Servo? And if Servo has not been built, what should be printed?

[wafflespeanut]

I think it'd be better if mach initially checks for any one Servo build (let it be debug or release) - just put a note at the top indicating which build. If there's no build in the possible paths, then exit with the usual message (the one we get for ./mach run -[d|r]). If there are two builds, then we should probably prefer release.

[cbrewster]

It looks like I could do this by using the get_binary_path() function from command_base.py; however, command_base.py is inside the servo folder while the code to print the help menu is back a directory and then into the mach folder. Should I just rewrite a similar function to get_binary_path() in the mach portion?

[frewsxcv]

I wouldn't modify anything in python/mach/. It's upstream from Gecko and shouldn't have any Servo specific code in there (or any changes at all for that matter), from what I understand. I haven't looked at code, so I don't have any great suggestion either :-/

[cbrewster]

I think I will hold off on this one until we figure out how/if this should be done.

[nox]

This is still true, right?