GP-4617: Moving most documentation from connectors to Help.

NationalSecurityAgency · May 23, 2024 · 90f3725 · 90f3725
1 parent 8734c48
commit 90f3725
Show file tree

Hide file tree

Showing 16 changed files with 360 additions and 177 deletions.
diff --git a/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-dbgeng.bat b/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-dbgeng.bat
@@ -1,21 +1,20 @@
 ::@title dbgeng
 ::@desc <html><body width="300px">
 ::@desc   <h3>Launch with <tt>dbgeng</tt> (in a Python interpreter)</h3>
-::@desc   <p>This will launch the target on the local machine using <tt>dbgeng.dll</tt>. Typically,
-::@desc   Windows systems have this library pre-installed, but it may have limitations, e.g., you
-::@desc   cannot use <tt>.server</tt>. For the full capabilities, you must install WinDbg.</p>
-::@desc   <p>Furthermore, you must have Python 3 installed on your system, and it must have the
-::@desc   <tt>pybag</tt> and <tt>protobuf</tt> packages installed.</p>
+::@desc   <p>
+::@desc     This will launch the target on the local machine using <tt>dbgeng.dll</tt>.
+::@desc     For setup instructions, press <b>F1</b>.
+::@desc   </p>
 ::@desc </body></html>
 ::@menu-group local
 ::@icon icon.debugger
 ::@help TraceRmiLauncherServicePlugin#dbgeng
-::@env OPT_PYTHON_EXE:str="python" "Path to python" "The path to the Python 3 interpreter. Omit the full path to resolve using the system PATH."
+::@env OPT_PYTHON_EXE:str="python" "Python command" "The path to the Python 3 interpreter. Omit the full path to resolve using the system PATH."
 :: Use env instead of args, because "all args except first" is terrible to implement in batch
 ::@env OPT_TARGET_IMG:str="" "Image" "The target binary executable image"
 ::@env OPT_TARGET_ARGS:str="" "Arguments" "Command-line arguments to pass to the target"
 ::@env OPT_USE_DBGMODEL:bool=true "Use dbgmodel" "Load and use dbgmodel.dll if it is available."
-::@env WINDBG_DIR:str="" "Path to dbgeng" "Path to dbgeng and associated DLLS (if not Windows Kits)."
+::@env WINDBG_DIR:str="" "Path to dbgeng.dll directory" "Path containing dbgeng and associated DLLS (if not Windows Kits)."
 
 @echo off
 

diff --git a/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-ttd.bat b/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-ttd.bat
@@ -1,21 +1,20 @@
 ::@title ttd
 ::@desc <html><body width="300px">
 ::@desc   <h3>Launch with <tt>ttd</tt> (in a Python interpreter)</h3>
-::@desc   <p>This will launch the target on the local machine using <tt>dbgeng.dll</tt>. Typically,
-::@desc   Windows systems have this library pre-installed, but it may have limitations, e.g., you
-::@desc   cannot use <tt>.server</tt>. For the full capabilities, you must install WinDbg.</p>
-::@desc   <p>Furthermore, you must have Python 3 installed on your system, and it must have the
-::@desc   <tt>pybag</tt> and <tt>protobuf</tt> packages installed.</p>
+::@desc   <p>
+::@desc     This will launch the target on the local machine for time-travel debugging.
+::@desc     For setup instructions, press <b>F1</b>.
+::@desc   </p>
 ::@desc </body></html>
 ::@menu-group local
 ::@icon icon.debugger
 ::@help TraceRmiLauncherServicePlugin#dbgeng_ttd
-::@env OPT_PYTHON_EXE:str="python" "Path to python" "The path to the Python 3 interpreter. Omit the full path to resolve using the system PATH."
+::@env OPT_PYTHON_EXE:str="python" "Python command" "The path to the Python 3 interpreter. Omit the full path to resolve using the system PATH."
 :: Use env instead of args, because "all args except first" is terrible to implement in batch
 ::@env OPT_TARGET_IMG:str="" "Trace (.run)" "A trace associated with the target binary executable"
 ::@env OPT_TARGET_ARGS:str="" "Arguments" "Command-line arguments to pass to the target"
 ::@env OPT_USE_DBGMODEL:bool=true "Use dbgmodel" "Load and use dbgmodel.dll if it is available."
