Skip to content

Commit c2d5fb6

Browse files
zlovattzlovatt
committed
Add articles on the VS Code debugger
1 parent 1b29503 commit c2d5fb6

File tree

5 files changed

+293
-12
lines changed

5 files changed

+293
-12
lines changed

‎docs/extendscript-toolkit/index.rst‎

Lines changed: 20 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,23 +2,31 @@
22

33
The ExtendScript Toolkit
44
========================
5-
The ExtendScript Toolkit provides an interactive development and testing environment for ExtendScript in
6-
all JavaScript-enabled Adobe applications. It includes a full-featured, syntax-highlighting text editor with
7-
Unicode capabilities and multiple undo/redo support. The Toolkit is the default editor for ExtendScript
8-
files, which use the extension .jsx.
5+
6+
.. warning::
7+
8+
The Extendscript Toolkit has been deprecated in favour of :ref:`the-vscode-debugger`!
9+
10+
This information is preserved here for legacy reference, but the Extendscript Toolkit is no longer being actively maintained or supported, and will no longer work on 64-bit-only versions of MacOS.
11+
12+
The ExtendScript Toolkit provides an interactive development and testing environment for ExtendScript in all JavaScript-enabled Adobe applications.
13+
14+
It includes a full-featured, syntax-highlighting text editor with Unicode capabilities and multiple undo/redo support. The Toolkit is the default editor for ExtendScript files, which use the extension .jsx.
915

1016
The Toolkit includes a JavaScript debugger that allows you to:
1117

1218
- Single-step through JavaScript scripts (JS or JSX files) inside an application.
1319
- Inspect all data for a running script.
1420
- Set and execute breakpoints.
1521

16-
When you double click a JSX file in the platform's windowing environment, the script runs in the Toolkit,
17-
unless it specifies a particular target application using the #target directive. For more information, see
18-
:ref:`selecting-a-debugging-target` and :ref:`preprocessor-directives`.
22+
When you double click a JSX file in the platform's windowing environment, the script runs in the Toolkit, unless it specifies a particular target application using the #target directive.
23+
24+
For more information, see :ref:`selecting-a-debugging-target` and :ref:`preprocessor-directives`.
25+
26+
.. tip::
27+
28+
When you have completed editing and debugging your JavaScript script, you can choose to save it as a binary file (with the extension JSXBIN), using ``File > Export as Binary``.
29+
30+
The script loader recognizes both source code and compiled code. Photoshop and After Effects can execute compiled scripts.
1931

20-
.. tip:: When you have completed editing and debugging your JavaScript script, you can choose to save it as
21-
a binary file (with the extension JSXBIN), using ``File > Export as Binary``. The script loader recognizes both
22-
source code and compiled code. Photoshop and After Effects can execute compiled scripts. If an application
23-
recognizes the execution of compiled JavaScript, it lists JSXBIN files along with JSX files in any list of
24-
available scripts.
32+
If an application recognizes the execution of compiled JavaScript, it lists JSXBIN files along with JSX files in any list of available scripts.

‎docs/index.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,14 @@ Welcome to The Javascript Tools Guide
99
introduction/extendscript-overview
1010
introduction/scripting-for-specific-applications
1111

12+
.. toctree::
13+
:maxdepth: 2
14+
:caption: The VS Code ExtendScript Debugger
15+
16+
vscode-debugger/index
17+
vscode-debugger/getting-started-with-vscode-debugger
18+
vscode-debugger/vscode-extension-features
19+
1220
.. toctree::
1321
:maxdepth: 2
1422
:caption: The ExtendScript Toolkit

‎docs/vscode-debugger/getting-started-with-vscode-debugger.rst‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
.. _getting-started-with-vscode-debugger:
2+
3+
Getting Started with the VS Code Debugger
4+
=========================================
5+
6+
Unlike the ExtendScript Toolkit, the VS Code debugger takes some work to get up and running. This document is intended to make that process as straightforward as possible.
7+
8+
.. note::
9+
10+
This guide is meant to walk you through how to install and run the Extendscript for VS Code debugger.
11+
12+
If you're looking on how to use specific features of the extension, see :ref:`vscode-extension-features`.
13+
14+
Generally, you'll need to follow these steps:
15+
16+
- :ref:`installing-the-extension`
17+
- :ref:`opening-a-project`
18+
- :ref:`creating-a-debug-launch-task`
19+
- :ref:`attaching-the-debugger`
20+
- :ref:`running-the-debugger`
21+
- :ref:`further-reading`
22+
23+
--------------------------------------------------------------------------------
24+
25+
.. _installing-the-extension:
26+
27+
Installing the extension
28+
------------------------
29+
30+
Either head to the `extension marketplace link <https://marketplace.visualstudio.com/items?itemName=Adobe.extendscript-debug>`_ and install from there, or search "ExtendScript Debugger" within VS Code's extension browser and install.
31+
32+
If you're going the latter route, make sure you're installing the one from Adobe!
33+
34+
--------------------------------------------------------------------------------
35+
36+
.. _opening-a-project:
37+
38+
Opening a project directory
39+
---------------------------
40+
41+
- `File > Open Folder`
42+
- Choose your project directory
43+
44+
--------------------------------------------------------------------------------
45+
46+
.. _creating-a-debug-launch-task:
47+
48+
Creating a debug launch task
49+
----------------------------
50+
51+
To use the extension, you need to create a debug task for VS Code to run when you want to debug extendscript.
52+
53+
In your project directory:
54+
55+
- create a folder called `.vscode` (with the period)
56+
- in that folder, create a file `launch.json`
57+
- paste in the following code
58+
::
59+
60+
{
61+
"version": "0.2.0",
62+
"configurations": [
63+
{
64+
"type": "extendscript-debug",
65+
"request": "launch",
66+
"name": "Run Current Script",
67+
"program": "${file}",
68+
"stopOnEntry": false,
69+
"excludes": [
70+
"undefined",
71+
"builtin",
72+
// "Function",
73+
"prototype"
74+
],
75+
}
76+
]
77+
}
78+
79+
- this will let you run the debugger on the *currently open file*
80+
- it also keeps functions included in the default object browser during breakpoints, which are otherwise excluded
81+
82+
If you wanted to run a task on a specific file, not necessarily the currently-open one, you'd replace the `program` entry with something like:
83+
84+
- For a specific script::
85+
86+
"${workspaceFolder}/path/to/my/script.jsx"
87+
88+
- To be prompted for the filename / path to a jsx folder::
89+
90+
"${workspaceFolder}/${command:AskForScriptName}"
91+
92+
--------------------------------------------------------------------------------
93+
94+
.. _attaching-the-debugger:
95+
96+
Attaching the debugger
97+
----------------------
98+
99+
Once the extension is installed:
100+
101+
- Open a JS workspace
102+
- Launch your Adobe app of choice
103+
- At the bottom of your VS Code window, at the far right of the status bar, you should see 'Select the target application' glowing yellow
104+
- Click this and pick the application you want to debug for
105+
106+
--------------------------------------------------------------------------------
107+
108+
.. _running-the-debugger:
109+
110+
Running the debugger
111+
--------------------
112+
113+
Once you've set up your environment and built your script:
114+
115+
- In VS Code, Debug > Start Debugging > 'Run Current Script' (or the task name you specified in :ref:`creating-a-debug-launch-task`
116+
- If the script throws any errors, you'll be able to view variables & a call stack
117+
118+
.. note::
119+
120+
If you're compiling the end jsx file from a number of source files, the debugger will catch errors in the *compiled* script, not the source files -- you'll need to backtrack yourself to figure out what source file the error came from, unless you're building source maps in some way.
121+
122+
This may not apply to compiled files using `#include`
123+
124+
--------------------------------------------------------------------------------
125+
126+
.. _further-reading:
127+
128+
Futher reading
129+
--------------
130+
131+
- `Debugging in VS Code <https://code.visualstudio.com/docs/editor/debugging>`_

‎docs/vscode-debugger/index.rst‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
.. _the-vscode-debugger:
2+
3+
The VS Code Debugger
4+
====================
5+
6+
Since :ref:`the-extendscript-toolkit` has been deprecated by Adobe (in part due to MacOS dropping support for 32-bit apps), the official method of debugging Extendscript is by using `VS Code <https://code.visualstudio.com/>`_ with the `Adobe Extendscript extension <https://marketplace.visualstudio.com/items?itemName=Adobe.extendscript-debug>`_.
7+
8+
It's semi-buggy, generally unreliable, and seems to be meant for self-contained instant-run scripts (as opposed to ScriptUI panels), but it can be helpful in some cases.
9+
10+
The docs here are currently in progress and are ever-evolving; contributions are encouraged and welcome!
11+
12+
- :ref:`getting-started-with-vscode-debugger`
13+
- :ref:`vscode-extension-features`
14+
15+
--------------------------------------------------------------------------------
16+
17+
External Links
18+
--------------
19+
20+
For information on the history of and official announcements about the VS Code debugger, see the following:
21+
22+
- `ExtendScript Debugger for Visual Studio Code Public Release <https://medium.com/adobetech/extendscript-debugger-for-visual-studio-code-public-release-a2ff6161fa01>`_
23+
- `The Future of ExtendScript Development: A VSCode Plugin <https://medium.com/adobetech/the-future-of-extendscript-development-a-vscode-plugin-2d8d0172a357>`_

‎docs/vscode-debugger/vscode-extension-features.rst‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
.. _vscode-extension-features:
2+
3+
VS Code Extension Features
4+
==========================
5+
6+
Once you have the Extendscript VS Code Extension up and running, there are a few other things you can do; :ref:`export to jsxbin <exporting-as-binary>`, :ref:`use breakpoints in your code <using-breakpoint>`, and more.
7+
8+
.. note::
9+
10+
This guide is meant to give insight on how to use specific Extendscript for VS Code features.
11+
12+
If you're looking on how to get up and running with the extension, see :ref:`getting-started-with-vscode-debugger`.
13+
14+
--------------------------------------------------------------------------------
15+
16+
.. _using-breakpoint:
17+
18+
Using Breakpoints
19+
-----------------
20+
21+
Breakpoints allow you to stop your code running at a specific line, letting you explore the call stack, variable status, and function arguments at that exact point.
22+
23+
You can create breakpoints one of two ways; either using :ref:`VS Code's native Breakpoints system <vs-code-breakpoints>`, or using :ref:`Extendscript's inline breakpoint method <extendscript-breakpoints>`.
24+
25+
.. _vs-code-breakpoints:
26+
27+
VS Code Breakpoints
28+
*******************
29+
30+
One advantage of using VS Code is that we can set VS Code breakpoints and have the debugger respect them! See the official `Visual Studio article on breakpoints <https://code.visualstudio.com/docs/editor/debugging#_breakpoints>`_.
31+
32+
.. _extendscript-breakpoints:
33+
34+
Extendscript Breakpoints
35+
************************
36+
37+
You can add in ``$.bp()`` anywhere in your source file, and the debugger will catch on it at the correct place, allowing you to view the call stack / data browser at that point.
38+
39+
This works identically to the ``debugger;`` method in browser-based Javascript.
40+
41+
See :ref:`dollar-bp` for more info.
42+
43+
--------------------------------------------------------------------------------
44+
45+
.. _exporting-as-binary:
46+
47+
Exporting as Binary
48+
-------------------
49+
50+
In the old Extendscript ToolKit, you could very easily save your projects as an obfuscated binary file. This functionality still exists in the VS Code debugger!
51+
52+
You can export either :ref:`from the vscode interface <jsxbin-from-vs-code>`, or :ref:`via the command line <jsxbin-from-the-command-line>`.
53+
54+
.. _jsxbin-from-vs-code:
55+
56+
JSXBIN from VS Code
57+
*******************
58+
59+
To export your script as binary, you have a few options:
60+
61+
- With the file open, right-click the document and press 'Export as Binary'
62+
- Open the command palette (Ctrl + Shift + P) and type 'Export as Binary'
63+
- Use the keyboard shortcut for the same command (Ctrl + Shift + J)
64+
65+
.. _jsxbin-from-the-command-line:
66+
67+
JSXBIN from the Command Line
68+
****************************
69+
70+
The VS Code extension allows you to export either single files or entire directories via the command line, but it takes a bit of work on your end.
71+
72+
.. warning::
73+
74+
While there is a built-in way to do it, it can be a fairly unfriendly process. As an alternative, consider the gulp-accessible `npm package jsxbin <https://www.npmjs.com/package/jsxbin>`_. It does the same as below, but with much less user involvement.
75+
76+
There are reports that this package has issues on Windows. As an alternative gulp task, you can try `this script <https://bitbucket.org/motiondesign/workspace/snippets/aLzaX5>`_ from `Justin Taylor <http://justintaylor.tv/>`_.
77+
78+
Both methods above require the VS Code extension be installed.
79+
80+
All of the files are saved in the same directory with the same filename (though the suffix will be .jsxbin). Any passed directories will be recursively traversed.
81+
82+
1. Within the Extension install directory, there's a ``exportToJSX.js`` script file that accepts a file path or directory to convert. We need to get this path.
83+
84+
- Note that you'll need to swap `X.X.X` with the current version #
85+
- MacOS: ``$HOME/.vscode/extensions/adobe.extendscript-debug-X.X.X/public-scripts/exportToJSX.js``
86+
- Windows: ``%USERPROFILE%\.vscode\extensions\adobe.extendscript-debug-X.X.X\public-scripts\exportToJSX.js``
87+
2. This script accepts a few arguments;
88+
89+
- ``-f``, ``--force``: Overwrite the '.jsxbin' file/files if already exists
90+
- ``-n``, ``--name``: The '.js/.jsx' script path or path to some directory having these files.
91+
- ``h``, ``--help``: Show this help and exit
92+
3. Running the script
93+
94+
- From your command line, run ``node path/to/exportToJSX.js [options] [file/directory]``
95+
96+
.. _examples:
97+
98+
Examples
99+
########
100+
101+
**Exporting a single script**
102+
103+
::
104+
105+
sh node "C:/Users/Dev/.vscode/extensions/adobe.extendscript-debug-1.1.2/public-scripts/exportToJSX.js" "d:/projects/scripting/coolTool.jsx"
106+
107+
**Exporting a folder, overwriting**
108+
109+
::
110+
111+
sh node "C:/Users/Dev/.vscode/extensions/adobe.extendscript-debug-1.1.2/public-scripts/exportToJSX.js" --force "d:/projects/scripting/"

0 commit comments

Comments
 (0)