189 строки
7.5 KiB
Plaintext
189 строки
7.5 KiB
Plaintext
---------------
|
|
I. Introduction
|
|
---------------
|
|
|
|
Welcome to ClearScript!
|
|
|
|
ClearScript is a library that allows you to add scripting to your .NET
|
|
applications. It supports JScript and VBScript out of the box and in theory can
|
|
work with other Windows Script engines.
|
|
|
|
ClearScript 5 adds support for the V8 high-performance open-source JavaScript
|
|
engine. It allows you to use V8 with the same managed API and host integration
|
|
features as JScript and VBScript. V8 provides better performance, however, and
|
|
is more suitable for multi-threaded applications and asynchronous server-side
|
|
scripting.
|
|
|
|
See ClearScript\doc for information about using ClearScript.
|
|
|
|
------------------------
|
|
II. Building ClearScript
|
|
------------------------
|
|
|
|
The provided project and solution files support Visual Studio 2013 and 2015.
|
|
They produce architecture-neutral managed libraries that target .NET Framework
|
|
4.0. ClearScript has been tested with .NET Framework 4.5 as well. It does not
|
|
support older environments. The output directory is bin\[Debug|Release].
|
|
|
|
There are two ways to build ClearScript - with and without V8 support.
|
|
|
|
If you don't need V8 support, simply build the ClearScript.NoV8 solution using
|
|
Visual Studio. Note that this solution does not include test projects.
|
|
|
|
In order to build full ClearScript with V8 support, you must first acquire,
|
|
build, and import V8:
|
|
|
|
1. NOTE: This procedure and the V8Update script are provided for your
|
|
convenience. ClearScript does not include V8 source code, nor does it come
|
|
with any third-party software required to download and build V8. Rights to
|
|
V8 and its prerequisites are provided by their rights holders.
|
|
|
|
2. Install Git (http://www.git-scm.com/download/win). Ensure that Git is added
|
|
to your executable path by selecting the option "Use Git from the Windows
|
|
Command Prompt".
|
|
|
|
3. Install the latest Python 2.x (http://www.python.org/downloads/) and add it
|
|
to your executable path. V8's build process requires at least Python 2.7 and
|
|
does not support Python 3.x.
|
|
|
|
4. Unzip or clone the ClearScript source code into a convenient directory.
|
|
IMPORTANT: Ensure that the path to your ClearScript root directory does not
|
|
contain any non-ASCII characters.
|
|
|
|
5. Ensure that your Visual Studio installation includes C++ support.
|
|
|
|
6. Open a Visual Studio developer command prompt and run the V8Update script
|
|
from your ClearScript root directory:
|
|
|
|
C:\ClearScript> V8Update [/N] [Debug|Release] [Latest|Tested|<Revision>]
|
|
|
|
This script downloads the V8 source code and its prerequisites, builds
|
|
32-bit and 64-bit V8 shared libraries, and imports the results into
|
|
ClearScript. It requires approximately 2GB of additional disk space and does
|
|
not perform any permanent software installation on your machine.
|
|
|
|
The optional "/N" flag causes V8Update to reuse previously downloaded files
|
|
if possible. It's useful for switching between Debug and Release versions of
|
|
V8 and for testing local V8 modifications.
|
|
|
|
Specifying "Debug" or "Release" is optional; the default is Release. The
|
|
selected V8 variant will then be used for all ClearScript configurations.
|
|
|
|
By default, V8Update builds a V8 revision that has been tested with the
|
|
current version of ClearScript. If you'd like to use a specific revision
|
|
instead, place the desired branch name, commit ID, or tag on the V8Update
|
|
command line. Browse to https://chromium.googlesource.com/v8/v8.git to view
|
|
V8's revision history.
|
|
|
|
You are now ready to build the full ClearScript solution using Visual Studio.
|
|
|
|
NOTE: The first time you open the solution, Visual Studio may prompt you to
|
|
upgrade one or more projects to the latest platform toolset or .NET Framework.
|
|
We recommend that you select "Cancel" or "Don't Upgrade".
|
|
|
|
OPTIONAL: The ClearScript distribution includes a copy of the ClearScript
|
|
Library Reference in Compiled HTML (.CHM) format. If you'd like to rebuild this
|
|
file, use Sandcastle Help File Builder (SHFB, http://shfb.codeplex.com) with
|
|
the provided SHFB project file (ClearScript\doc\Reference.shfbproj).
|
|
|
|
------------------------------------------------------------
|
|
III. Building strong-named ClearScript assemblies (optional)
|
|
------------------------------------------------------------
|
|
|
|
ClearScript now includes optional support for building strong-named assemblies.
|
|
Use the following one-time procedure to enable this feature:
|
|
|
|
1. If the ClearScript solution is open in Visual Studio, close it.
|
|
|
|
2. Generate a cryptographic key pair in your ClearScript root directory:
|
|
|
|
C:\ClearScript> sn -k ClearScript.snk
|
|
|
|
3. Open the ClearScript solution in Visual Studio.
|
|
|
|
4. Click "Build" -> "Transform All T4 Templates".
|
|
|
|
5. Rebuild the solution.
|
|
|
|
Once you've performed these steps, the ClearScript assemblies you build will
|
|
have strong names.
|
|
|
|
---------------------------------------------------------------
|
|
IV. Integrating and deploying ClearScript with your application
|
|
---------------------------------------------------------------
|
|
|
|
Once you've built ClearScript, here's how to add it to your application:
|
|
|
|
1. Right-click your project in Visual Studio and select "Add Reference...".
|
|
|
|
2. In the Reference Manager window, click "Browse..." and locate your
|
|
ClearScript output directory (see above). Select ClearScript.dll, click
|
|
"Add", and then click "OK" to exit Reference Manager.
|
|
|
|
3. IMPORTANT: If you're using V8, you must also copy the following files from
|
|
your ClearScript output directory to your application's directory:
|
|
|
|
ClearScriptV8-32.dll
|
|
ClearScriptV8-64.dll
|
|
v8-ia32.dll
|
|
v8-x64.dll
|
|
|
|
For ASP.NET projects, we recommend that you add these assemblies as content
|
|
files at the root of your web application and set their "Copy to Output
|
|
Directory" properties to "Do not copy".
|
|
|
|
4. IMPORTANT: If Visual Studio is not installed on your deployment machine,
|
|
you must install 32-bit and 64-bit Visual C++ Redistributable packages:
|
|
|
|
Visual Studio 2013
|
|
http://www.microsoft.com/en-us/download/details.aspx?id=40784
|
|
|
|
Visual Studio 2015
|
|
http://www.microsoft.com/en-us/download/details.aspx?id=48145
|
|
|
|
------------------------------------
|
|
V. Debugging with ClearScript and V8
|
|
------------------------------------
|
|
|
|
V8 does not support standard Windows script debugging. Instead, it implements
|
|
its own TCP/IP-based debugging protocol. A convenient way to debug JavaScript
|
|
code running in V8 is to use the open-source Eclipse IDE:
|
|
|
|
1. Install Eclipse:
|
|
|
|
http://www.eclipse.org/downloads/
|
|
|
|
2. Install Google Chrome Developer Tools for Java:
|
|
|
|
a. Launch Eclipse and click "Help" -> "Install New Software...".
|
|
b. Paste the following URL into the "Work with:" field:
|
|
|
|
http://chromedevtools.googlecode.com/svn/update/dev/
|
|
|
|
c. Select "Google Chrome Developer Tools" and complete the dialog.
|
|
d. Restart Eclipse.
|
|
|
|
3. Enable script debugging in your application by invoking the V8ScriptEngine
|
|
constructor with V8ScriptEngineFlags.EnableDebugging and an available TCP/IP
|
|
port number. The default port number is 9222.
|
|
|
|
4. Attach the Eclipse debugger to your application:
|
|
|
|
a. In Eclipse, select "Run" -> "Debug Configurations...".
|
|
b. Right-click on "Standalone V8 VM" and select "New".
|
|
c. Fill in the correct port number and click "Debug".
|
|
|
|
Note that you can also attach Visual Studio to your application for
|
|
simultaneous debugging of script, managed, and native code.
|
|
|
|
-------------------
|
|
VI. Acknowledgments
|
|
-------------------
|
|
|
|
We'd like to thank:
|
|
|
|
1. The V8 team (https://code.google.com/p/v8/people/list).
|
|
|
|
2. Kenneth Reitz (http://kennethreitz.org) for generously providing the Httpbin
|
|
service (http://httpbin.org).
|