Browse Source

Merge branch 'remoteRoot' of nico/Indium into master

pull/10/head
Nicolas Petton 2 years ago
committed by Gitea
parent
commit
b88564f436
7 changed files with 125 additions and 78 deletions
  1. +36
    -30
      doc/Indium.texi
  2. +1
    -1
      server/README.md
  3. +14
    -17
      server/helpers/workspace.js
  4. +1
    -1
      server/package.json
  5. +55
    -11
      server/spec/helpers/workspace-spec.js
  6. +13
    -15
      sphinx-doc/debugger.rst
  7. +5
    -3
      sphinx-doc/setup.rst

+ 36
- 30
doc/Indium.texi View File

@ -21,7 +21,7 @@
@copying
@quotation
Indium 2.1.1, Sep 25, 2019
Indium 2.1.4, Oct 22, 2019
Nicolas Petton
@ -144,7 +144,7 @@ The stepping debugger
Using sourcemaps
* Overriding sourcemap paths::
* Overriding script paths::
* Setting a different remote root (NodeJS): Setting a different remote root NodeJS.
The inspector
@ -325,14 +325,11 @@ this @code{.indium.json} file is placed, but it can be overridden with the @code
@}
@end example
Custom script path overrides can be set with @code{scriptPathRegexpOverrides}. See
@ref{14,,Overriding script paths} for more information on script paths and debugging.
Custom sourcemap path overrides can be set with @code{sourceMapPathOverrides}. See
@ref{15,,Using sourcemaps} for more information on sourcemaps and debugging.
@ref{14,,Using sourcemaps} for more information on sourcemaps and debugging.
@node Chrome/Chromium configuration options,NodeJS configuration options,General configuration,Getting up and running
@anchor{setup chrome-chromium-configuration-options}@anchor{16}@anchor{setup chrome-configuration}@anchor{11}
@anchor{setup chrome-chromium-configuration-options}@anchor{15}@anchor{setup chrome-configuration}@anchor{11}
@subsection Chrome/Chromium configuration options
@ -365,7 +362,7 @@ Example configuration:
@end example
@node NodeJS configuration options,Starting Indium,Chrome/Chromium configuration options,Getting up and running
@anchor{setup nodejs-configuration}@anchor{10}@anchor{setup nodejs-configuration-options}@anchor{17}
@anchor{setup nodejs-configuration}@anchor{10}@anchor{setup nodejs-configuration-options}@anchor{16}
@subsection NodeJS configuration options
@ -402,6 +399,10 @@ Here is an example configuration for debugging Gulp tasks:
@}
@end example
When the NodeJS application runs on another computer (or inside a container like
Docker), a custom remote project root path can be set with @code{remoteRoot}. See
@ref{17,,Setting a different remote root (NodeJS)} for more information on script paths and debugging.
@node Starting Indium,NodeJS requirements,NodeJS configuration options,Getting up and running
@anchor{setup id2}@anchor{18}@anchor{setup starting-indium}@anchor{19}
@subsection Starting Indium
@ -727,7 +728,7 @@ The left fringe or margin can also be clicked to add or remove breakpoints.
Once a breakpoint is set, execution will stop when a breakpoint is hit, and the
Indium debugger pops up (see @ref{2b,,The stepping debugger}).
Since Indium 0.7, breakpoints are supported in source files with an associated sourcemap, see @ref{15,,Using sourcemaps}.
Since Indium 0.7, breakpoints are supported in source files with an associated sourcemap, see @ref{14,,Using sourcemaps}.
@cartouche
@quotation Note
@ -748,7 +749,7 @@ connection is made Indium will attempt to add back all breakpoints.
@end menu
@node Using sourcemaps,Blackboxing scripts,,The stepping debugger
@anchor{debugger sourcemaps}@anchor{15}@anchor{debugger using-sourcemaps}@anchor{2e}
@anchor{debugger sourcemaps}@anchor{14}@anchor{debugger using-sourcemaps}@anchor{2e}
@subsection Using sourcemaps
@ -769,11 +770,11 @@ source-mapped. This can happen for instance when using Webpack.
@menu
* Overriding sourcemap paths::
* Overriding script paths::
* Setting a different remote root (NodeJS): Setting a different remote root NodeJS.
@end menu
@node Overriding sourcemap paths,Overriding script paths,,Using sourcemaps
@node Overriding sourcemap paths,Setting a different remote root NodeJS,,Using sourcemaps
@anchor{debugger overriding-sourcemap-paths}@anchor{2f}@anchor{debugger webpack}@anchor{30}
@subsubsection Overriding sourcemap paths
@ -803,29 +804,34 @@ sourcemap paths using @code{M-x indium-list-sourcemap-sources}.
@end quotation
@end cartouche
@node Overriding script paths,,Overriding sourcemap paths,Using sourcemaps
@anchor{debugger overriding-script-paths}@anchor{31}@anchor{debugger scriptpaths}@anchor{14}
@subsubsection Overriding script paths
@node Setting a different remote root NodeJS,,Overriding sourcemap paths,Using sourcemaps
@anchor{debugger remoteroot}@anchor{17}@anchor{debugger setting-a-different-remote-root-nodejs}@anchor{31}
@subsubsection Setting a different remote root (NodeJS)
If your application’s script URLs don’t correspond directly to where
their source code is located, you can use @code{scriptPathRegexpOverrides} to
tell Indium where to find the sources. It maps regular expressions to
Javascript substitution strings.
When running a NodeJS application on a remote machine or inside a Docker
container, your application’s root folder path might not correspond to where
their source code is located on your local disk.
For example, if your project root is @code{/home/user/projects/foo/}, and
the source code for @indicateurl{http://localhost:3000/js/app.js/1234567890} is at
@code{/home/user/projects/foo/private/js/app.js}, you might set
@code{scriptPathRegexpOverrides} to:
In this case, you can tell Indium to replace the @code{root} path with a different
location using the @code{remoteRoot} configuration option.
@quotation
@table @asis
@item @{
“remoteRoot”: “/var/task”
@end table
@example
@{
"(/js/.*\\.js)/[0-9]+": "private$1"
@}
@end example
@end quotation
This removes the trailing slash and digits, and it adds “private” to
the beginning of the path below the project root.
Note that @code{remoteRoot} can be used together with the @code{root} configuration
option.
@node Blackboxing scripts,,Using sourcemaps,The stepping debugger
@anchor{debugger blackboxing-scripts}@anchor{32}
@ -998,7 +1004,7 @@ that the file where you’re trying to add a breakpoint is listed.
Correctly mapping sourcemaps to file locations can be tedious (see
@ref{15,,Using sourcemaps}).
@ref{14,,Using sourcemaps}).
Indium provides the command @code{indium-list-sourcemap-sources} to help
configuring sourcemaps correctly. This command displays a list of all


+ 1
- 1
server/README.md View File

@ -1,6 +1,6 @@
# Indium server
This documentation describes the version 4.0 of the server component of
This documentation describes the version 5.0 of the server component of
[Indium](https://indium.readthedocs.org).
The Indium server exposes a simple interface to communicate with a JS runtime


+ 14
- 17
server/helpers/workspace.js View File

@ -34,6 +34,7 @@ const isProjectFile = path =>
basename(path) === projectFilename;
const isAbsolute = path => {
// Also test for Windows paths
return path.startsWith("/") || /^[a-zA-Z]\:[\\\/]/.test(path);
};
@ -69,17 +70,15 @@ const resolveRoot = conf => {
return resolve(dir);
};
const locateScript = (pathname, conf) => {
let overrides = conf.scriptPathRegexpOverrides || {};
for (let pattern of Object.keys(overrides)) {
let regex = new RegExp(pattern);
const convertRemoteRoot = (path, conf) => {
if (!conf.remoteRoot) {
return path;
}
if (pathname.match(regex)) {
return pathname.replace(regex, overrides[pattern]);
}
}
return pathname;
return join(
resolveRoot(conf),
path.replace(new RegExp(`^${conf.remoteRoot}`), "")
);
};
const resolveUrl = (url, conf) => {
@ -87,19 +86,17 @@ const resolveUrl = (url, conf) => {
// always exist either, so also check for a protocol when parsed
// as a URL.
if (isAbsolute(url) || !parse(url).protocol) {
// console.log(`Resolved to ${url}`);
return url;
return convertRemoteRoot(url, conf);
}
let root = resolveRoot(conf);
let { protocol, pathname } = new URL(url);
// Always treat URLs using the file: protocol to have absolute pathnames.
let { protocol, pathname } = new URL(url);
if (protocol === "file:") {
return pathname;
return convertRemoteRoot(pathname, conf);
}
return resolve(`${root}/${locateScript(pathname, conf)}`);
let root = resolveRoot(conf);
return convertRemoteRoot(resolve(`${root}/${pathname}`), conf);
};
const expandRoot = (path, root = "") => {


+ 1
- 1
server/package.json View File

@ -1,6 +1,6 @@
{
"name": "indium",
"version": "4.0.0",
"version": "5.0.0",
"description": "Indium server",
"main": "index.js",
"scripts": {


+ 55
- 11
server/spec/helpers/workspace-spec.js View File

@ -209,7 +209,6 @@ describe("URL resolution", () => {
expect(resolveUrl(url, conf)).toEqual("/home/user/projects/foo/bar.js");
});
// Regression test for GH issue #161
it("does not transform the path when the file exists on Windows", () => {
let conf = {
@ -221,16 +220,61 @@ describe("URL resolution", () => {
expect(resolveUrl(url, conf)).toEqual(url);
});
it("supports script path regexp overrides", () => {
let conf = {
projectFile: "/home/user/projects/foo/.indium.json",
"scriptPathRegexpOverrides": {
"(/js/.*\\.js)/[0-9]+": "private$1"
}
};
describe("remote root replacement", () => {
it("Does not replace remote root when no remote root defined", () => {
let conf = {
projectFile: "/home/user/projects/foo/.indium.json"
};
let path = "/home/user/projects/foo/bar.js";
expect(resolveUrl(path, conf)).toEqual(path);
});
it("Replaces remote root when defined", () => {
let conf = {
projectFile: "/home/user/projects/foo/.indium.json",
remoteRoot: "/var/task/"
};
let path = "/var/task/bar.js";
expect(resolveUrl(path, conf)).toEqual("/home/user/projects/foo/bar.js");
});
it("Replaces local root with remote root when defined", () => {
let conf = {
projectFile: "/home/user/projects/foo/.indium.json",
root: "bar",
remoteRoot: "/var/task/"
};
let url = "http://localhost:3000/js/app.js/1234567890";
let path = "/var/task/baz.js";
expect(resolveUrl(path, conf)).toEqual("/home/user/projects/foo/bar/baz.js");
});
it("Replaces remote root with no trailing slash", () => {
let conf = {
projectFile: "/home/user/projects/foo/.indium.json",
remoteRoot: "/var/task"
};
let path = "/var/task/bar/baz.js";
expect(resolveUrl(path, conf)).toEqual("/home/user/projects/foo/bar/baz.js");
});
it("Replaces remote root with file:// protocol", () => {
let conf = {
projectFile: "/home/user/projects/foo/.indium.json",
remoteRoot: "/var/task/"
};
let path = "/var/task/bar.js";
expect(resolveUrl(path, conf)).toEqual("/home/user/projects/foo/bar.js");
});
});
expect(resolveUrl(url, conf)).toEqual("/home/user/projects/foo/private/js/app.js");
});
});

+ 13
- 15
sphinx-doc/debugger.rst View File

@ -44,29 +44,27 @@ Overriding the ``sourceMapPathOverrides`` option will erase the default mapping.
.. TIP:: If sourcemaps do not seem to work, you can see how Indium resolves
sourcemap paths using ``M-x indium-list-sourcemap-sources``.
.. _scriptpaths:
.. _remoteroot:
Overriding script paths
~~~~~~~~~~~~~~~~~~~~~~~
Setting a different remote root (NodeJS)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If your application's script URLs don't correspond directly to where
their source code is located, you can use ``scriptPathRegexpOverrides`` to
tell Indium where to find the sources. It maps regular expressions to
Javascript substitution strings.
When running a NodeJS application on a remote machine or inside a Docker
container, your application's root folder path might not correspond to where
their source code is located on your local disk.
For example, if your project root is ``/home/user/projects/foo/``, and
the source code for http://localhost:3000/js/app.js/1234567890 is at
``/home/user/projects/foo/private/js/app.js``, you might set
``scriptPathRegexpOverrides`` to::
In this case, you can tell Indium to replace the ``root`` path with a different
location using the ``remoteRoot`` configuration option.
{
"(/js/.*\\.js)/[0-9]+": "private$1"
...
"remoteRoot": "/var/task"
}
This removes the trailing slash and digits, and it adds "private" to
the beginning of the path below the project root.
Note that ``remoteRoot`` can be used together with the ``root`` configuration
option.
Blackboxing scripts
-------------------


+ 5
- 3
sphinx-doc/setup.rst View File

@ -48,9 +48,6 @@ this ``.indium.json`` file is placed, but it can be overridden with the ``root``
]
}
Custom script path overrides can be set with ``scriptPathRegexpOverrides``. See
:ref:`scriptpaths` for more information on script paths and debugging.
Custom sourcemap path overrides can be set with ``sourceMapPathOverrides``. See
:ref:`sourcemaps` for more information on sourcemaps and debugging.
@ -110,6 +107,11 @@ Here is an example configuration for debugging Gulp tasks::
]
}
When the NodeJS application runs on another computer (or inside a container like
Docker), a custom remote project root path can be set with ``remoteRoot``. See
:ref:`remoteroot` for more information on script paths and debugging.
.. _starting_indium:
Starting Indium


Loading…
Cancel
Save