-::@env OPT_DBGMODEL_PATH:str="" "Path to dbgeng & \\ttd" "Path to dbgeng and associated DLLS (if not Windows Kits)."
+::@env OPT_DBGMODEL_PATH:str="" "Path to dbgeng.dll & \\ttd" "Path containing dbgeng and associated DLLS (if not Windows Kits)."
 
 @echo off
 

diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/local-gdb.sh b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/local-gdb.sh
@@ -17,17 +17,18 @@
 #@title gdb
 #@desc <html><body width="300px">
 #@desc   <h3>Launch with <tt>gdb</tt></h3>
-#@desc   <p>This will launch the target on the local machine using <tt>gdb</tt>. GDB must already
-#@desc   be installed on your system, and it must embed the Python 3 interpreter. You will also
-#@desc   need <tt>protobuf</tt> and <tt>psutil</tt> installed for Python 3.</p>
+#@desc   <p>
+#@desc     This will launch the target on the local machine using <tt>gdb</tt>.
+#@desc     For setup instructions, press <b>F1</b>.
+#@desc   </p>
 #@desc </body></html>
 #@menu-group local
 #@icon icon.debugger
 #@help TraceRmiLauncherServicePlugin#gdb
 #@enum StartCmd:str run start starti
 #@arg :str "Image" "The target binary executable image"
 #@args "Arguments" "Command-line arguments to pass to the target"
-#@env OPT_GDB_PATH:str="gdb" "Path to gdb" "The path to gdb. Omit the full path to resolve using the system PATH."
+#@env OPT_GDB_PATH:str="gdb" "gdb command" "The path to gdb. Omit the full path to resolve using the system PATH."
 #@env OPT_START_CMD:StartCmd="starti" "Run command" "The gdb command to actually run the target."
 #@env OPT_EXTRA_TTY:bool=false "Inferior TTY" "Provide a separate terminal emulator for the target."
 #@tty TTY_TARGET if env:OPT_EXTRA_TTY

diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/qemu-gdb.sh b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/qemu-gdb.sh
@@ -17,21 +17,21 @@
 #@title qemu + gdb
 #@desc <html><body width="300px">
 #@desc   <h3>Launch with <tt>qemu</tt> and connect with <tt>gdb</tt></h3>
-#@desc   <p>This will launch the target on the local machine using <tt>qemu</tt>. Then in a second
-#@desc   terminal, it will connect <tt>gdb</tt> to QEMU's GDBstub.
-#@desc   GDB must already be installed on your system, it must support your target architecture
-#@desc   (you may install <tt>gdb-multiarch</tt>), and it must embed the Python 3 interpreter. You
-#@desc   will also need <tt>protobuf</tt> installed for Python 3.
+#@desc   <p>
+#@desc     This will launch the target on the local machine using <tt>qemu</tt>.
+#@desc     Then in a second terminal, it will connect <tt>gdb</tt> to QEMU's GDBstub.
+#@desc     For setup instructions, press <b>F1</b>.
+#@desc   </p>
 #@desc </body></html>
 #@menu-group cross
 #@icon icon.debugger
 #@help TraceRmiLauncherServicePlugin#gdb_qemu
 #@arg :str "Image" "The target binary executable image"
 #@args "Arguments" "Command-line arguments to pass to the target"
-#@env GHIDRA_LANG_EXTTOOL_qemu:str="" "Path to qemu" "The path to qemu for the target architecture."
+#@env GHIDRA_LANG_EXTTOOL_qemu:str="" "QEMU command" "The path to qemu for the target architecture."
 #@env QEMU_GDB:int=12345 "QEMU Port" "Port for gdb connection to qemu"
 #@env OPT_EXTRA_QEMU_ARGS:str="" "Extra qemu arguments" "Extra arguments to pass to qemu. Use with care."
