Skip to content

Commit

Permalink
terminal updates; dashboard rewrite; use tailwind css; other updates
Browse files Browse the repository at this point in the history
  • Loading branch information
cs01 committed Aug 16, 2020
1 parent ed2a1a1 commit f39f798
Show file tree
Hide file tree
Showing 62 changed files with 4,847 additions and 3,005 deletions.
3 changes: 1 addition & 2 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,5 @@ yarn-error.log
venv
.vscode
site
build.js
build.js.map
gdbgui/static/js/*
__pycache__
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,15 @@
# gdbgui release history

## development
**Breaking Changes**
* Removed `cmd` positional argument from CLI. Use `--args` instead.
* Replaced `--gdb` flag with `--gdb-cmd`. The `--gdb-cmd` argument specifies the gdb executable as well as all arguments you wish to pass to gdb at startup, for example `--gdb-cmd "gdb -nx"`.
* Removed `--rr` flag. Use `--gdb-cmd rr replay` instead.

**Additional Changes**
* Replaced single terminal on frontend with three terminals: an interactive xterm terminal running gdb, a gdbgui console for diagnostic messages, and a terminal connected to the inferior application being debugged.
* Updates to the dashboard
* Add ability to specify gdb command from the browser. This can now be accomplished from the dashboard.
* Removed gdbgui binaries from source control. They can now be downloaded as artifacts of [releases](https://github.com/cs01/gdbgui/releases).

## 0.13.2.1
Expand Down
73 changes: 17 additions & 56 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@ Thanks for your interest in contributing to gdbgui!

If your change is small, go ahead and submit a pull request. If it is substantial, create a GitHub issue to discuss it before making the change.

## Development Instructions
## Dependencies

gdbgui uses [nox](https://github.com/theacodes/nox) to automate various tasks. You will need it installed on your system before continuing.
1.) [nox](https://github.com/theacodes/nox) is used to automate various tasks. You will need it installed on your system before continuing.

You can install it with pipx (recommended):
```
Expand All @@ -15,72 +15,33 @@ or pip:
> pip install --user nox
```

### Step 1: Compile JavaScript Code
2.) [yarn](https://yarnpkg.com/) is used for managing JavaScript files

gdbgui compiles JavaScript source code into a single .js file.

Note that `yarn` can be replaced with `npm`:

First install JavaScript dependencies:
```bash
yarn install
## Developing
Development can be done with one simple step:
```

To watch JavaScript files for changes and build non-optimized code for each change, use
```
yarn start
> nox -s develop
```
This will install all Python and JavaScript dependencies, and build and watch Python and JavaScript files for changes, automatically reloading as things are changed.

This is useful for iterating on changes.

To build once for production-optimized code, you can run
```
yarn build
```

### Step 2: Run Server
Make sure you [turn your cache off](https://www.technipages.com/google-chrome-how-to-completely-disable-cache) so that changes made locally are reflected in the page.

## Running and Adding tests
```bash
git clone https://github.com/cs01/gdbgui
cd gdbgui
nox -s develop-3.7 # replace with desired Python version
source .nox/develop-3-7/bin/activate # replace with desired Python version
> nox
```

You are now in a virtual environment with gdbgui's dependencies installed. When finished, type `deactivate` to leave the virtual environment.
runs all applicable tests and linting.

```bash
python -m gdbgui --debug
Python tests are in `gdbgui/tests`. They are run as part of the above command, but can be run with
```

The `--debug` flag:

1. Automatically reloads the server when it detects changes you've made
1. Adds a new component at the bottom of the right sidebar called "gdb machine interface output" that displays the raw gdb mi output to help you debug.
1. Displays all changes to state data in the browser's developer console, such as `rendered_source_file_fullname null -> /home/chad/git/gdbgui/examples/hello.c`


### Step 3: Make your changes

Open the browser to view gdbgui. Refresh the page as you make changes to JavaScript code.

!!! Note

Make sure you have caching turned off in your browser. In Chrome, for example, this is a setting in the developer console.

### Step 4: Run and Add tests

To continue, you must have nox installed.

```bash
nox
> nox -s python_tests
```

runs gdbgui unit tests.

If you have changed any Python code, add new tests to `gdbgui/tests/test_app.py` as necessary.

JavaScript tests are minimal, so you will have to manually excercise any code paths that may be affected.
JavaScript tests are in `gdbgui/src/js/tests`. They are run as part of the above command, but can be run with
```
> nox -s js_tests
```

## Documentation

Expand Down
6 changes: 6 additions & 0 deletions MANIFEST.in
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@ include README.md
include LICENSE

graft gdbgui
# these files are built and must be included in distribution
# but shouldn't be included in git repository since they
# are generated
graft gdbgui/static/js

prune examples
prune downloads
Expand Down Expand Up @@ -29,3 +33,5 @@ exclude yarn.lock
exclude noxfile.py
exclude CHANGELOG.md
exclude CONTRIBUTING.md
exclude postcss.config.js
exclude tailwind.config.js
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
</p>

<h3 align="center">
A modern, browser-based frontend to gdb (gnu debugger)
A browser-based frontend to gdb (gnu debugger)
</h3>

<p align="center">
Expand Down
18 changes: 7 additions & 11 deletions docs/examples.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,19 +14,19 @@ gdbgui
set the inferior program, pass argument, set a breakpoint at main

```
gdbgui "./myprogram myarg -myflag"
gdbgui --args ./myprogram myarg command -myflag
```

alternate way to do the same thing (note the lack of quotes)
use gdb binary not on your $PATH

```
gdbgui --args ./myprogram myarg command -myflag
gdbgui --gdb-cmd build/mygdb
```

use gdb binary not on your $PATH
Pass arbitrary arguments directly to gdb when it is launched

```
gdbgui -g build/mygdb
gdbgui --gdb-cmd="gdb -x gdbcmds.txt"
```

run on port 8080 instead of the default port
Expand All @@ -35,11 +35,7 @@ run on port 8080 instead of the default port
gdbgui --port 8080
```

Pass arbitrary arguments directly to gdb when it is launched

```
gdbgui --gdb-args="-x gdbcmds.txt"
```

run on a server and host on 0.0.0.0. Accessible to the outside world as long as port 80 is not blocked.

Expand All @@ -63,13 +59,13 @@ gdbgui -r --auth --key private.key --cert host.cert

Use Mozilla's [record and replay](https://rr-project.org) (rr) debugging supplement to gdb. rr lets your record a program (usually with a hard-to-reproduce bug in it), then deterministically replay it as many times as you want. You can even step forwards and backwards.
```
gdbgui --rr
gdbgui --gdb-cmd "rr replay"
```

Use recording other than the most recent one

```
gdbgui --rr RECORDED_DIRECTORY
gdbgui --gdb-cmd "rr replay RECORDED_DIRECTORY"
```

Don't automatically open the browser when launching
Expand Down
15 changes: 6 additions & 9 deletions docs/gettingstarted.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,13 @@
Now that you have `gdbgui` installed, all you need to do is run
Before running `gdbgui`, you should compile your program with debug symbols and a lower level of optimization, so code isn't optimized out before runtime. To include debug symbols with `gcc` or `rustc`, this means using `-g`. To disable most optimizations in gdcc `gcc` use the `-O0` flag.

For more details, consult your compiler's documentation or a search engine.

Now that you have `gdbgui` installed and your program compiled with debug symbols, all you need to do is run
```
gdbgui
```

which will start gdbgui's server and open a new tab in your browser. That tab contains a fully functional frontend running `gdb`!
This will start gdbgui's server and open a new tab in your browser. That tab contains a fully functional frontend running `gdb`!

You can see gdbgui in action on [YouTube](https://www.youtube.com/channel/UCUCOSclB97r9nd54NpXMV5A).

Expand Down Expand Up @@ -32,10 +36,3 @@ The following keyboard shortcuts are available when the focus is not in an input
* Up: u or up arrow
* Next Instruction: m
* Step Instruction: ,


## Debugging Faults

If your program exits unexpectedly from something like a SEGFAULT, gdbgui displays a button in the console to re-enter the state the program was in when it exited. This allows you to inspect the stack, the line on which the program exited, memory, variables, registers, etc.

![](https://raw.githubusercontent.com/cs01/gdbgui/master/screenshots/SIGSEV.png)
9 changes: 5 additions & 4 deletions docs/guides.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,9 @@ Remember, these guides, like gdbgui, are **open source** and can be edited by yo
After downloading gdbgui, you can launch it like so:

* `gdbgui` (or whatever the binary name is, i.e. `gdbgui_0.10.0.0`)
* `gdbgui "./mybinary -myarg value -flag1 -flag2"` (note the quotes around the arguments)
* `gdbgui --args "./mybinary -myarg value -flag1 -flag2"` (note the quotes around the arguments)
* `gdbgui --args ./mybinary -myarg value -flag1 -flag2`

Make sure the program you want to debug was compiled with debug symbols. See the getting started section for more details.

A new tab in your browser will open with gdbgui in it. If a browser tab did not open, navigate to the ip/port that gdbgui is being served on (i.e. http://localhost:5000).

Expand Down Expand Up @@ -42,9 +43,9 @@ cd myprog
cargo build
```

You can start debugging with a simple
You can start debugging with

`gdbgui target/debug/myprog`
`gdbgui --args target/debug/myprog`

There are a couple of small difficulties.

Expand Down
2 changes: 1 addition & 1 deletion docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
</p>

<h3 align="center">
A modern, browser-based frontend to gdb (gnu debugger)
A browser-based frontend to gdb (gnu debugger)
</h3>

<p align="center">
Expand Down
9 changes: 3 additions & 6 deletions docs/screenshots.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
![image](https://github.com/cs01/gdbgui/raw/master/screenshots/gdbgui2.png)

Enter the binary and args just as you'd call them on the command line.
Binary is restored when gdbgui is opened at a later time.
The binary is restored when gdbgui is opened at a later time.

![image](https://github.com/cs01/gdbgui/raw/master/screenshots/load_binary_and_args.png)

Expand All @@ -11,7 +11,7 @@ Next, Step, Return, Next Instruction, Step Instruction.

![image](https://github.com/cs01/gdbgui/raw/master/screenshots/controls.png)

If using an Intel CPU and running Linux, gdbgui also works in conjunction with [rr](http://rr-project.org/) to let you debug in reverse.
If the environment supports reverse debugging, such as when using an Intel CPU and running Linux and debugging with [rr](http://rr-project.org/), gdbgui allows you to debug in reverse.
![image](https://github.com/cs01/gdbgui/raw/master/screenshots/reverse_debugging.png)

## Stack/Threads
Expand All @@ -22,13 +22,10 @@ pointing and clicking.

![image](https://github.com/cs01/gdbgui/raw/master/screenshots/stack_and_threads.png)

## Send Signal to Inferior
## Send Signal to Inferior (debugged) Process
Choose from any signal your OS supports to send to the inferior. For example, to mock `CTRL+C` in plain gdb, you can send `SIGINT` to interrupt the inferior process. If the inferior process is hung for some reason, you can send `SIGKILL`, etc.
![image](https://github.com/cs01/gdbgui/raw/master/screenshots/send_signal.png)

Signals are also recognized by `gdbgui`, and a button is presented to let you step back into the program and inspect the program's state in case it exits unexpectedly.
![image](https://github.com/cs01/gdbgui/raw/master/screenshots/SIGSEV.png)


## Source Code
View source, assembly, add breakpoints. All symbols used to compile the
Expand Down
22 changes: 13 additions & 9 deletions examples/c/hello.c
Original file line number Diff line number Diff line change
@@ -1,21 +1,23 @@
#include <stdio.h>
#include <string.h>

void say_something(const char* str)
void say_something(const char *str)
{
printf("%s\n", str);
}

struct mystruct_t {
struct mystruct_t
{
int value;
char letter;
char *string;

struct {
struct
{
double dbl;
} substruct; /* named sub-struct */

