163 строки
6.9 KiB
Plaintext
163 строки
6.9 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 require Visual Studio 2012. 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 Subversion (http://subversion.apache.org/packages.html) and add it
|
|
to your executable path.
|
|
|
|
3. 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 downloads 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 trunk revision number on the V8Update command
|
|
line. To use the latest stable trunk revision, specify "Latest". Go to
|
|
http://code.google.com/p/v8/source/list to view V8's revision history.
|
|
|
|
You are now ready to build the full ClearScript solution using Visual Studio.
|
|
|
|
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. 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
|
|
|
|
In addition, if Visual Studio is not installed on the deployment machine,
|
|
you must install 32-bit and 64-bit Visual C++ Redistributable packages:
|
|
|
|
http://www.microsoft.com/en-us/download/details.aspx?id=30679
|
|
|
|
-------------------------------------
|
|
IV. 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.
|
|
|
|
------------------
|
|
V. V8 Known Issues
|
|
------------------
|
|
|
|
1. V8 doesn't support indexers - properties with one or more parameters. Given
|
|
the general syntax "A.B(C,D) = E" where A is an external object, JScript
|
|
performs a single operation that assigns E to A's property B with index
|
|
arguments C and D. This syntax allows for multiple indices and arbitrary
|
|
index types. V8 interprets it as an attempt to use a value on the left side
|
|
of an assignment - something that makes no sense in JavaScript. JScript's
|
|
behavior appears to be an extension, but it's a convenient one because
|
|
indexers are common in the CLR.
|
|
|
|
WORKAROUND: ClearScript supports the alternate syntax "A.B.set(C,D,E)".
|
|
|
|
2. V8 doesn't support default properties. This is only an issue in conjunction
|
|
with (1). The problematic syntax is of the form "A(B, C) = D", which in
|
|
JScript means "assign D to external object A's default property with index
|
|
arguments B and C".
|
|
|
|
WORKAROUND: ClearScript supports the alternate syntax "A.set(B,C,D)".
|
|
|
|
3. V8 treats properties and methods identically. A method call is simply the
|
|
invocation of a property. This causes ambiguity when an object has both a
|
|
property and a method with the same name. An example of this in the CLR is
|
|
an instance of System.Collections.Generic.List with LINQ extensions; such
|
|
an object has both a property and a method named Count.
|
|
|
|
WORKAROUND: None.
|