-#@env OPT_GDB_PATH:str="gdb-multiarch" "Path to gdb" "The path to gdb. Omit the full path to resolve using the system PATH."
+#@env OPT_GDB_PATH:str="gdb-multiarch" "gdb command" "The path to gdb. Omit the full path to resolve using the system PATH."
 #@env OPT_EXTRA_TTY:bool=false "QEMU TTY" "Provide a separate terminal emulator for the target."
 #@tty TTY_TARGET if env:OPT_EXTRA_TTY
 

diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/raw-gdb.sh b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/raw-gdb.sh
@@ -18,16 +18,16 @@
 #@no-image
 #@desc <html><body width="300px">
 #@desc   <h3>Start <tt>gdb</tt></h3>
-#@desc   <p>This will start <tt>gdb</tt> and connect to it. It will not launch
-#@desc   a target, so you can (must) set up your target manually.
-#@desc   GDB must already
-#@desc   be installed on your system, and it must embed the Python 3 interpreter. You will also
-#@desc   need <tt>protobuf</tt> and <tt>psutil</tt> installed for Python 3.</p>
+#@desc   <p>
+#@desc     This will start <tt>gdb</tt> and connect to it.
+#@desc     It will not launch a target, so you can (must) set up your target manually.
+#@desc     For setup instructions, press <b>F1</b>.
+#@desc   </p>
 #@desc </body></html>
 #@menu-group raw
 #@icon icon.debugger
 #@help TraceRmiLauncherServicePlugin#gdb_raw
-#@env OPT_GDB_PATH:str="gdb" "Path to gdb" "The path to gdb. Omit the full path to resolve using the system PATH."
+#@env OPT_GDB_PATH:str="gdb" "gdb command" "The path to gdb. Omit the full path to resolve using the system PATH."
 #@env OPT_ARCH:str="i386:x86-64" "Architecture" "Target architecture"
 
 if [ -d ${GHIDRA_HOME}/ghidra/.git ]

diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/remote-gdb.sh b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/remote-gdb.sh
@@ -18,25 +18,20 @@
 #@no-image
 #@desc <html><body width="300px">
 #@desc   <h3>Launch with local <tt>gdb</tt> and connect to a stub (e.g., <tt>gdbserver</tt>)</h3>
-#@desc   <p>This will start <tt>gdb</tt> on the local system and then use it to connect to the remote system. 
-#@desc   The actual command used is, e.g:</p>
-#@desc   <pre>target remote host:port</pre>
-#@desc   <p>It may be worth testing this manually to ensure everything is configured correctly.
-#@desc   GDB must be installed on your local system, it must be compatible with the remote system, 
-#@desc   and it must embed the Python 3 interpreter. You will also need <tt>protobuf</tt> installed 
-#@desc   for Python 3 on the local system. There are no Python requirements for the remote system.
-#@desc   Please ensure that Ghidra's current program and the target's image match.  Otherwise, the
-#@desc   modules may not map.</p>
+#@desc   <p>
+#@desc     This will start <tt>gdb</tt> on the local system and then use it to connect to the remote system. 
+#@desc     For setup instructions, press <b>F1</b>. 
+#@desc   </p>
 #@desc </body></html>
 #@menu-group remote
 #@icon icon.debugger
-#@help TraceRmiLauncherServicePlugin#gdb
+#@help TraceRmiLauncherServicePlugin#gdb_remote
 #@enum TargetType:str remote extended-remote
 #@env OPT_TARGET_TYPE:TargetType="remote" "Target" "The type of remote target"
 #@env OPT_HOST:str="localhost" "Host" "The hostname of the target"
 #@env OPT_PORT:str="9999" "Port" "The host's listening port"
 #@env OPT_ARCH:str="" "Architecture (optional)" "Target architecture override"