struct {
struct
{
float fp;
}; /* anonymous struct */

Expand All @@ -27,8 +29,8 @@ struct mystruct_t {
};
};


int main(int argc, char **argv) {
int main(int argc, char **argv)
{
printf("Hello World\n");

int retval = 1;
Expand All @@ -46,11 +48,13 @@ int main(int argc, char **argv) {
s.unionint = 0;
s.uniondouble = 1.0;

for (int i = 0; i < 2; i++) {
for (int i = 0; i < 2; i++)
{
printf("i is %d\n", i);
}

if (!strcmp(s.string, "pass")) {
if (!strcmp(s.string, "pass"))
{
retval = 0;
}

Expand Down
11 changes: 11 additions & 0 deletions examples/c/input.c
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
#include <stdio.h>
#include <string.h>

int main(int argc, char **argv)
{
char name[20];
printf("Hello. What's your name?\n");
fgets(name, 20, stdin);
printf("Hi there, %s", name);
return 0;
}
14 changes: 9 additions & 5 deletions examples/c/makefile
Original file line number Diff line number Diff line change
@@ -1,17 +1,21 @@
GDBGUI=../../gdbgui/backend.py
ROOT:=$(shell dirname $(realpath $(firstword $(MAKEFILE_LIST))))

hello: hello.c
gcc hello.c -o hello_c.a -std=c99 -g
$(GDBGUI) hello_c.a
@echo Run with gdbgui: gdbgui --args $(ROOT)/hello_c.a

input: input.c
gcc input.c -o input.a -std=c99 -g
@echo Run with gdbgui: gdbgui --args $(ROOT)/input.a

debug_segfault: debug_segfault.c
gcc debug_segfault.c -g -o debug_segfault.a -std=c99
$(GDBGUI) debug_segfault.a
@echo Run with gdbgui: gdbgui --args $(ROOT)/debug_segfault.a

threads: threads.c
gcc threads.c -o threads.a -std=c99 -lpthread -g
$(GDBGUI) threads.a
@echo Run with gdbgui: gdbgui --args $(ROOT)/threads.a

sleeper: sleeper.c
gcc sleeper.c -o sleeper.a -std=c99 -g
$(GDBGUI) sleeper.a
@echo Run with gdbgui: gdbgui --args $(ROOT)/sleeper.a
Loading

0 comments on commit f39f798

Please sign in to comment.