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` %>