Config for raLspServerPath will be overwritten if __RA_LSP_SERVER_DEBUG is set

Changed presentation from clear to reveal silent
Removed the vscode gitignore entry
Added debugging documentation
Added tasks and launch configs

7 files changed, 470 insertions, 7 deletions

diff --git a/.gitignore b/.gitignore
index 68158e41c..25e2b01b4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,6 +2,5 @@
 crates/*/target
 **/*.rs.bk
 .idea/*
-.vscode/*
 *.log
 *.iml
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
new file mode 100644
index 000000000..027eeabc4
--- /dev/null
+++ b/.vscode/extensions.json
@@ -0,0 +1,9 @@
+{
+  // See http://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations.
+  // Extension identifier format: ${publisher}.${name}. Example: vscode.csharp
+
+  // List of extensions which should be recommended for users of this workspace.
+  "recommendations": ["vadimcn.vscode-lldb"],
+  // List of extensions recommended by VS Code that should not be recommended for users of this workspace.
+  "unwantedRecommendations": []
+}
diff --git a/.vscode/launch.json b/.vscode/launch.json
new file mode 100644
index 000000000..9aafc8bd3
--- /dev/null
+++ b/.vscode/launch.json
@@ -0,0 +1,340 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug Extension",
+      "type": "extensionHost",
+      "request": "launch",
+      "runtimeExecutable": "${execPath}",
+      "args": [
+        "--extensionDevelopmentPath=${workspaceFolder}/editors/code",
+        "--disable-extensions"
+      ],
+      "env": {
+        "__RA_LSP_SERVER_DEBUG": "${workspaceFolder}/target/debug/ra_lsp_server"
+      },
+      "outFiles": ["${workspaceFolder}/editors/code/out/**/*.js"],
+      "preLaunchTask": "Build All"
+    },
+    {
+      "name": "Debug Lsp Server",
+      "type": "lldb",
+      "request": "attach",
+      "program": "${workspaceFolder}/target/debug/ra_lsp_server",
+      "pid": "${command:pickMyProcess}",
+      "sourceLanguages": ["rust"]
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug unit tests in library 'gen_lsp_server'",
+      "cargo": {
+        "args": ["test", "--no-run", "--lib", "--package=gen_lsp_server"],
+        "filter": {
+          "kind": "lib"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug unit tests in library 'ra_analysis'",
+      "cargo": {
+        "args": ["test", "--no-run", "--lib", "--package=ra_analysis"],
+        "filter": {
+          "kind": "lib"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug test 'tests'",
+      "cargo": {
+        "args": ["build", "--test=tests", "--package=ra_analysis"],
+        "filter": {
+          "kind": "bin"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug unit tests in test 'tests'",
+      "cargo": {
+        "args": ["test", "--no-run", "--test=tests", "--package=ra_analysis"],
+        "filter": {
+          "kind": "bin"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug unit tests in library 'ra_hir'",
+      "cargo": {
+        "args": ["test", "--no-run", "--lib", "--package=ra_hir"],
+        "filter": {
+          "kind": "lib"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug unit tests in library 'ra_db'",
+      "cargo": {
+        "args": ["test", "--no-run", "--lib", "--package=ra_db"],
+        "filter": {
+          "kind": "lib"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug unit tests in library 'ra_editor'",
+      "cargo": {
+        "args": ["test", "--no-run", "--lib", "--package=ra_editor"],
+        "filter": {
+          "kind": "lib"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug unit tests in library 'ra_syntax'",
+      "cargo": {
+        "args": ["test", "--no-run", "--lib", "--package=ra_syntax"],
+        "filter": {
+          "kind": "lib"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug test 'test'",
+      "cargo": {
+        "args": ["build", "--test=test", "--package=ra_syntax"],
+        "filter": {
+          "kind": "bin"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug unit tests in test 'test'",
+      "cargo": {
+        "args": ["test", "--no-run", "--test=test", "--package=ra_syntax"],
+        "filter": {
+          "kind": "bin"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug unit tests in library 'test_utils'",
+      "cargo": {
+        "args": ["test", "--no-run", "--lib", "--package=test_utils"],
+        "filter": {
+          "kind": "lib"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug executable 'ra_cli'",
+      "cargo": {
+        "args": ["build", "--bin=ra_cli", "--package=ra_cli"],
+        "filter": {
+          "kind": "bin"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug unit tests in executable 'ra_cli'",
+      "cargo": {
+        "args": ["test", "--no-run", "--bin=ra_cli", "--package=ra_cli"],
+        "filter": {
+          "kind": "bin"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug unit tests in library 'tools'",
+      "cargo": {
+        "args": ["test", "--no-run", "--lib", "--package=tools"],
+        "filter": {
+          "kind": "lib"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug executable 'tools'",
+      "cargo": {
+        "args": ["build", "--bin=tools", "--package=tools"],
+        "filter": {
+          "kind": "bin"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug unit tests in executable 'tools'",
+      "cargo": {
+        "args": ["test", "--no-run", "--bin=tools", "--package=tools"],
+        "filter": {
+          "kind": "bin"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug test 'cli'",
+      "cargo": {
+        "args": ["build", "--test=cli", "--package=tools"],
+        "filter": {
+          "kind": "bin"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug unit tests in test 'cli'",
+      "cargo": {
+        "args": ["test", "--no-run", "--test=cli", "--package=tools"],
+        "filter": {
+          "kind": "bin"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug unit tests in library 'ra_lsp_server'",
+      "cargo": {
+        "args": ["test", "--no-run", "--lib", "--package=ra_lsp_server"],
+        "filter": {
+          "kind": "lib"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug executable 'ra_lsp_server'",
+      "cargo": {
+        "args": ["build", "--bin=ra_lsp_server", "--package=ra_lsp_server"],
+        "filter": {
+          "kind": "bin"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug unit tests in executable 'ra_lsp_server'",
+      "cargo": {
+        "args": [
+          "test",
+          "--no-run",
+          "--bin=ra_lsp_server",
+          "--package=ra_lsp_server"
+        ],
+        "filter": {
+          "kind": "bin"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug test 'heavy_tests'",
+      "cargo": {
+        "args": ["build", "--test=heavy_tests", "--package=ra_lsp_server"],
+        "filter": {
+          "kind": "bin"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Debug unit tests in test 'heavy_tests'",
+      "cargo": {
+        "args": [
+          "test",
+          "--no-run",
+          "--test=heavy_tests",
+          "--package=ra_lsp_server"
+        ],
+        "filter": {
+          "kind": "bin"
+        }
+      },
+      "args": [],
+      "cwd": "${workspaceFolder}"
+    }
+  ]
+}
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
new file mode 100644
index 000000000..045cee326
--- /dev/null
+++ b/.vscode/tasks.json
@@ -0,0 +1,47 @@
+// See https://go.microsoft.com/fwlink/?LinkId=733558
+// for the documentation about the tasks.json format
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "type": "npm",
+      "script": "compile",
+      "label": "Build Extension",
+      "problemMatcher": {
+        "owner": "typescript",
+        "pattern": "$tsc",
+        "fileLocation": ["relative", "${workspaceRoot}/editors/code"]
+      },
+      "path": "editors/code/"
+    },
+    {
+      "label": "Build Lsp",
+      "type": "shell",
+      "command": "cargo build",
+      "problemMatcher": {
+        "owner": "rust",
+        "fileLocation": ["relative", "${workspaceRoot}"],
+        "pattern": [
+          {
+            "regexp": "^(warning|warn|error)(?:\\[(.*?)\\])?: (.*)$",
+            "severity": 1,
+            "code": 2,
+            "message": 3
+          },
+          {
+            "regexp": "^[\\s->=]*(.*?):(\\d*):(\\d*)\\s*$",
+            "file": 1,
+            "line": 2,
+            "column": 3
+          }
+        ]
+      }
+    },
+    {
+      "label": "Build All",
+      "group": "build",
+      "dependsOn": ["Build Extension", "Build Lsp"],
+      "problemMatcher": []
+    }
+  ]
+}
diff --git a/DEBUGGING.md b/DEBUGGING.md
new file mode 100644
index 000000000..0fa8ae29c
--- /dev/null
+++ b/DEBUGGING.md
@@ -0,0 +1,62 @@
+# Debugging vs Code plugin and the Language Server
+
+Install [LLDB](https://lldb.llvm.org/) and the [LLDB Extension](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb).
+
+Checkout rust rust-analyzer and open it in vscode.
+
+```
+$ git clone https://github.com/rust-analyzer/rust-analyzer.git --depth 1
+$ cd rust-analyzer
+$ code .
+```
+
+- To attach to the `lsp server` in linux you'll have to run:
+
+  `echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope`
+
+  This enables ptrace on non forked processes
+
+- Ensure the dependencies for the extension are installed, run the `npm: install - editors/code` task in vscode.
+
+- Launch the `Debug Extension`, this will build the extension and the `lsp server`.
+
+- A new instance of vscode with `[Extension Development Host]` in the title.
+
+  Don't worry about disabling `rls` all other extensions will be disabled but this one.
+
+- In the new vscode instance open a rust project, and navigate to a rust file
+
+- In the original vscode start an additional debug session (the three periods in the launch) and select `Debug Lsp Server`.
+
+- A list of running processes should appear select the `ra_lsp_server` from this repo.
+
+- Navigate to `crates/ra_lsp_server/src/main_loop.rs` and add a breakpoint to the `on_task` function.
+
+- Go back to the `[Extension Development Host]` instance and hover over a rust variable and your breakpoint should hit.
+
+## Demo
+
+![demonstration of debugging](./images/Rls_Debug.gif)
+
+## Troubleshooting
+
+### Can't find the `ra_lsp_server` process
+
+It could be a case of just jumping the gun.
+
+The `ra_lsp_server` is only started once the `onLanguage:rust` activation.
+
+Make sure you open a rust file in the `[Extension Development Host]` and try again.
+
+### Can't connect to `ra_lsp_server`
+
+Make sure you have run `echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope`.
+
+By default this should reset back to 1 everytime you log in.
+
+### Breakpoints are never being hit
+
+Check your version of `lldb` if it's version 6 and lower use the `classic` adapter type.
+It's `lldb.adapterType` in settings file.
+
+If you're running `lldb` version 7 change the lldb adapter type to `bundled` or `native`.
diff --git a/README.md b/README.md
index cbb72c8cf..304c2620a 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,6 @@ Work on the Rust Analyzer is sponsored by
 
 [![Ferrous Systems](https://ferrous-systems.com/images/ferrous-logo-text.svg)](https://ferrous-systems.com/)
 
-
 ## Quick Start
 
 Rust analyzer builds on Rust >= 1.31.0 and uses the 2018 edition.
@@ -36,6 +35,11 @@ $ cargo install --path crates/ra_lsp_server
 See [these instructions](./editors/README.md) for VS Code setup and the list of
 features (some of which are VS Code specific).
 
+## Debugging
+
+See [these instructions](./DEBUGGING.md) for VS Code setup and the list of
+features (some of which are VS Code specific).
+
 ## Current Status and Plans
 
 Rust analyzer aims to fill the same niche as the official [Rust Language
@@ -53,11 +57,11 @@ The near/mid term plan is to work independently of the main rustc compiler and
 implement at least simplistic versions of name resolution, macro expansion and
 type inference. The purpose is two fold:
 
-* to quickly bootstrap usable and useful language server: solution that covers
+- to quickly bootstrap usable and useful language server: solution that covers
   80% of Rust code will be useful for IDEs, and will be vastly simpler than 100%
   solution.
 
-* to understand how the consumer-side of compiler API should look like
+- to understand how the consumer-side of compiler API should look like
   (especially it's on-demand aspects). If you have `get_expression_type`
   function, you can write a ton of purely-IDE features on top of it, even if the
   function is only partially correct. Pluging in the precise function afterwards
@@ -77,7 +81,6 @@ implemented in Rust: [https://discord.gg/sx3RQZB](https://discord.gg/sx3RQZB).
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) and [ARCHITECTURE.md](./ARCHITECTURE.md)
 
-
 ## License
 
 Rust analyzer is primarily distributed under the terms of both the MIT
diff --git a/editors/code/src/config.ts b/editors/code/src/config.ts
index cd0c6e6e2..cc7a10f76 100644
--- a/editors/code/src/config.ts
+++ b/editors/code/src/config.ts
@@ -2,9 +2,11 @@ import * as vscode from 'vscode';
 
 import { Server } from './server';
 
+const RA_LSP_DEBUG = process.env.__RA_LSP_SERVER_DEBUG;
+
 export class Config {
     public highlightingOn = true;
-    public raLspServerPath = 'ra_lsp_server';
+    public raLspServerPath = RA_LSP_DEBUG || 'ra_lsp_server';
 
     constructor() {
         vscode.workspace.onDidChangeConfiguration(_ =>
@@ -24,7 +26,8 @@ export class Config {
         }
 
         if (config.has('raLspServerPath')) {
-            this.raLspServerPath = config.get('raLspServerPath') as string;
+            this.raLspServerPath =
+                RA_LSP_DEBUG || (config.get('raLspServerPath') as string);
         }
     }
 }