-#@env OPT_GDB_PATH:str="gdb" "Path to gdb" "The path to gdb on the local system. Omit the full path to resolve using the system PATH."
+#@env OPT_GDB_PATH:str="gdb" "gdb command" "The path to gdb on the local system. Omit the full path to resolve using the system PATH."
 
 if [ -d ${GHIDRA_HOME}/ghidra/.git ]
 then

diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdb.sh b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdb.sh
@@ -18,19 +18,10 @@
 #@title gdb via ssh
 #@desc <html><body width="300px">
 #@desc   <h3>Launch with <tt>gdb</tt> via <tt>ssh</tt></h3>
-#@desc   <p>This will launch the target on a remote machine using <tt>gdb</tt> via <tt>ssh</tt>.
-#@desc   GDB and an SSH server must already be installed and operational on the remote system, and
-#@desc   GDB must embed the Python 3 interpreter. The remote SSH server must be configured to allow
-#@desc   remote port forwarding. You will also need to install the following for GDB's embedded
-#@desc   version of Python:</p>
-#@desc   <ul>
-#@desc     <li><tt>ghidragdb</tt> - Ghidra plugin for GDB, available from the Debugger-agent-gdb
-#@desc         directory in Ghidra</li>
-#@desc     <li><tt>ghidratrace</tt> - Ghidra Trace RMI client for Python, available from the
-#@desc         Debugger-rmi-trace directory in Ghidra</li>
-#@desc     <li><tt>protobuf</tt> - available from PyPI</li>
-#@desc     <li><tt>psutil</tt> - available from PyPI</li>
-#@desc   </ul>
+#@desc   <p>
+#@desc     This will launch the target on a remote machine using <tt>gdb</tt> via <tt>ssh</tt>.
+#@desc     For setup instructions, press <b>F1</b>.
+#@desc   </p>
 #@desc </body></html>
 #@menu-group remote
 #@icon icon.debugger
@@ -41,7 +32,7 @@
 #@env OPT_HOST:str="localhost" "[User@]Host" "The hostname or user@host"
 #@env OPT_REMOTE_PORT:int=12345 "Remote Trace RMI Port" "A free port on the remote end to receive and forward the Trace RMI connection."
 #@env OPT_EXTRA_SSH_ARGS:str="" "Extra ssh arguments" "Extra arguments to pass to ssh. Use with care."
-#@env OPT_GDB_PATH:str="gdb" "Path to gdb" "The path to gdb on the remote system. Omit the full path to resolve using the system PATH."
+#@env OPT_GDB_PATH:str="gdb" "gdb command" "The path to gdb on the remote system. Omit the full path to resolve using the system PATH."
 #@env OPT_START_CMD:StartCmd="start" "Run command" "The gdb command to actually run the target."
 
 target_image="$1"

diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdbserver.sh b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdbserver.sh
@@ -18,16 +18,10 @@
 #@title gdb + gdbserver via ssh
 #@desc <html><body width="300px">
 #@desc   <h3>Launch with local <tt>gdb</tt> and <tt>gdbserver</tt> via <tt>ssh</tt></h3>
-#@desc   <p>This will start <tt>gdb</tt> on the local system and then use it to connect and launch
-#@desc   the target in <tt>gdbserver</tt> on the remote system via <tt>ssh</tt>. The actual command
-#@desc   used is, e.g:</p>
-#@desc   <pre>target remote | ssh user@host gdbserver - /path/to/image</pre>
-#@desc   <p>It may be worth testing this manually to ensure everything is configured correctly. An
-#@desc   SSH server and <tt>gdbserver</tt> must already be installed and operational on the remote
-#@desc   system. GDB must be installed on your local system, it must be compatible with the
-#@desc   <tt>gdbserver</tt> on the remote system, and it must embed the Python 3 interpreter. You
-#@desc   will also need <tt>protobuf</tt> installed for Python 3 on the local system. There are no
-#@desc   Python requirements for the remote system.</p>
+#@desc   <p>
+#@desc     This will start <tt>gdb</tt> on the local system and then use it to connect and launch the target in <tt>gdbserver</tt> on the remote system via <tt>ssh</tt>.
+#@desc     For setup instructions, press <b>F1</b>.
+#@desc   </p>
 #@desc </body></html>
 #@menu-group remote
 #@icon icon.debugger
