This article needs a technical review. How you can help.
These release notes are an incomplete draft.
SpiderMonkey 31 is supported on all the platforms where Firefox 31 runs. Compiling it requires a C++ compiler, and the JSAPI can only be used from C++ code. If you are compiling with Microsoft's Visual Studio, note that the minimum supported version is MSVC10/2010: MSVC8/9 support has been dropped.
Migrating to SpiderMonkey 31
The first change most embedders will notice is that SpiderMonkey must now be initialized before it can be used, using the newly-repurposed
JS_Init method. After this method is called, normal JSAPI operations are permitted. When all JSAPI operation has completed, the corresponding
JS_ShutDown method (currently non-mandatory, but highly recommended as it may become mandatory in the future) uninitializes SpiderMonkey, cleaning up memory and allocations performed by
A major change to SpiderMonkey in 31 is that its APIs support a moving garbage collector. This entailed changing the vast majority of the JSAPI from raw types, such as
JS::MutableHandle template types that encapsulate access to the provided value/string/object or its location. The
JS::MutableHandle<JS::Value> classes have been specialized to implement the same interface as
JS::Value, for simplicity and to ease migration pain. Changes to introduce handles to the JSAPI are not individually documented, because of the breadth of the changes involved.
The following features in earlier versions of SpiderMonkey have been dropped.
- XXX list removed features here
SpiderMonkey 31 is not binary-compatible with previous releases, nor is it source-code compatible. Many JSAPI types, functions, and callback signatures have changed, though most functions that have changed still have the same names and implement essentially unchanged functionality. Applications will need significant changes, but most of those changes will be detected by the C/C++ compiler, so they are easy to detect and updating the code is a fairly straightforward job. Here is a list of the most significant changes:
- Many of the garbage collector changes require type signature changes to JSAPI methods: specifically introducing
JS::MutableHandletypes. These types, with the appropriate parametrizations, can roughly be substituted for plain types of GC things (values, string/object pointers, etc.).
JSBooltype has been removed, along with the corresponding
JS_FALSEconstants. They have been replaced by
js::Classinstances are now explicitly
const, and several APIs have been updated to use
const JSClass *and
const js::Class *pointers.
- All references to shortid/tinyid have been removed. That includes the APIs
JS_DefineUCPropertyWithTinyIdas well as the
JSPropertyDescriptorstructure and the matching
These and other changes are explained in detail below.
New C++ APIs
JSAPI is now a C++-only API. Please note that SpiderMonkey reserves the
JS:: namespace for itself (and the
js:: namespace for internal use).
JS_Initis a new function which must be used to initialize the JS engine before any
JSRuntimes are created or other JSAPI methods are called. This method pairs with the existing (currently non-mandatory)
JS_ShutDownmethod, which uninitializes the JS engine after all runtimes have been destroyed.
JS_SetICUMemoryFunctionsis a new function which can be used to set the allocation and deallocation functions used by the ICU internationalization library. This is unlikely to be of interest to embedders unless you are doing detailed memory profiling. It must be called before
- JS_ConvertArguments "j" type
- JS_NewGrowableString (can be replaced with JS_NewUCString)
- JS_IsConstructing (can be replaced with CallArgs::isConstructing or CallReceiver::isConstructing)
- JS_ValueToBoolean (replaced by JS::ToBoolean)
- JS_ValueToNumber (can be replaced with JS::ToNumber)
- JS_ValueToInt64 (replaced by JS::ToInt64)
- JS_ValueToUint64 (replaced by JS::ToUint64)
- JS_ValueToECMAUint32 (replaced by JS::ToUint32)
- JS_ValueToECMAInt32 (replaced by JS::ToInt32)
- JS_ValueToInt32 (can be replaced with JS::ToInt32, which has a different behavior!)
- JS_ValueToUint16 (replaced by JS::ToUint16)
- JS_ValueToString (replaced by JS::ToString)
SpiderMonkey must now be initialized before it can be used. This is performed by calling the new
JS_Init method before creating any runtimes or contexts and before compiling, evaluating, or executing any JS script. Once this method has been successfully called, it's okay to call
JS_NewRuntime and all the other existing SpiderMonkey APIs as usual. Once all JSAPI operation has completed, the corresponding
JS_ShutDown method uninitializes SpiderMonkey, cleaning up memory and allocations performed by
JS_Init. It is not required to call
JS_ShutDown at present, but it is strongly recommended: calling it may be required in a future SpiderMonkey release.
Detail added/removed methods here...
On POSIX platforms, building a threadsafe shell no longer requires NSPR. Embedders still need to build with NSPR, as the new wrappers require using SpiderMonkey internal functions which are not exposed to the public API.
Detail any known issues here...
...insert details on future plans...
SpiderMonkey embedders should be aware that
- Mozilla has no plans to keep the JSAPI, nor the JSDBGAPI stable for embedders. We have chosen to concentrate on performance and correctness as primary concerns instead.
- JS_THREADSAFE is going away, with future versions supporting only thread-safe builds
- A new debugging API is on the way to replace JSD.
Release Notes Errata
This is a list of changes which need to be made to the release notes ASAP. Feel free to fix any problems you spot -- this is a Wiki!
- Don't add anything here -- this is for after the release notes are completed. :-)