From af9d543015bd5e39aa172e3f62030b0041f98eed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tobias=20Baunb=C3=A6k=20Christensen?= Date: Fri, 16 Feb 2024 15:35:02 +0100 Subject: [PATCH] Add guide on terminal debugging (#43) * Add guides on how to debug mobile/terminal apps * Rename to Pear Desktop * Cleanup * Clean Pear.config.args explanation * Fix incorrect renaming * Remove mobile debugging guide * Rename fix * Rename back to Pear Runtime --- SUMMARY.md | 3 +- guide/debugging-a-pear-terminal-app.md | 50 ++++++++++++++++++++++++++ guide/getting-started.md | 6 ++-- guide/making-a-pear-terminal-app.md | 1 - lib/system-status.js | 2 +- reference/api.md | 12 +++---- 6 files changed, 62 insertions(+), 12 deletions(-) create mode 100644 guide/debugging-a-pear-terminal-app.md diff --git a/SUMMARY.md b/SUMMARY.md index 678621d..d25c80f 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -17,6 +17,7 @@ * [Making a Pear Terminal Application](./guide/making-a-pear-terminal-app.md) * [Sharing a Pear Application](./guide/sharing-a-pear-app.md) * [Marking a Release](./guide/releasing-a-pear-app.md) +* [Debugging a Pear Terminal Application](./guide/debugging-a-pear-terminal-app.md) ### How-tos @@ -37,7 +38,7 @@ * [Hyperswarm](./building-blocks/hyperswarm.md) -## Helpers +## Helpers * [Corestore](./helpers/corestore.md) * [Localdrive](./helpers/localdrive.md) diff --git a/guide/debugging-a-pear-terminal-app.md b/guide/debugging-a-pear-terminal-app.md new file mode 100644 index 0000000..2aff468 --- /dev/null +++ b/guide/debugging-a-pear-terminal-app.md @@ -0,0 +1,50 @@ +# Debugging A Pear Terminal Application + +Debugging Pear Terminal Applications is different than debugging Desktop Applications because they do not come with a UI. Instead a few steps are needed. + +Use [Pear Inspect](https://github.com/holepunchto/pear-inspect) together with the Pear Runtime Desktop and use any tool that supports DevTools like Chrome. + +## Step 1. Install pear-inspect + +First install `pear-inspect`: + +``` +npm install pear-inspect +``` + +## Step 2. Add Code + +This code should run as the first thing in the application: + +``` js +if (Pear.config.dev) { + const { Inspector } = await import('pear-inspect') + const inpector = await new Inspector() + const key = await inpector.enable() + console.log(`Debug with pear://runtime/devtools/${key.toString('hex')}`) +} +``` + +## Step 3. Run In Dev Mode + +As the code specifies, `pear-inspect` is only running when in dev mode, so start the app: + +``` +pear dev . +``` + +The application will output something similar to: + +``` +Debug with pear://runtime/devtools/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2 +``` + +## Step 4. Add to Pear Runtime Desktop + +In Pear Desktop go to `Developer Tooling` and paste in the key. + +Note that the key can also be sent to someone else and they can debug the app remotely. + +## Step 5. Open in Chrome + +Click on `Open in Chrome` or copy the link into a tool that support DevTools. diff --git a/guide/getting-started.md b/guide/getting-started.md index 57ddbfd..08f4140 100644 --- a/guide/getting-started.md +++ b/guide/getting-started.md @@ -10,7 +10,7 @@ Since `npm` (or equivalent package manager) is needed to install application dep Pear runs on Windows, Mac and Linux. -The `pear` CLI can be installed from [npm](https://www.npmjs.com/), which comes with [`node`](https://nodejs.org/en/about). +The `pear` CLI can be installed from [npm](https://www.npmjs.com/), which comes with [`node`](https://nodejs.org/en/about). The `npm` package manager can also be used to install application dependencies later on. @@ -35,7 +35,7 @@ pear ``` If a Pear application, such as [Keet](https://keet.io), is already installed then the Pear platform is already available. In this case, running `pear` should show help output. - + If not, the first run of `pear` will fetch the platform from peers, after which running `pear` again should output help information. To check that Pear is fully working, try the following command: @@ -50,4 +50,4 @@ Pear loads applications from peers, so this command should open [Keet](https://k ## Next * [Starting a Pear Desktop Project](./starting-a-pear-desktop-project.md) -* [Starting a Pear Terminal Project](./starting-a-pear-terminal-project.md) \ No newline at end of file +* [Starting a Pear Terminal Project](./starting-a-pear-terminal-project.md) diff --git a/guide/making-a-pear-terminal-app.md b/guide/making-a-pear-terminal-app.md index 34bb231..5dacb2f 100644 --- a/guide/making-a-pear-terminal-app.md +++ b/guide/making-a-pear-terminal-app.md @@ -32,7 +32,6 @@ const { teardown, config } = Pear const key = config.args.pop() const shouldCreateSwarm = !key const swarm = new Hyperswarm() -const log = console.log const rl = readline.createInterface({ input: new tty.ReadStream(0), output: new tty.WriteStream(1) diff --git a/lib/system-status.js b/lib/system-status.js index f1f21a7..1cb9163 100644 --- a/lib/system-status.js +++ b/lib/system-status.js @@ -94,7 +94,7 @@ customElements.define('system-status', class extends HTMLElement { #tip { margin-top: 3rem; } - h1 { + h1 { padding: 0.5rem; display: inline-block; padding-right: 0.75em; diff --git a/reference/api.md b/reference/api.md index ecd1fde..beab3c9 100644 --- a/reference/api.md +++ b/reference/api.md @@ -9,9 +9,9 @@ as small as possible. ## `global.Pear` -The Pear Platform API is made available globally as `Pear`. +The Pear Platform API is made available globally as `Pear`. -The `Pear` API is designed to be small and immutable. +The `Pear` API is designed to be small and immutable. Any future changes to the `Pear` API will be non-breaking additions. @@ -83,7 +83,7 @@ Application storage path. ### `Pear.config.args ` -Command-line application arguments passed after double dash `--`. +Command-line application arguments passed like `pear dev . --some arg`. ### `Pear.config.release ` @@ -363,9 +363,9 @@ Restart the application. The `listener` function is called for every incoming update with an `update` object of the form: ```js -{ - type: 'pear/updates', - version: { fork , length , key , } | null, +{ + type: 'pear/updates', + version: { fork , length , key , } | null, app , diff >, }