@@ -36,9 +30,9 @@
 #@args "Arguments" "Command-line arguments to pass to the target"
 #@env OPT_HOST:str="localhost" "[User@]Host" "The hostname or user@host"
 #@env OPT_EXTRA_SSH_ARGS:str="" "Extra ssh arguments" "Extra arguments to pass to ssh. Use with care."
-#@env OPT_GDBSERVER_PATH:str="gdbserver" "Path to gdbserver (remote)" "The path to gdbserver on the remote system. Omit the full path to resolve using the system PATH."
+#@env OPT_GDBSERVER_PATH:str="gdbserver" "gdbserver command (remote)" "The path to gdbserver on the remote system. Omit the full path to resolve using the system PATH."
 #@env OPT_EXTRA_GDBSERVER_ARGS:str="" "Extra gdbserver arguments" "Extra arguments to pass to gdbserver. Use with care."
-#@env OPT_GDB_PATH:str="gdb" "Path to gdb" "The path to gdb on the local system. Omit the full path to resolve using the system PATH."
+#@env OPT_GDB_PATH:str="gdb" "gdb command" "The path to gdb on the local system. Omit the full path to resolve using the system PATH."
 
 if [ -d ${GHIDRA_HOME}/ghidra/.git ]
 then

diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/wine-gdb.sh b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/wine-gdb.sh
@@ -17,27 +17,18 @@
 #@title wine + gdb
 #@desc <html><body width="300px">
 #@desc   <h3>Launch with <tt>gdb</tt> and <tt>wine</tt></h3>
-#@desc   <p>This will launch the target on the local machine using <tt>gdb</tt> and <tt>wine</tt>.
-#@desc   GDB and Wine must already be installed on your system, and GDB must embed the Python 3
-#@desc   interpreter. You will also need <tt>protobuf</tt> and <tt>psutil</tt> installed for Python
-#@desc   3.</p>
-#@desc   <p>This operates by starting GDB on the Wine executable and passing arguments to launch a
-#@desc   Windows target. This may prevent GDB from processing the object file, because it is a PE
-#@desc   file, and most copies of GDB for UNIX will support only ELF. Nevertheless, Ghidra should
-#@desc   recognize the target and map it, giving you symbols and debug info in the front end, even
-#@desc   if not in the GDB CLI.</p>
-#@desc   <p>You will need to locate the <tt>wine</tt> executable, not the script, on your system. To
-#@desc   find it, either dissect the <tt>wine</tt> script or consult online documentation for your
-#@desc   distribution of Wine. There are often two executables, one for 32-bit targets and one for
-#@desc   64-bit targets. You must select the correct one.</p>
+#@desc   <p>
+#@desc     This will launch the target on the local machine using <tt>gdb</tt> and <tt>wine</tt>.
+#@desc     For setup instructions, press <b>F1</b>.
+#@desc   </p>
 #@desc </body></html>
 #@menu-group cross
 #@icon icon.debugger
 #@help TraceRmiLauncherServicePlugin#gdb_wine
 #@arg :str "Image" "The target binary executable image"
 #@args "Arguments" "Command-line arguments to pass to the target"
 #@env OPT_WINE_PATH:str="/usr/lib/wine/wine64" "Path to wine binary" "The path to the wine executable for your target architecture."
