misc/README.md.erb in debug-1.0.0.beta8 vs misc/README.md.erb in debug-1.0.0.rc1

- old
+ new

@@ -18,10 +18,11 @@ * By calling Ruby's method explicitly * Misc * Support threads (almost done) and ractors (TODO). * Support suspending and entering to the console debugging with `Ctrl-C` at most of timing. * Show parameters on backtrace command. + * Support recording & reply debugging. # Installation ``` $ gem install debug --pre @@ -30,40 +31,40 @@ or specify `-Ipath/to/debug/lib` in `RUBYOPT` or each ruby command-line option, especially for debug this gem development. If you use Bundler, write the following line to your Gemfile. ``` -gem "debug", ">= 1.0.0.beta" +gem "debug", ">= 1.0.0.rc" ``` # HOW TO USE To use a debugger, roughly you will do the following steps: 1. Set breakpoints. 2. Run a program with the debugger. 3. At the breakpoint, enter the debugger console. 4. Use debug commands. - * Query the prgram status (e.g. `p lvar` to see the local variable `lvar`). + * Query the program status (e.g. `p lvar` to see the local variable `lvar`). * Control program flow (e.g. move to the another line with `step`, to the next line with `next`). - * Set another breakpoints (e.g. `catch Exception` to set the breakpoints when `Exception` is raiesd). + * Set another breakpoint (e.g. `catch Exception` to set a breakpoint when `Exception` is raised). * Change the configuration (e.g. `config set no_color true` to disable coloring). * Continue the program (`c` or `continue`) and goto 3. ## Invoke with the debugger There are several options for (1) and (2). Please choose your favorite way. ### Modify source code as `binding.pry` and `binding.irb` If you can modify the source code, you can use the debugger by adding `require 'debug'` line at the top of your program and putting `binding.break` method (`binding.b` for short) into lines where you want to stop as breakpoints like `binding.pry` and `binding.irb`. -After that, you run the program as usuall and you will enter the debug console at breakpoints you inserted. +After that, you run the program as usual and you will enter the debug console at breakpoints you inserted. The following example shows the demonstration of `binding.break`. ```shell -$ cat target.rb # Sample prgram +$ cat target.rb # Sample program require 'debug' a = 1 b = 2 binding.break # Program will stop here @@ -118,17 +119,17 @@ (rdbg) continue [1, 2, 3, 4] ``` -### Invoke the prorgam from the debugger as a traditional debuggers +### Invoke the program from the debugger as a traditional debuggers If you don't want to modify the source code, you can set breakpoints with a debug command `break` (`b` for short). Using `rdbg` command to launch the program without any modifications, you can run the program with the debugger. ```shell -$ cat target.rb # Sample prgram +$ cat target.rb # Sample program a = 1 b = 2 c = 3 d = 4 p [a, b, c, d] @@ -239,20 +240,20 @@ NOTE: If you want to use bundler (`bundle` command), you need to write `gem debug` line in your `Gemfile`. ### Using VSCode -Like other langauges, you can use this debugger on the VSCode. +Like other languages, you can use this debugger on the VSCode. -1. Install [VSCode rdbg Ruby Debugger - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg) +1. Install [VSCode rdbg Ruby Debugger - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg) 2. Open `.rb` file (e.g. `target.rb`) 3. Register breakpoints with "Toggle breakpoint" in Run menu (or type F9 key) 4. Choose "Start debugging" in "Run" menu (or type F5 key) 5. You will see a dialog "Debug command line" and you can choose your favorite command line your want to run. -6. Chosed command line is invoked with `rdbg -c` and VSCode shows the details at breakponts. +6. Chosen command line is invoked with `rdbg -c` and VSCode shows the details at breakpoints. -Plase refer [Debugging in Visual Studio Code](https://code.visualstudio.com/docs/editor/debugging) for operations on VSCode. +Please refer [Debugging in Visual Studio Code](https://code.visualstudio.com/docs/editor/debugging) for operations on VSCode. You can configure the extension in `.vscode/launch.json`. Please see the extension page for more details. ## Remote debugging @@ -263,11 +264,11 @@ * Your application is running on Docker container and there is no TTY. * Your application is running as a daemon. * Your application uses pipe for STDIN or STDOUT. * Your application is running as a daemon and you want to query the running status (checking a backtrace and so on). -You can run your application as a remote debuggee and the remote debugger console can attach to the debugee anytime. +You can run your application as a remote debuggee and the remote debugger console can attach to the debuggee anytime. ### Invoke as a remote debuggee There are two ways to invoke a script as remote debuggee: Use `rdbg --open` and require `debug/open` (or `debug/open_nonstop`). @@ -277,14 +278,14 @@ ```shell $ exe/rdbg --open target.rb DEBUGGER: Session start (pid: 7773) DEBUGGER: Debugger can attach via UNIX domain socket (/home/ko1/.ruby-debug-sock/ruby-debug-ko1-7773) -DEBUGGER: wait for debuger connection... +DEBUGGER: wait for debugger connection... ``` -By deafult, `rdbg --open` uses UNIX domain socket and generates path name automatically (`/home/ko1/.ruby-debug-sock/ruby-debug-ko1-7773` in this case). +By default, `rdbg --open` uses UNIX domain socket and generates path name automatically (`/home/ko1/.ruby-debug-sock/ruby-debug-ko1-7773` in this case). You can connect to the debuggee with `rdbg --attach` command (`rdbg -A` for short). ```shell $ rdbg -A @@ -307,11 +308,11 @@ NOTE: If you use `quit` command, only remote console exits and the debuggee program continues to run (and you can connect it again). If you want to exit the debuggee program, use `kill` command. If you want to use TCP/IP for the remote debugging, you need to specify the port and host with `--port` like `rdbg --open --port 12345` and it binds to `localhost:12345`. -To connect to the debugeee, you need to specify the port. +To connect to the debuggee, you need to specify the port. ```shell $ rdbg --attach 12345 ``` @@ -322,11 +323,11 @@ If you can modify the program, you can open debugging port by adding `require 'debug/open'` line in the program. If you don't want to stop the program at the beginning, you can also use `require 'debug/open_nonstop'`. Using `debug/open_nonstop` is useful if you want to open a backdoor to the application. -However, it is also danger because it can become antoher vulnerability. +However, it is also danger because it can become another vulnerability. Please use it carefully. By default, UNIX domain socket is used for the debugging port. To use TCP/IP, you can set the `RUBY_DEBUG_PORT` environment variable. ```shell @@ -334,18 +335,18 @@ ``` ## Configuration You can configure the debugger's behavior with debug commands and environment variables. -When the debug session is started, initial scripts are loaded so you can put your favorite configurations in the intial scripts. +When the debug session is started, initial scripts are loaded so you can put your favorite configurations in the initial scripts. ### Configuration list You can configure debugger's behavior with environment variables and `config` command. Each configuration has environment variable and the name which can be specified by `config` command. ``` -# configulation example +# configuration example config set log_level INFO config set no_color true ``` <% cat = nil; DEBUGGER__::CONFIG_SET.each do |key, (env, desc)| %> @@ -353,11 +354,11 @@ * <%= $1 %> <% cat = $1; end %> * `<%= env %>` (`<%= key %>`): <%= $2 %><% end %> ### Initial scripts -If there is `~/.rdbgrc`, the file is loaded as an initial scripts which contains debug commands) when the debug session is started. +If there is `~/.rdbgrc`, the file is loaded as an initial script (which contains debug commands) when the debug session is started. * `RUBY_DEBUG_INIT_SCRIPT` environment variable can specify the initial script file. * You can specify the initial script with `rdbg -x initial_script` (like gdb's `-x` option). Initial scripts are useful to write your favorite configurations. @@ -393,11 +394,11 @@ * `require 'debug/open_nonstop'`: Same as `rdbg --open --nonstop`. You need to require one of them at the very beginning of the application. Using `ruby -r` (for example `ruby -r debug/start target.rb`) is another way to invoke with debugger. -NOTE: Until Ruby 3.0, there is old `lib/debug.rb` standard library. So that if this gem is not installed, or if `Gemfile` missed to list this gem and `bunde exec` is used, you will see the following output: +NOTE: Until Ruby 3.0, there is old `lib/debug.rb` standard library. So that if this gem is not installed, or if `Gemfile` missed to list this gem and `bundle exec` is used, you will see the following output: ```shell $ ruby -r debug -e0 .../2.7.3/lib/ruby/2.7.0/x86_64-linux/continuation.so: warning: callcc is obsolete; use Fiber instead Debug.rb @@ -409,11 +410,11 @@ `lib/debug.rb` was not maintained well in recent years, and the purpose of this library is to rewrite old `lib/debug.rb` with recent techniques. #### Start by method -After loading `debug/session`, you can start debug session with the following methods. They are convinient if you want to specifies debug configrations in your program. +After loading `debug/session`, you can start debug session with the following methods. They are convenient if you want to specify debug configurations in your program. * `DEBUGGER__.start(**kw)`: start debug session with local console. * `DEBUGGER__.open(**kw)`: open debug port with configuration (without configurations open with UNIX domain socket) * `DEBUGGER__.open_unix(**kw)`: open debug port with UNIX domain socket * `DEBUGGER__.open_tcp(**kw)`: open debug port with TCP/IP @@ -434,28 +435,28 @@ If `do: 'command'` is specified, the debugger suspends the program and run the `command` as a debug command and continue the program. It is useful if you only want to call a debug command and don't want to stop there. ``` -def initialzie +def initialize @a = 1 binding.b do: 'watch @a' end ``` -On this case, register a watch breakpont for `@a` and continue to run. +On this case, register a watch breakpoint for `@a` and continue to run. -If `pre: 'command'` is specified, the debuger suspends the program and run the `command` as a debug command, and keep suspend. +If `pre: 'command'` is specified, the debugger suspends the program and run the `command` as a debug command, and keep suspend. It is useful if you have operations before suspend. ``` def foo binding.b pre: 'p bar()' ... end ``` -On this case, you can see the result of `bar()` everytime when you stops there. +On this case, you can see the result of `bar()` every time you stop there. ## rdbg command help ``` <%= `exe/rdbg --help` %>