Document the support of transpiled code by DominicKramer · Pull Request #277 · googleapis/cloud-debug-nodejs

DominicKramer · 2017-06-12T18:12:07Z

No description provided.

matthewloring

Looks good with a few nits.

README.md


 ![Breakpoint Hit](doc/images/breakpoint-hit.png?raw=true)

+Note that the directory layout of the code that is being debugged does not have to exactly match the source code specified in the Debug UI.  In particular, if a snapshot is specified in a file in the Debug UI, a breakpoint is set in the corresponding file in the code of the running instance that matches the most path components of the file specified in the Debug UI starting from the rightmost path component and working left.


README.md

+/running/instance/a/index.js
+/running/instance/b/a/index.js
+```
+Now suppose on your device you have a copy of the code as follows, and you have selected the local `/your/device` directory in the Debug UI as the directory containing the code to debug.


README.md

+
+In this case, if you specify a snapshot in file `/your/device/b/a/index.js` in the Debug UI, the debugger will identify that that file corresponds to the file `/running/instance/b/a/index.js` of the code on the running instance, and the breakpoint will hit when the specified line of `/running/instance/b/a/index.js` is reached.
+
+Note, however, if a snapshot is specified for the file `/your/device/a/index.js` in the Debug UI, then the debugger would not know whether this file corresponds to the file `/running/instance/a/index.js` or `/running/instance/b/a/index.js`.  If such an ambiguity occurs, a message will be displayed in the Debug UI.


README.md

+
+The debugger supports the use of transpiled code, whether it be Javascript to Javascript transpilation or transpilation from another language (such as Typescript) to Javascript.  In order to use transpiled code with the debugger, sourcemaps need to be generated with the transpiled code.  The sourcemaps can either be included inline in the transpiled code or provided in separate `.js.map` files.
+
+To use the debugger, the only files that are needed at runtime are the transpiled files as well as the generated sourcemap files (if the sourcemaps are not inlined).  In particular, the original source does not need to be available to the debugger at runtime.


README.md

+
+## Support for Transpiled Code
+
+The debugger supports the use of transpiled code, whether it be Javascript to Javascript transpilation or transpilation from another language (such as Typescript) to Javascript.  In order to use transpiled code with the debugger, sourcemaps need to be generated with the transpiled code.  The sourcemaps can either be included inline in the transpiled code or provided in separate `.js.map` files.


README.md

+```
+Now suppose on your local machine you have a copy of the code as follows, and you have selected the `/local/machine` directory in the Debug UI as the directory containing the code to debug.
+```
+/local/machine/package.json


README.md

+/local/machine/b/a/index.js
+```
+
+In this case, if you specify a snapshot in file `/local/machine/b/a/index.js` in the Debug UI, the debugger will identify that that file corresponds to the file `/running/instance/b/a/index.js` of the code on the running instance, and the breakpoint will hit when the specified line of `/running/instance/b/a/index.js` is reached.


README.md

+
+Note, however, if a snapshot is specified for the file `/local/machine/a/index.js` in the Debug UI, then the debugger would not know whether this file corresponds to the file `/running/instance/a/index.js` or `/running/instance/b/a/index.js`.  If such an ambiguity occurs, a message will be displayed in the Debug UI.
+
+In this case, the `appPathRelativeToRepository` configuration option can be used to specify the directory containing the application's `package.json` file to help resolve the ambiguity.  In the example above, if the `appPathRelativeToRepository` configuration option is set to `/local/machine`, the debugger would be able to identify `/running/instance/a/index.js` as the file where the breakpoint should be set.  See the [Debugger Agent Settings](#debugger-agent-settings) section for more information on configuring the debugger.


ofrobots

LGTM with some copy edits.

README.md


 ![Breakpoint Hit](doc/images/breakpoint-hit.png?raw=true)

+Note that the directory layout of the code that is being debugged does not have to exactly match the source code specified in the Debug UI.  In particular, if a snapshot is specified in a file in the Debug UI, a breakpoint is set in the deployed file with the longest matching path suffix.


README.md

+
+The debugger supports the use of transpiled code, whether it be Javascript to Javascript transpilation or transpilation from another language (such as Typescript) to Javascript.  In order to use transpiled code with the debugger, sourcemaps need to be generated with the transpiled code.  The sourcemaps need to be provided in `.js.map` files.
+
+To use the debugger, the only files that are needed in the deployment environment are the transpiled files as well as the generated sourcemap files.  In particular, the original source does not need to be available to the debugger in the deployment environment.


README.md

