update docs and add __main__ entrypoint

CHANGELOG.md

@@ -1,8 +1,5 @@
 # gdbgui release history
 
-## master
-* Do not clear program state when resuming inferior so that scroll position is better maintained
-
 ## 0.13.1.0
 * Remove automatic flushing of stdout and require newer version of pygdbmi
 * Add flake8 tests to CI build

CONTRIBUTING.md

@@ -20,14 +20,14 @@ run the Flask server with the `debug` flag.
 ```bash
 git clone https://github.com/cs01/gdbgui
 cd gdbgui
-pip install -r requirements.txt
+pip install -e .
 pip install -r dev_requirements.txt
 ```
 
 
 #### Step 2: Run Python server
 ```bash
-gdbgui/backend.py --debug
+python -m gdbgui --debug
 ```
 
 The `--debug` flag:
@@ -53,7 +53,6 @@ Now every JavaScript source file you change will be noticed by webpack and recom
 If you are modifying `gdbgui.js`, make sure you have caching turned off. In Chrome, for example, this is a setting in the developer console.
 
 #### Step 5: Make your changes
-Add your super awesome bugfix/feature/whatever
 
 #### Step 6: Run and Add tests
 

README.md

@@ -14,45 +14,75 @@ A modern, browser-based frontend to gdb (gnu debugger)
 </p>
 
 <p align="center">
-<a href="https://travis-ci.org/cs01/gdbgui"><img src="https://travis-ci.org/cs01/gdbgui.svg?branch=master" alt="image" /></a> <a href="https://pypi.python.org/pypi/gdbgui/"><img src="https://img.shields.io/badge/pypi-0.13.0.0-blue.svg" alt="image" /></a> <img src="https://img.shields.io/badge/python-2,3,pypy-blue.svg" alt="image" /> <a href="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/ambv/black"><img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code style: black" /></a> <a href="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/prettier/prettier"><img src="https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square" alt="code style: prettier" /></a></p>
+<a href="https://travis-ci.org/cs01/gdbgui">
+<img src="https://travis-ci.org/cs01/gdbgui.svg?branch=master" alt="image" /></a>
 