-#@env OPT_GDB_PATH:str="gdb" "Path to gdb" "The path to gdb. Omit the full path to resolve using the system PATH."
+#@env OPT_GDB_PATH:str="gdb" "gdb command" "The path to gdb. Omit the full path to resolve using the system PATH."
 #@env OPT_EXTRA_TTY:bool=false "Inferior TTY" "Provide a separate terminal emulator for the target."
 #@tty TTY_TARGET if env:OPT_EXTRA_TTY
 

diff --git a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/local-lldb.sh b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/local-lldb.sh
@@ -17,17 +17,18 @@
 #@title lldb
 #@desc <html><body width="300px">
 #@desc   <h3>Launch with <tt>lldb</tt></h3>
-#@desc   <p>This will launch the target on the local machine using <tt>lldb</tt>. LLDB must already
-#@desc   be installed on your system, and it must embed the Python 3 interpreter. You will also
-#@desc   need <tt>protobuf</tt> and <tt>psutil</tt> installed for Python 3.</p>
+#@desc   <p>
+#@desc     This will launch the target on the local machine using <tt>lldb</tt>.
+#@desc     For setup instructions, press <b>F1</b>.
+#@desc   </p>
 #@desc </body></html>
 #@menu-group local
 #@icon icon.debugger
 #@help TraceRmiLauncherServicePlugin#lldb
 #@enum StartCmd:str "process launch" "process launch --stop-at-entry"
 #@arg :str "Image" "The target binary executable image"
 #@args "Arguments" "Command-line arguments to pass to the target"
-#@env OPT_LLDB_PATH:str="lldb" "Path to lldb" "The path to lldb. Omit the full path to resolve using the system PATH."
+#@env OPT_LLDB_PATH:str="lldb" "lldb command" "The path to lldb. Omit the full path to resolve using the system PATH."
 #@env OPT_START_CMD:StartCmd="process launch" "Run command" "The lldb command to actually run the target."
 #@env OPT_EXTRA_TTY:bool=false "Target TTY" "Provide a separate terminal emulator for the target."
 #@tty TTY_TARGET if env:OPT_EXTRA_TTY

diff --git a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/remote-lldb.sh b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/remote-lldb.sh
@@ -18,23 +18,18 @@
 #@no-image
 #@desc <html><body width="300px">
 #@desc   <h3>Launch with local <tt>lldb</tt> and connect to a stub (e.g., <tt>gdbserver</tt>)</h3>
-#@desc   <p>This will start <tt>lldb</tt> on the local system and then use it to connect to the remote system. 
-#@desc   The actual command used is, e.g:</p>
-#@desc   <pre>gdb-remote host:port</pre>
-#@desc   <p>It may be worth testing this manually to ensure everything is configured correctly.
-#@desc   LLDB must be installed on your local system, it must be compatible with the remote system, 
-#@desc   and it must embed the Python 3 interpreter. You will also need <tt>protobuf</tt> installed 
-#@desc   for Python 3 on the local system. There are no Python requirements for the remote system.
-#@desc   Please ensure that Ghidra's current program and the target's image match.  Otherwise, the
-#@desc   modules may not map.</p>
+#@desc   <p>
+#@desc     This will start <tt>lldb</tt> on the local system and then use it to connect to the remote system.
+#@desc     For setup instructions, press <b>F1</b>.
+#@desc   </p>
 #@desc </body></html>
 #@menu-group remote
 #@icon icon.debugger
 #@help TraceRmiLauncherServicePlugin#lldb_remote
 #@env OPT_HOST:str="localhost" "Host" "The hostname of the target"
 #@env OPT_PORT:str="9999" "Port" "The host's listening port"
 #@env OPT_ARCH:str="" "Architecture" "Target architecture override"
-#@env OPT_LLDB_PATH:str="lldb" "Path to lldb" "The path to lldb on the local system. Omit the full path to resolve using the system PATH."
+#@env OPT_LLDB_PATH:str="lldb" "lldb command" "The path to lldb on the local system. Omit the full path to resolve using the system PATH."
 
 if [ -d ${GHIDRA_HOME}/ghidra/.git ]
 then