+
+To use the debugger, the only files that are needed in the deployment environment are the transpiled files as well as the generated sourcemap files.  In particular, the original source does not need to be available to the debugger in the deployment environment.
+
+Instead, the original source code is provided to the Debug UI to specify snapshots.  When specifying a snapshot in an original source file in the Debug UI, the corresponding file and line in the transpiled code is automatically determined based on the sourcemap files provided with the transpiled code at runtime.  See the [Using the Debugger](#using-the-debugger) section for more information about using the Debug UI.  In addition, the exact directory layout of the original source is somewhat flexible, just as it is with the use of non-transpiled code as described in the [Using the Debugger](#using-the-debugger) section.


README.md

+
+In this case, if you specify a snapshot in file `b/a/index.js` in the Debug UI, the debugger will identify that that file corresponds to the file `/running/instance/b/a/index.js` of the code on the running instance, and the breakpoint will hit when the specified line of `/running/instance/b/a/index.js` is reached.
+
+Note, however, if a snapshot is specified for the file `a/index.js` in the Debug UI, then the debugger would not know whether this file corresponds to the file `/running/instance/a/index.js` or `/running/instance/b/a/index.js`.  If such an ambiguity occurs, a message will be displayed in the Debug UI.


Document the support of transpiled code

619e7ee

googlebot added the cla: yes This human has signed the Contributor License Agreement. label Jun 12, 2017

jmdobry added the in progress label Jun 12, 2017

DominicKramer requested a review from ofrobots June 12, 2017 18:12

matthewloring approved these changes Jun 12, 2017

View reviewed changes

matthewloring reviewed Jun 12, 2017

View reviewed changes

Address GitHub comments

184ccb8

ofrobots suggested changes Jun 13, 2017

View reviewed changes

Address GitHub comments

943088f

ofrobots approved these changes Jun 15, 2017

View reviewed changes

kjin reviewed Jun 15, 2017

View reviewed changes

Address GitHub comments

6789380

DominicKramer merged commit e3c4853 into googleapis:master Jun 15, 2017

jmdobry removed the in progress label Jun 15, 2017

matthewloring mentioned this pull request Jun 19, 2017

Add docs explaining source map requirements #266

Closed


		![Breakpoint Hit](doc/images/breakpoint-hit.png?raw=true)

		Note that the directory layout of the code that is being debugged does not have to exactly match the source code specified in the Debug UI. In particular, if a snapshot is specified in a file in the Debug UI, a breakpoint is set in the corresponding file in the code of the running instance that matches the most path components of the file specified in the Debug UI starting from the rightmost path component and working left.


		In this case, if you specify a snapshot in file `/your/device/b/a/index.js` in the Debug UI, the debugger will identify that that file corresponds to the file `/running/instance/b/a/index.js` of the code on the running instance, and the breakpoint will hit when the specified line of `/running/instance/b/a/index.js` is reached.

		Note, however, if a snapshot is specified for the file `/your/device/a/index.js` in the Debug UI, then the debugger would not know whether this file corresponds to the file `/running/instance/a/index.js` or `/running/instance/b/a/index.js`. If such an ambiguity occurs, a message will be displayed in the Debug UI.


		The debugger supports the use of transpiled code, whether it be Javascript to Javascript transpilation or transpilation from another language (such as Typescript) to Javascript. In order to use transpiled code with the debugger, sourcemaps need to be generated with the transpiled code. The sourcemaps can either be included inline in the transpiled code or provided in separate `.js.map` files.

		To use the debugger, the only files that are needed at runtime are the transpiled files as well as the generated sourcemap files (if the sourcemaps are not inlined). In particular, the original source does not need to be available to the debugger at runtime.


		## Support for Transpiled Code

		The debugger supports the use of transpiled code, whether it be Javascript to Javascript transpilation or transpilation from another language (such as Typescript) to Javascript. In order to use transpiled code with the debugger, sourcemaps need to be generated with the transpiled code. The sourcemaps can either be included inline in the transpiled code or provided in separate `.js.map` files.


		Note, however, if a snapshot is specified for the file `/local/machine/a/index.js` in the Debug UI, then the debugger would not know whether this file corresponds to the file `/running/instance/a/index.js` or `/running/instance/b/a/index.js`. If such an ambiguity occurs, a message will be displayed in the Debug UI.

		In this case, the `appPathRelativeToRepository` configuration option can be used to specify the directory containing the application's `package.json` file to help resolve the ambiguity. In the example above, if the `appPathRelativeToRepository` configuration option is set to `/local/machine`, the debugger would be able to identify `/running/instance/a/index.js` as the file where the breakpoint should be set. See the [Debugger Agent Settings](#debugger-agent-settings) section for more information on configuring the debugger.


		To use the debugger, the only files that are needed in the deployment environment are the transpiled files as well as the generated sourcemap files. In particular, the original source does not need to be available to the debugger in the deployment environment.

		Instead, the original source code is provided to the Debug UI to specify snapshots. When specifying a snapshot in an original source file in the Debug UI, the corresponding file and line in the transpiled code is automatically determined based on the sourcemap files provided with the transpiled code at runtime. See the [Using the Debugger](#using-the-debugger) section for more information about using the Debug UI. In addition, the exact directory layout of the original source is somewhat flexible, just as it is with the use of non-transpiled code as described in the [Using the Debugger](#using-the-debugger) section.

Conversation

DominicKramer commented Jun 12, 2017

Uh oh!

matthewloring left a comment

Choose a reason for hiding this comment

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

ofrobots left a comment

Choose a reason for hiding this comment

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants