Skip to content

Commit

Permalink
feat: add node-debugger files from nuclide
Browse files Browse the repository at this point in the history
  • Loading branch information
aminya committed Oct 25, 2020
1 parent 33f54c9 commit f881c93
Show file tree
Hide file tree
Showing 80 changed files with 8,510 additions and 0 deletions.
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# Dev setup
Clone this repo, run `npm install` and `gulp build`, and in VS Code run the `launch as server` launch config. This will start the adapter as a server listening on port 4712.

Then in the debuggee, you can add `"debugServer": "4712"` to connect to your instance of the debug adapter, instead of the installed one. See [this page](https://code.visualstudio.com/docs/extensions/example-debuggers) for more details on debugging a debug adapter.

Since most of the code for this extension is in the [vscode-chrome-debug-core](https://github.com/Microsoft/vscode-chrome-debug-core) library, if you need to make changes, then you will probably want to clone both repos. You can run `npm link` from the `vscode-chrome-debug-core` directory, and `npm link vscode-chrome-debug-core` from this directory to make this repo use your cloned version of that library.

## Testing
See the project under testapp/ for a bunch of test scenarios crammed onto one page.
13 changes: 13 additions & 0 deletions src/debugger/node/VendorLib/vscode-node-debug2/LICENSE.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
VS Code - Debugger for Chrome

Copyright (c) Microsoft Corporation

All rights reserved.

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ""Software""), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
70 changes: 70 additions & 0 deletions src/debugger/node/VendorLib/vscode-node-debug2/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# VS Code Node Debug 2
[![build status](https://travis-ci.org/Microsoft/vscode-node-debug2.svg?branch=master)](https://travis-ci.org/Microsoft/vscode-node-debug2)
[![Build status](https://ci.appveyor.com/api/projects/status/qrr2hff3eagw5k05?svg=true)](https://ci.appveyor.com/project/roblourens/vscode-node-debug2)

This repository contains a debug extension for [node.js](https://nodejs.org) that ships with [VS Code](https://code.visualstudio.com) and uses the [Chrome Debugging Protocol](https://chromedevtools.github.io/debugger-protocol-viewer/v8/), which Node now exposes via the `--inspect` flag, only in Node versions 6.3+. It's built on the [vscode-chrome-debug-core](https://github.com/Microsoft/vscode-chrome-debug-core) library.

This extension has essentially reached feature-parity with vscode-node-debug. You can see the remaining issues in the [vscode-node-debug2](https://github.com/Microsoft/vscode-node-debug2/issues) repo and the [vscode-chrome-debug-core](https://github.com/microsoft/vscode-chrome-debug-core/issues) repo. You should be able to set `"type": "node2"` in your existing Node launch config and have things work the same, as long as it's running in Node v6.3+.

See an overview of debugging Node.js in VS Code [here](https://code.visualstudio.com/docs/editor/debugging).

## Node version compatibility
Typically it should work with any version of Node greater than 6.3. But there is some instability in Node with this option before 6.8, especially in Windows. Due to [nodejs/node#8155](https://github.com/nodejs/node/issues/8155), I recommend using at least 6.8 in Windows.

## Troubleshooting
* If something doesn't work, please try on the original Node debug adapter (`"type": "node"`) and this one, and file an issue for any regression.
* If there may be an issue with sourcemaps, try running with sourcemaps disabled and setting breakpoints in the generated script.
* Or try adding 'debugger' statements to ensure that the debugger pauses.
* Watch for error messages in the debug console or terminal. There may be bugs on Node's side and it could crash. It's most stable in Node v6.9 and v7. If Node seems to be crashing, you can launch with `"console": "integratedTerminal"` to watch for error messages that don't show up in the debug console.
* Set `"diagnosticLogging": true` or `"verboseDiagnosticLogging": true` in your launch config. The adapter will log its own diagnostic info to the console, and to a file in your temp directory, the path to which will be printed at the top of the console. This is useful in figuring out why breakpoints don't resolve, or why sourcemaps don't work properly, or anything else. This is often useful info to include when filing an issue on GitHub. Note that it will include paths and file names from your machine.

## When breakpoints don't bind (turn gray when debugging)
Typically this is because of an issue with sourcemaps. VS Code needs to be able to map the sources in your sourcemap file to the source files in your workspace.
* Ensure that `outFiles` is set correctly in your launch config, so that VS Code can find your scripts and its sourcemaps before they're loaded in Node. Example: `"outFiles": ["${workspaceFolder}/out/**/*.js"]`. (This may not be possible if your scripts are built in-memory or on demand.)
* Type `.scripts` into the Debug Console to see information about the scripts loaded in Node, and their sourcemaps. (Details below). Check the output for correctness.
* If the local paths of sources have been inferred incorrectly, you can correct it with the `sourceMapPathOverrides` option. See details below.
* You can set the `diagnosticLogging` or `verboseDiagnosticLogging` options to see the details of the sourcemap resolving process.

## The `.scripts` command
This feature is extremely useful for understanding how the extension maps files in your workspace to files running in Node. You can enter `.scripts` in the debug console to see a listing of all scripts loaded in the runtime, their sourcemap information, and how they are mapped to files on disk. The format is like this:

```
› <The exact URL for a script, reported by Node> (<The local path that has been inferred for this script, if applicable>)
- <The exact source path from the sourcemap> (<The local path inferred for the source, using sourceMapPathOverrides if applicable>)
```

Example:
```
.scripts
› /Users/roblou/project/out/app.js
- ../app.ts (/Users/roblou/project/app.ts)
```

## sourceMapPathOverrides
The `sourceMapPathOverrides` option lets you set a mapping of source paths from the sourcemap, to the locations of these sources on disk. Useful when the sourcemap isn't accurate or can't be fixed in the build process. The left hand side of the mapping is a pattern that can contain a wildcard, and will be tested against the `sourceRoot` + `sources` entry in the source map. If it matches, the source file will be resolved to the path on the right hand side, which should be an absolute path to the source file on disk. A couple mappings are applied by default, corresponding to the default configs for Webpack and Meteor -
```
"sourceMapPathOverrides": {
"webpack:///./*": "${cwd}/*", // Example: "webpack:///./src/app.js" -> "/users/me/project/src/app.js"
"webpack:///*": "*", // Example: "webpack:///C:/project/app.ts" -> "C:/project/app.ts"
"meteor://💻app/*": "${cwd}/*" // Example: "meteor://💻app/main.ts" -> "c:/code/main.ts"
}
```
If you set `sourceMapPathOverrides` in your launch config, that will override these defaults. `${workspaceFolder}` and `${cwd}` can be used here. If you aren't sure what the left side should be, you can use the `.scripts` command (details below). You can also use the `diagnosticLogging`/`verboseDiagnosticLogging` options to see the contents of the sourcemap, or look at the paths of the sources in Chrome DevTools, or open your `.js.map` file and check the values manually.

## Skipping "library code"/"blackboxed scripts"
The `skipFiles` option allows you to specify an array of names of folders/files to skip when debugging. For example, if you set `"skipFiles": ["lib.js"]`, then you will skip any file named 'lib.js' when stepping through your code. You also won't break on exceptions thrown from 'lib.js'. This works the same as "blackboxing scripts" in Chrome DevTools. Note that this is just an experiment at the moment. The supported formats are:
* The name of a file (like `lib.js`)
* The name of a folder, under which to skip all scripts (like `node_modules`)
* A path glob, to skip all scripts that match (like `node_modules/**/*.min.js`)

You can also skip a file at runtime by right clicking on the stack frame and selecting "Toggle skipping this file". This option only persists for the current debugging session. You can also use it to stop skipping a file that is skipped by the `skipFiles` option in your launch config.

When a file is skipped, it will be grayed out in the callstack.

## Contributing
Contributions are welcome, please see [CONTRIBUTING.txt](https://github.com/Microsoft/vscode-node-debug2/blob/master/CONTRIBUTING.txt).

This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](https://github.com/Microsoft/vscode-node-debug2/blob/master/mailto:opencode@microsoft.com) with any additional questions or comments.

## License
[MIT](https://github.com/Microsoft/vscode-node-debug2/blob/master/LICENSE.txt)
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
This project may use or incorporate third party material from the projects listed below. The original copyright notice and the license under which Microsoft received such third party material are set forth below. Microsoft reserves all other rights not expressly granted, whether by implication, estoppel or otherwise.

websockets-ws

(The MIT License)

Copyright (c) 2011 Einar Otto Stangvik <einaros@gmail.com>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
157 changes: 157 additions & 0 deletions src/debugger/node/VendorLib/vscode-node-debug2/gulpfile.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,157 @@
/*---------------------------------------------------------
* Copyright (C) Microsoft Corporation. All rights reserved.
*--------------------------------------------------------*/

const gulp = require('gulp');
const path = require('path');
const ts = require('gulp-typescript');
const log = require('gulp-util').log;
const typescript = require('typescript');
const sourcemaps = require('gulp-sourcemaps');
const tslint = require('gulp-tslint');
const runSequence = require('run-sequence');
const nls = require('vscode-nls-dev');
const cp = require('child_process');
const del = require('del');
const fs = require('fs');
const vsce = require('vsce');
const es = require('event-stream');

const transifexApiHostname = 'www.transifex.com'
const transifexApiName = 'api';
const transifexApiToken = process.env.TRANSIFEX_API_TOKEN;
const transifexProjectName = 'vscode-extensions';
const transifexExtensionName = 'vscode-node-debug2';
const vscodeLanguages = [
'zh-hans',
'zh-hant',
'ja',
'ko',
'de',
'fr',
'es',
'ru',
'it',
'pt-br',
'hu',
'tr'
];

const watchedSources = [
'src/**/*',
'test/**/*'
];

const scripts = [
'src/terminateProcess.sh'
];

const lintSources = [
'src'
].map(function(tsFolder) { return tsFolder + '/**/*.ts'; });

const tsProject = ts.createProject('tsconfig.json', { typescript });
function doBuild(buildNls) {
return tsProject.src()
.pipe(sourcemaps.init())
.pipe(tsProject()).js
.pipe(buildNls ? nls.rewriteLocalizeCalls() : es.through())
.pipe(buildNls ? nls.createAdditionalLanguageFiles(nls.coreLanguages, 'i18n', 'out') : es.through())
.pipe(sourcemaps.write('.', { includeContent: false, sourceRoot: '..' })) // .. to compensate for TS returning paths from 'out'
.pipe(gulp.dest('out'));
}

gulp.task('build', ['copy-scripts'], function () {
doBuild(true);
});

gulp.task('dev-build', ['copy-scripts'], function () {
doBuild(false);
});

gulp.task('copy-scripts', () => {
return gulp.src(scripts, { base: '.' })
.pipe(gulp.dest('out'));
});

gulp.task('watch', ['dev-build'], function(cb) {
log('Watching build sources...');
return gulp.watch(watchedSources, ['dev-build']);
});

gulp.task('default', ['build']);

gulp.task('tslint', function() {
return gulp.src(lintSources, { base: '.' })
.pipe(tslint({
formatter: "verbose"
}))
.pipe(tslint.report({ emitError: false }));
});

gulp.task('clean', function() {
return del(['out/**', 'package.nls.*.json', 'vscode-node-debug2-*.vsix']);
});

function verifyNotALinkedModule(modulePath) {
return new Promise((resolve, reject) => {
fs.lstat(modulePath, (err, stat) => {
if (stat.isSymbolicLink()) {
reject(new Error('Symbolic link found: ' + modulePath));
} else {
resolve();
}
});
});
}

function verifyNoLinkedModules() {
return new Promise((resolve, reject) => {
fs.readdir('./node_modules', (err, files) => {
Promise.all(files.map(file => {
const modulePath = path.join('.', 'node_modules', file);
return verifyNotALinkedModule(modulePath);
})).then(resolve, reject);
});
});
}

gulp.task('verify-no-linked-modules', cb => verifyNoLinkedModules().then(() => cb, cb));

gulp.task('vsce-publish', function () {
return vsce.publish();
});
gulp.task('vsce-package', function () {
return vsce.createVSIX();
});

gulp.task('publish', function(callback) {
runSequence('build', 'add-i18n', 'vsce-publish', callback);
});

gulp.task('package', function(callback) {
runSequence('build', 'add-i18n', 'vsce-package', callback);
});

gulp.task('add-i18n', function () {
return gulp.src(['package.nls.json'])
.pipe(nls.createAdditionalLanguageFiles(nls.coreLanguages, 'i18n'))
.pipe(gulp.dest('.'));
});

gulp.task('transifex-push', function () {
return gulp.src('**/*.nls.json')
.pipe(nls.prepareXlfFiles(transifexProjectName, transifexExtensionName))
.pipe(nls.pushXlfFiles(transifexApiHostname, transifexApiName, transifexApiToken));
});

gulp.task('transifex-pull', function () {
return nls.pullXlfFiles(transifexApiHostname, transifexApiName, transifexApiToken, vscodeLanguages, [{ name: transifexExtensionName, project: transifexProjectName }])
.pipe(gulp.dest(`../${transifexExtensionName}-localization`));
});

gulp.task('i18n-import', function () {
return gulp.src(`../${transifexExtensionName}-localization/**/*.xlf`)
.pipe(nls.prepareJsonFiles())
.pipe(gulp.dest('./i18n'));
});
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
/*---------------------------------------------------------------------------------------------
* Copyright (c) Microsoft Corporation. All rights reserved.
* Licensed under the MIT License. See License.txt in the project root for license information.
*--------------------------------------------------------------------------------------------*/
// Do not edit this file. It is machine generated.
{
"VSND2001": "无法在 PATH 上找到运行时”{0}“。",
"VSND2011": "无法在终端({0})中启动调试目标。",
"VSND2017": "无法启动调试目标({0})。",
"VSND2028": "未知的控制台类型“{0}”。",
"VSND2002": "无法启动计划“{0}”;配置源映射可能会有帮助。",
"VSND2003": "无法启动程序”{0}“;设置”{1}“属性可能会有帮助。",
"VSND2029": "无法从文件({0})加载环境变量。"
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
/*---------------------------------------------------------------------------------------------
* Copyright (c) Microsoft Corporation. All rights reserved.
* Licensed under the MIT License. See License.txt in the project root for license information.
*--------------------------------------------------------------------------------------------*/
// Do not edit this file. It is machine generated.
{
"program.path.case.mismatch.warning": "程序路径与磁盘上的文件一样使用大小写不同的字符;这可能导致出现未被命中的断点。",
"node.console.title": "节点调试控制台",
"attribute.path.not.exist": "属性 \"{0}\" 不存在(\"{1}\")。",
"attribute.path.not.absolute": "属性”{0}“不是绝对的(”{1}“);可考虑将”{2}“添加为前缀以使其成为绝对。",
"VSND2001": "无法在 PATH 上找到运行时”{0}“。",
"more.information": "详细信息",
"origin.from.node": "Node.js 的只读内容",
"origin.core.module": "只读核心模块"
}
Loading

0 comments on commit f881c93

Please sign in to comment.