+<a href="https://pypi.python.org/pypi/gdbgui/">
+<img src="https://img.shields.io/badge/pypi-0.13.1.1-blue.svg" alt="image" />
+</a>
+
+[![Downloads](https://pepy.tech/badge/gdbgui)](https://pepy.tech/project/gdbgui)
+</p>
 
 
 Add breakpoints, view stack traces, and more in C, C++, Go, and Rust! Perfect for beginners and experts. Simply run `gdbgui` from the terminal and a new tab will open in your browser.
 
 
+## [gdbgui.com](https://gdbgui.com)
+Visit [gdbgui.com](https://gdbgui.com) for documentation, screenshots, and downloads
 
-## [Homepage](https://gdbgui.com)
 
-Visit [gdbgui.com](https://gdbgui.com) to download, view documentation, installation instructions, screenshots and more.
+## Try Without Installing
+By using [pipx](https://github.com/cs01/pipx), you can run Python CLI programs in ephemeral one-time virtual environments.
+```
+pipx gdbgui
+```
+A new tab running the latest version of gdbgui will open in your browser. Press CTRL+C to end the process, and your system will remain untouched.
+
+You can install pipx like this:
+```
+curl https://raw.githubusercontent.com/cs01/pipx/master/get-pipx.py | python3
+```
 
 ## Install
-gdbgui can be installed with pip
+### Global
+This option relies on [pipx](https://github.com/cs01/pipx), the Python CLI binary runner and installer. It installs Python CLI programs in isolated virtual environments. `pipx` can run any Python CLI program, including gdbgui. This is the recommended installation method.
+```
+pipx install gdbgui
+```
+Then type `gdbgui` at the command prompt.
+
+To upgrade, run
+```
+pipx upgrade gdbgui
+```
+
+### In a Virtual Environment
+Alternatively, if you have already activated a virtual environment, you can install gdbgui with pip.
 ```
 pip install gdbgui
 ```
+Then type `gdbgui`.
+
+### Download a binary executable for your platform
 or a binary executable can be downloaded from [gdbgui.com](https://gdbgui.com).
 
 ## License
-
 GNU GPLv3, which means you can use it for free at work or for personal use.
 
-[gdbgui.com](https://gdbgui.com), [https://github.com/cs01/gdbgui](https://github.com/cs01/gdbgui), and [PyPI](https://pypi.python.org/pypi/gdbgui/) are the only official sources of gdbgui that should be trusted.
+gdbgui is distributed through [gdbgui.com](https://gdbgui.com), [https://github.com/cs01/gdbgui](https://github.com/cs01/gdbgui), and [PyPI](https://pypi.python.org/pypi/gdbgui/).
 
 ## FAQ
 [click here](https://github.com/cs01/gdbgui/blob/master/docs/FAQ.md)
 
-## Support gdbgui
+## Donate
+[Paypal](https://www.paypal.me/grassfedcode/20)
 
-You can support the project by [donating](https://www.paypal.me/grassfedcode/20), spreading the word, and reporting issues.
 ## Contributing
-
 To add a feature or fix a bug, see [CONTRIBUTING](https://github.com/cs01/gdbgui/blob/master/CONTRIBUTING.md).
 
 ## Authors
-
 `gdbgui` is primarily authored by Chad Smith, with [help from the community](https://github.com/cs01/gdbgui/graphs/contributors). Large contributions were made by @bobthekingofegypt, who added initial autocomplete functionality for the gdb terminal.
 
 ## Contact
-
-<[email protected]>
+[email protected]

docs/INSTALLATION.md

@@ -1,49 +1,62 @@
 # gdbgui installation
 
-## Installation Options
-There are two options to use gdbgui:
-* standalone binary executable or
-* the Python Package `gdbgui`.
+## Try Without Installing
+By using [pipx](https://github.com/cs01/pipx), you can run Python CLI programs in ephemeral one-time virtual environments.
+```
+pipx gdbgui
+```
+A new tab running the latest version of gdbgui will open in your browser. Press CTRL+C to end the process, and your system will remain untouched.
 
-**Standalone binary executables are easier to install, and are available at [gdbgui.com](http:https://gdbgui.com)**.
 
-## Python Package
-If you do not want to use the binary, `gdbgui` is also a package in the [Python Package Index (PyPI)](https://pypi.python.org/pypi) and can be installed using [pip](https://pip.pypa.io/en/stable/), the recommended tool for installing Python packages. It is installed like any other python package:
+## Recommended Installation Instructions
+gdbgui recommends using [pipx](https://github.com/cs01/pipx), a program to run Python CLI binaries in isolated environments. You can install pipx like this:
+```
+curl https://raw.githubusercontent.com/cs01/pipx/master/get-pipx.py | python3
+```
 
- [sudo] pip install gdbgui --upgrade
+Then install gdbgui with pipx:
+```
+pipx install gdbgui
+```
+
+To upgrade run
+```
+pipx upgrade gdbgui
+```
 
 When installation is finished, type `gdbgui` from the command line to run it, or `gdbgui -h` for help.
 
-If you are unfamiliar with `pip` or if that command did not work, consider downloading the binary since it can be run directly. If you still want to install with pip, see Troubleshooting below.
+## Alternate Installation 1
+If you prefer to use Virtual Environments, you can activate one and then run
+```
+pip install gdbgui
+```
+
+## Alternate Installation 2
+Download and run the binary executable for your system on [gdbgui.com](http:https://gdbgui.com).
+
 
 **Please create an issue or pull request if any of this information is out of date, incomplete, or incorrect.**
 
-## Prerequisites if Using Python Package
+## System Dependencies
+Note that this only applies if you are installing the Python package, and not using the binary executable from gdbgui.com.
 
 * gdb (gnu debugger)
 * Python 3.4+ (recommended) or 2.7
 * pip version 8 or higher
 
-### Linux Prerequisites
-
-Note: this is for python package installation only, and not related to the standalone binary executables available at [gdbgui.com](http:https://gdbgui.com).
-
+### Linux Dependencies
  sudo apt-get install gdb python3
- sudo python3 -m pip install pip --upgrade
-
-### macOS Prerequisites
 
+### macOS Dependencies
  brew install python3
  brew install gdb --with-python --with-all-targets
 
 macOS users must also codesign gdb: follow [these
 instructions](http:https://andresabino.com/2015/04/14/codesign-gdb-on-mac-os-x-yosemite-10-10-2/). This will fix the error
 `please check gdb is codesigned - see taskgated(8)`.
 
-### Windows Prerequisites
-
-Note: this is for python package installation only, and not related to the standalone binary executables available at [gdbgui.com](http:https://gdbgui.com).
-
+### Windows Dependencies
 * [Python 3](https://www.python.org/downloads/windows/)
 * gdb, make, gcc
 
@@ -58,7 +71,7 @@ Ensure this MinGW binary directory (i.e. `C:\MinGW\bin\`) is on your "Path" envi
 
 ##### Cygwin
 Cygwin is a more UNIX-like compatibility layer on Windows, and `gdbgui` works with it as well.
-* Install [cygwin](https://cygwin.com/install.html) | [homepage](https://cygwin.com/index.html))
+* Install [cygwin](https://cygwin.com/install.html)
 * When installing cygwin packages, add the following:
 ** python3
 ** python3-pip
@@ -67,49 +80,22 @@ Cygwin is a more UNIX-like compatibility layer on Windows, and `gdbgui` works wi
 ** gcc-core
 ** gcc-g++
 
-Then run
-`pip install gdbgui --upgrade`
-
-## Troubleshooting
-
-Note: this is for python package installation only, and not related to the standalone binary executables available at [gdbgui.com](http:https://gdbgui.com).
-
-### Linux, macOS, Windows
-
-If there is a conflict or error when installing via pip, use [`pipsi`](https://github.com/mitsuhiko/pipsi). pipsi is like pip, but it sandboxes everything into its own python environment, and it works on all operating systems.
-
-* [Download the pipsi installer](https://raw.githubusercontent.com/mitsuhiko/pipsi/master/get-pipsi.py)
-* Run with python: `python get-pipsi.py`
-* `~/.local/bin/pipsi.exe install gdbgui`
-
-When installation is finished, type `gdbgui` from the command line to run it, or `gdbgui -h` for help.
-
-To upgrade gdbgui with pipsi:
-* `~/.local/bin/pipsi.exe upgrade gdbgui`
-
-### Running from source
 
+### Running from Source
+In an activated Virtual Environment, run
 ```bash
 git clone https://github.com/cs01/gdbgui
 cd gdbgui
-pip install -r requirements.txt # run as sudo if this fails
-gdbgui/backend.py
+pip install -e .
+python -m gdbgui
 ```
 
-Note: Although not strictly required, you should install requirements.txt using a virtualenv to avoid changing system python packages.
+A Virtual Environment sandboxes python packages, which guarantees there will be no installation conflicts.
 
-A [virtualenv](https://virtualenv.pypa.io/en/stable/) sandboxes python packages, which guarantees there will be no installation
-conflicts.
-
-To use a new virtualenv:
+To create and use a new virtualenv:
 
 ```bash
-pip install virtualenv # run as sudo if this fails
-virtualenv venv -p python3 # creates a virtual env named "venv"
+pythom3 -m venv # creates a virtual env named "venv"
 source venv/bin/activate # activates the virtualenv sandbox
 pip install pip --upgrade # make sure pip is at the latest version
 ```
-
-Then run
-
- pip install -r requirements.txt

gdbgui/VERSION.txt

@@ -1 +1 @@
-0.13.0.0
+0.13.1.1

gdbgui/__main__.py

@@ -0,0 +1,3 @@
+from . import backend
+
+backend.main()

gdbgui/src/js/BinaryLoader.jsx

@@ -192,17 +192,6 @@ class BinaryLoader extends React.Component {
  if (isNaN(num_gdbgui_sessions)) {
  num_gdbgui_sessions = 0;
  }
- if (
- num_gdbgui_sessions >= 9 &&
- initial_data.p !==
- "d2b6fad22b1e05178f4888fcb461a481e8e0e3b7a28b6bc60b1df7eb286a77dc"
- ) {
- /* global initial_data */
- Actions.add_console_entries("", constants.console_entry_type.UPGRADE_GDBGUI);
- localStorage.setItem("num_gdbgui_sessions", 0);
- } else {
- localStorage.setItem("num_gdbgui_sessions", num_gdbgui_sessions + 1);
- }
  }
  /**
  * parse tokens with awareness of double quotes

gdbgui/src/js/ControlButtons.jsx

@@ -16,7 +16,7 @@ class ControlButtons extends React.Component {
  <React.Fragment>
  <button
  id="run_button"
- onClick={()=>GdbApi.click_run_button()}
+ onClick={() => GdbApi.click_run_button()}
  type="button"
  title="Start inferior program from the beginning keyboard shortcut: r"
  className={btn_class}
@@ -26,7 +26,7 @@ class ControlButtons extends React.Component {
 
  <button
  id="continue_button"
- onClick={()=>GdbApi.click_continue_button()}
+ onClick={() => GdbApi.click_continue_button()}
  type="button"
  title={
  "Continue until breakpoint is hit or inferior program exits keyboard shortcut: c" +
@@ -48,7 +48,7 @@ class ControlButtons extends React.Component {
 
  <button
  id="next_button"
- onClick={()=>GdbApi.click_next_button()}
+ onClick={() => GdbApi.click_next_button()}
  type="button"
  title={
  "Step over next function call keyboard shortcut: n or right arrow" +
@@ -61,7 +61,7 @@ class ControlButtons extends React.Component {
 
  <button
  id="step_button"
- onClick={()=>GdbApi.click_step_button()}
+ onClick={() => GdbApi.click_step_button()}
  type="button"
  title={
  "Step into next function call keyboard shortcut: s or down arrow" +
@@ -74,7 +74,7 @@ class ControlButtons extends React.Component {
 
  <button
  id="return_button"
- onClick={()=>GdbApi.click_return_button()}
+ onClick={() => GdbApi.click_return_button()}
  type="button"
  title="Step out of current function keyboard shortcut: u or up arrow"
  className={btn_class}
@@ -84,7 +84,7 @@ class ControlButtons extends React.Component {
  <div role="group" className="btn-group btn-group-xs">
  <button
  id="next_instruction_button"
- onClick={()=>GdbApi.click_next_instruction_button()}
+ onClick={() => GdbApi.click_next_instruction_button()}
  type="button"
  title={
  "Next Instruction: Execute one machine instruction, stepping over function calls keyboard shortcut: m" +
@@ -96,7 +96,7 @@ class ControlButtons extends React.Component {
  </button>
  <button
  id="step_instruction_button"
- onClick={()=>GdbApi.click_step_instruction_button()}
+ onClick={() => GdbApi.click_step_instruction_button()}
  type="button"
  title={
  "Step Instruction: Execute one machine instruction, stepping into function calls keyboard shortcut: ','" +

gdbgui/src/js/GdbApi.jsx

@@ -310,7 +310,7 @@ const GdbApi = {
  constants.IGNORE_ERRORS_TOKEN_STR + "-thread-info",
  // print the name, type and value for simple data types,
  // and the name and type for arrays, structures and unions.
- constants.IGNORE_ERRORS_TOKEN_STR + "-stack-list-variables --simple-values",
+ constants.IGNORE_ERRORS_TOKEN_STR + "-stack-list-variables --simple-values"
  ];
  if (store.get("interpreter") === "gdb") {
  // update all user-defined variables in gdb

gdbgui/src/js/Settings.jsx

@@ -20,7 +20,7 @@ class Settings extends React.Component {
  "pretty_print",
  "refresh_state_after_sending_console_command",
  "show_all_sent_commands_in_console",
- "highlight_source_code",
+ "highlight_source_code"
  ]);
  this.get_update_max_lines_of_code_to_fetch = this.get_update_max_lines_of_code_to_fetch.bind(
  this