--- a/README.md Mon Feb 22 19:55:25 2021 +0000
+++ b/README.md Tue Feb 23 13:38:11 2021 +0000
@@ -6,18 +6,153 @@
* event-based interface
* convenient API to inspect and query current state of a debugee
- * support for custom disassembler allowing for custom code analysis
+ * support for custom disassembler allowing for custom code analysis (not part
+ of *libgdbs*)
+
+## Example Use
-## Building from Source
+ | b0 thread frame i r |
+
+ "Create new debugger object - `gdb`."
+ gdb := GDBDebugger new.
+
+ "Load an executable to debug, the parameter is a String
+ with path to the executable."
+ gdb executable: GDBDebuggeesResource current binaryFactorial1.
+
+ "Set breakpoint on function `factorial(int)`, see`factorial.c`(*).
+ Here we use `GDBDebugger >> #send:` to send a standard CLI command
+ to `gdb`. The method blocks and returns once the command is executed.
+ See class `GDBDebugger`, protocol 'commands' for more ways to send a
+ command to GDB.
+
+ (*) https://swing.fit.cvut.cz/hg/jv-libgdbs/file/tip/tests/c/factorial1.c
+ "
+ gdb send: 'b factorial'.
+
+ "You may ask `gdb` for list of breakpoints, ..."
+ gdb breakpoints.
+
+ "...retrieve a breakpoint as an object..."
+ b0 := gdb breakpoints first.
+
+ "...and then use breakpoint object to get details
+ for example on what file and line the breakpoint was
+ put:"
+ 'location is %1 : %2' bindWith: b0 file with: b0 line.
+
+ "Breakpoint objects can also be used to manipulate it,
+ for example to set a condition when the breakpoint should
+ hit. See class `GDBBreakpoint`. "
+ b0 condition: 'i == 1'.
+
+ "Now let's run debuggee util it hits the breakpoint using
+ GDB's `r` (or `run`) command. Here we (have to) use a different
+ API than plain `#send: - `#send:` executes the command and return
+ as soon as the command is executed. This is not what we want now,
+ here we want to run the debuggee and wait until breakpoint hits
+ (or until some error occur). In theory, this could be hours after
+ the `r` command is executed.
+
+ For cases like this, libgdb's provides another API:
+ `GDBDebugger >> send:andWaitFor:` to wait for 'stopped' event:"
+ gdb send: 'r' andWaitFor: GDBStoppedEvent.
-*libgsbs* is a part of [Smalltalk/X jv-branch][3] since version 8.0.0. To
-build *libgsbs*, just follow instructions how to [build
-Smalltalk/X jv-branch][6]
+ "Now let's see where we have stopped. Since GDB allows
+ to debug multiple processes (called inferiors in GDB parlance)
+ and each process may have multiple threads, we have to first get
+ a the thread and then ask the thread for first (newest) frame of
+ threads callstack. In this case, there' only one process with
+ only one thread, so getting the thread is easy.
+
+ Note, that there's always a callstack with at least one frame."
+ thread := gdb selectedInferior threads first.
+ frame := thread stack first.
+
+ "Again, thread and frame are objects and can be used to access
+ program state"
+ frame func. " -> 'factorial'"
+ i := frame variables first.
+ i name. " -> 'i' "
+ i value. " -> '1' "
+
+ r := frame registers first.
+ r name. " -> 'rax' (depending on target architecture, of course) "
+ r value.
+
+ "Finally, remove all breakpoints and let the program continue and finish..."
+ gdb send: 'del'.
+ gdb send: 'c' andWaitFor: GDBThreadGroupExitedEvent.
+
+For more examples, load `jv:libgdbs/tests` and see `GDBDebuggerExamples`. You may also
+want to have a look at tests `GDBDebuggerTestsR`.
+
+## Getting Started...
+
+### ...on Linux
+
+1. Create a directory where to download and install all components - in following
+ steps we use `/where/you/want/it` but naturally, choice is yours:
+
+ mkdir -p /where/you/want/it
+ cd /where/you/want/it
+
+2. Get suitable GDB. Pre-built binaries for Linux (and Windows) can be found
+ at [https://swing.fit.cvut.cz/download/gdb][11]:
+
+ wget https://swing.fit.cvut.cz/download/gdb/gdb_x86_64-pc-linux-gnu_YYYY-MM-DD_XXXXXXXX_NN.zip
+ unzip gdb_x86_64-pc-linux-gnu_YYYY-MM-DD_XXXXXXXX_NN.zip
+ rm gdb_x86_64-pc-linux-gnu_YYYY-MM-DD_XXXXXXXX_NN.zip
-## Prerequisites
+ Alternatively, you may want to build suitable GDB from sources, see
+ [doc/GDB.md][9] for details.
+
+ **Note** that if you're using pre-built binaries, make sure it
+ does run fine:
+
+ gdb_x86_64-pc-linux-gnu_YYYY-MM-DD_XXXXXXXX_NN/bin/gdb --help
+
+ You may have some libraries missing or have different versions than build
+ host, so it might not work. If it does not, you need to build it yourtself.
+ Luckily, building GDB in Linux is straigtforward enough - see
+ [doc/GDB.md][9] for details
+
+3. Get [Smalltalk/X jv-branch][3]. Pre-build "toy" binaries for Linux
+ can be found at [https://swing.fit.cvut.cz/download/smalltalkx/devel][5]:
+
+ wget https://swing.fit.cvut.cz/download/smalltalkx/devel/YYYY-MM-DD_NNN/smalltalkx-jv-branch-8.0.99_buildNNN_x86_64-pc-linux-gnu.tar.bz2
+ tar xf smalltalkx-jv-branch-8.0.99_buildNNN_x86_64-pc-linux-gnu.tar.bz2
+ rm smalltalkx-jv-branch-8.0.99_buildNNN_x86_64-pc-linux-gnu.tar.bz2
+
+ Alternatively, you may want to build Smalltalk/X from sources, see
+ [build instructions][12]. This is actually preferred way to work with
+ Smalltalk/X.
-As of today, *libgdbs* requires a very recent GDB. Likely you'd need to
-compile a GDB yourself - see [GDB.md][9]
+4. Get *jv:libgdbs*:
+
+ mkdir -p jv
+ hg clone https://swing.fit.cvut.cz/hg/jv-libgdbs jv/libgdbs
+
+5. Start Smalltalk/X:
+
+ ./smalltalkx-jv-branch-8.0.99_buildNNN_x86_64-pc-linux-gnu/bin/stx --package-path /where/you/want/it
+
+ Please note, that `/where/you/want/it` should be the path to where you
+ created `jv` directory in which libgdbs has been cloned in step 3.
+
+6. In Smalltalk/X workspace, load `jv:libgdbs` and set path to suitable GDB:
+
+ Smalltalk loadPackage: 'jv:libgdbs'.
+ UserPreferences current gdbCommand: '/where/you/want/it/gdb_x86_64-pc-linux-gnu_YYYY-MM-DD_XXXXXXXX_NN/bin/gdb'.
+
+7. Now you may create an instance of GDB to play with - in Smalltalk/X
+ workspace execute:
+
+ gdb := GDBDebugger new.
+
+### ...on Windows
+
+For installing on Windows, see [doc/GettingStartedOnWindows.md][13]
## Documentation
@@ -44,9 +179,12 @@
[2]: https://www.gnu.org/software/gdb/
[3]: https://swing.fit.cvut.cz/projects/stx-jv
[4]: https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git
-[5]: https://swing.fit.cvut.cz/jenkins/job/stx_jv/lastSuccessfulBuild/
+[5]: https://swing.fit.cvut.cz/download/smalltalkx/devel
[6]: https://swing.fit.cvut.cz/projects/stx-jv/report/9
[7]: https://swing.fit.cvut.cz/projects/stx-jv/newticket
[8]: https://groups.google.com/forum/#!forum/stx-jv
[9]: doc/GDB.md
-[10]: doc/README.md
\ No newline at end of file
+[10]: doc/README.md
+[11]: https://swing.fit.cvut.cz/download/gdb
+[12]: https://swing.fit.cvut.cz/projects/stx-jv/wiki/Documentation/BuildingStXWithRakefiles
+[13]: doc/GettingStartedOnWindows.md
\ No newline at end of file