| // Copyright 2018 The Fuchsia Authors. All rights reserved. | |
| // Use of this source code is governed by a BSD-style license that can be | |
| // found in the LICENSE file. | |
| #include "src/developer/debug/zxdb/console/command_line_options.h" | |
| #include <lib/cmdline/args_parser.h> | |
| #include <filesystem> | |
| #include <iostream> | |
| #include <system_error> | |
| namespace zxdb { | |
| namespace { | |
| // Appears at the top of the --help output above the switch list. | |
| const char kHelpIntro[] = R"(zxdb [ <options> ] | |
| For information on using the debugger, type "help" at the interactive prompt. | |
| Options | |
| )"; | |
| const char kUnixConnectHelp[] = R"( --unix-connect=<filepath> | |
| -u <filepath> | |
| Attempts to connect to a debug_agent through a unix socket.)"; | |
| const char kLocalHelp[] = R"( --local | |
| -l | |
| Runs the built-in local debug_agent for debugging the local system. Only | |
| supported on x64 Linux. | |
| In this mode, any non-switch parameters (or anything after '--') will be | |
| treated as the program to debug and its parameters.)"; | |
| const char kConnectHelp[] = R"( --connect=<host>:<port> | |
| -c <host>:<port> | |
| Attempts to connect to a debug_agent running on the given host/port.)"; | |
| const char kCoreHelp[] = R"( --core=<filename> | |
| Attempts to open a core file for analysis.)"; | |
| const char kDebugModeHelp[] = R"( --debug-mode | |
| -d | |
| Output debug information about zxdb. | |
| Should only be useful for people developing zxdb.)"; | |
| const char kConsoleModeHelp[] = R"( --console-mode | |
| The style in which zxdb interacts with the console. Valid values are | |
| "shell" (default), "embedded", and "embedded-interactive".)"; | |
| const char kEmbeddedModeContextHelp[] = R"( --embedded-mode-context | |
| A short contextual string shown to the user when zxdb breaks out of | |
| Embedded mode. This is typically something that the user would expect | |
| to need to debug e.g. "test failure" or "crash". If unspecified, the | |
| exception that caused the debugger to appear will be shown.)"; | |
| const char kHelpHelp[] = R"( --help | |
| -h | |
| Prints all command-line switches.)"; | |
| const char kAttachHelp[] = R"( --attach=<koid|filter> | |
| -a <koid|filter> | |
| Attaches to the given process or creates a filter that matches current | |
| and future processes. The argument will be parsed in the same way as the | |
| "attach" command in the console. Multiple attaches can be specified to | |
| match more than one process.)"; | |
| const char kConfigFileHelp[] = R"( --config-file=<file> | |
| Reads a script file from a file. The file must contains valid zxdb | |
| commands as they would be input from the command line. They will be | |
| executed sequentially without waiting for completion.)"; | |
| const char kScriptFileHelp[] = R"( --script-file=<file> | |
| -S <file> | |
| Reads and executes a script file. A script file is a sequence of plain | |
| text lines. Lines beginning with "[zxdb]" are interpreted as commands to | |
| be interpreted. What follows each of these lines is any number of lines | |
| (with no prefix) that will be fuzzy matched against the output of the | |
| prior command before executing the next command (again on a line starting | |
| with "[zxdb]"). This is different than --config-file since it waits on | |
| some output of each command before executing the next. | |
| See examples in //src/developer/debug/examples. | |
| )"; | |
| const char kExecuteCommandHelp[] = R"( --execute=<command> | |
| -e <command> | |
| Execute one zxdb command. Multiple commands will be executed sequentially.)"; | |
| const char kSymbolIndexHelp[] = R"( --symbol-index=<path> | |
| Populates --ids-txt and --build-id-dir using the given symbol-index file, | |
| which defaults to ~/.fuchsia/debug/symbol-index.json. The file should be | |
| created and maintained by the "symbol-index" host tool.)"; | |
| const char kSymbolPathHelp[] = R"( --symbol-path=<path> | |
| -s <path> | |
| Adds the given directory or file to the symbol search path. Multiple | |
| -s switches can be passed to add multiple locations. When a directory | |
| path is passed, the directory will be enumerated non-recursively to | |
| index all ELF files. When a file is passed, it will be loaded as an ELF | |
| file (if possible).)"; | |
| const char kBuildIdDirHelp[] = R"( --build-id-dir=<path> | |
| Adds the given directory to the symbol search path. Multiple | |
| --build-id-dir switches can be passed to add multiple directories. | |
| The directory must have the same structure as a .build-id directory, | |
| that is, each symbol file lives at xx/yyyyyyyy.debug where xx is | |
| the first two characters of the build ID and yyyyyyyy is the rest. | |
| However, the name of the directory doesn't need to be .build-id.)"; | |
| const char kIdsTxtHelp[] = R"( --ids-txt=<path> | |
| Adds the given file to the symbol search path. Multiple --ids-txt | |
| switches can be passed to add multiple files. The file, typically named | |
| "ids.txt", serves as a mapping from build ID to symbol file path and | |
| should contain multiple lines in the format of "<build ID> <file path>".)"; | |
| const char kSymbolCacheHelp[] = R"( --symbol-cache=<path> | |
| Directory where we can keep a symbol cache, which defaults to | |
| ~/.fuchsia/debug/symbol-cache. If a symbol server has been specified, | |
| downloaded symbols will be stored in this directory. The directory | |
| structure will be the same as a .build-id directory, and symbols will | |
| be read from this location as though you had specified | |
| "--build-id-dir=<path>".)"; | |
| const char kPrivateSymbolServerHelp[] = R"( --symbol-server=<url> | |
| Adds the given URL to symbol servers. Symbol servers host the debug | |
| symbols for prebuilt binaries and dynamic libraries. Servers specified | |
| with this option will be required to authenticate against the given url.)"; | |
| const char kPublicSymbolServerHelp[] = R"( --public-symbol-server=<url> | |
| Adds the given URL to symbol servers. Symbol servers host the debug | |
| symbols for prebuilt binaries and dynamic libraries.)"; | |
| using ::analytics::core_dev_tools::kAnalyticsHelp; | |
| using ::analytics::core_dev_tools::kAnalyticsShowHelp; | |
| const char kVersionHelp[] = R"( --version | |
| -v | |
| Prints the version.)"; | |
| const char kEnableDebugAdapterHelp[] = R"( --enable-debug-adapter | |
| Starts the debug adapter that serves debug adapter protocol. | |
| This is useful for connecting the debugger with an IDE.)"; | |
| const char kDebugAdapterPortHelp[] = R"( --debug-adapter-port=<port> | |
| Uses this port number to serve debug adapter protocol. | |
| By default 15678 is used.)"; | |
| const char kAutoAttachLimboHelp[] = R"( --auto-attach-limbo | |
| Enables automatically attaching to all processes found in Process Limbo | |
| upon successful connection.)"; | |
| const char kSignalWhenReadyHelp[] = R"( --signal-when-ready=<pid> | |
| Send SIGUSR1 to pid when ready for interactive commands.)"; | |
| const char kStreamFileHelp[] = R"( --stream-file=<path> | |
| Stream the contents of the given file, usually a pipe, to the console.)"; | |
| } // namespace | |
| cmdline::Status ParseCommandLine(int argc, const char* argv[], CommandLineOptions* options, | |
| std::vector<std::string>* params) { | |
| using analytics::core_dev_tools::AnalyticsOption; | |
| using analytics::core_dev_tools::ParseAnalyticsOption; | |
| cmdline::ArgsParser<CommandLineOptions> parser; | |
| parser.AddSwitch("connect", 'c', kConnectHelp, &CommandLineOptions::connect); | |
| parser.AddSwitch("unix-connect", 'u', kUnixConnectHelp, &CommandLineOptions::unix_connect); | |
| parser.AddSwitch("local", 'l', kLocalHelp, &CommandLineOptions::local); | |
| parser.AddSwitch("core", 0, kCoreHelp, &CommandLineOptions::core); | |
| parser.AddSwitch("debug-mode", 'd', kDebugModeHelp, &CommandLineOptions::debug_mode); | |
| parser.AddSwitch("console-mode", 0, kConsoleModeHelp, &CommandLineOptions::console_mode); | |
| parser.AddSwitch("embedded-mode-context", 0, kEmbeddedModeContextHelp, | |
| &CommandLineOptions::embedded_mode_context); | |
| parser.AddSwitch("attach", 'a', kAttachHelp, &CommandLineOptions::attach); | |
| parser.AddSwitch("config-file", 0, kConfigFileHelp, &CommandLineOptions::config_files); | |
| parser.AddSwitch("script-file", 'S', kScriptFileHelp, &CommandLineOptions::script_file); | |
| parser.AddSwitch("execute", 'e', kExecuteCommandHelp, &CommandLineOptions::execute_commands); | |
| parser.AddSwitch("symbol-index", 0, kSymbolIndexHelp, &CommandLineOptions::symbol_index_files); | |
| parser.AddSwitch("symbol-path", 's', kSymbolPathHelp, &CommandLineOptions::symbol_paths); | |
| parser.AddSwitch("build-id-dir", 0, kBuildIdDirHelp, &CommandLineOptions::build_id_dirs); | |
| parser.AddSwitch("ids-txt", 0, kIdsTxtHelp, &CommandLineOptions::ids_txts); | |
| parser.AddSwitch("symbol-cache", 0, kSymbolCacheHelp, &CommandLineOptions::symbol_cache); | |
| parser.AddSwitch("symbol-server", 0, kPrivateSymbolServerHelp, | |
| &CommandLineOptions::private_symbol_servers); | |
| parser.AddSwitch("public-symbol-server", 0, kPublicSymbolServerHelp, | |
| &CommandLineOptions::public_symbol_servers); | |
| parser.AddSwitch("version", 'v', kVersionHelp, &CommandLineOptions::requested_version); | |
| parser.AddSwitch("analytics", 0, kAnalyticsHelp, &CommandLineOptions::analytics); | |
| parser.AddSwitch("analytics-show", 0, kAnalyticsShowHelp, &CommandLineOptions::analytics_show); | |
| parser.AddSwitch("enable-debug-adapter", 0, kEnableDebugAdapterHelp, | |
| &CommandLineOptions::enable_debug_adapter); | |
| parser.AddSwitch("debug-adapter-port", 0, kDebugAdapterPortHelp, | |
| &CommandLineOptions::debug_adapter_port); | |
| parser.AddSwitch("auto-attach-limbo", 0, kAutoAttachLimboHelp, | |
| &CommandLineOptions::auto_attach_limbo); | |
| parser.AddSwitch("signal-when-ready", 0, kSignalWhenReadyHelp, | |
| &CommandLineOptions::signal_when_ready); | |
| parser.AddSwitch("stream-file", 0, kStreamFileHelp, &CommandLineOptions::stream_files); | |
| // Special --help switch which doesn't exist in the options structure. | |
| bool requested_help = false; | |
| parser.AddGeneralSwitch("help", 'h', kHelpHelp, [&requested_help]() { requested_help = true; }); | |
| cmdline::Status status = parser.Parse(argc, argv, options, params); | |
| if (status.has_error()) | |
| return status; | |
| // Handle --help switch since we're the one that knows about the switches. | |
| if (requested_help) | |
| return cmdline::Status::Error(kHelpIntro + parser.GetHelp()); | |
| // Default values for vector types. | |
| if (const char* home = std::getenv("HOME"); home) { | |
| std::string home_str = home; | |
| if (!options->symbol_cache) { | |
| options->symbol_cache = home_str + "/.fuchsia/debug/symbol-cache"; | |
| } | |
| if (options->symbol_index_files.empty()) { | |
| std::error_code ec; | |
| std::string symbol_index = home_str + "/.fuchsia/debug/symbol-index.json"; | |
| if (std::filesystem::exists(symbol_index, ec)) { | |
| options->symbol_index_files.push_back(symbol_index); | |
| } | |
| } | |
| std::string zxdbrc = home_str + "/.fuchsia/debug/zxdbrc"; | |
| std::error_code ec; | |
| if (std::filesystem::exists(zxdbrc, ec)) { | |
| // zxdbrc is expected to execute first. | |
| options->config_files.insert(options->config_files.begin(), zxdbrc); | |
| } | |
| } | |
| return cmdline::Status::Ok(); | |
| } | |
| } // namespace zxdb |