AuroraMiddleware/v8
1
0
Fork 0
Code Issues 2 Pull Requests Releases Wiki Activity

[Docs] Removed unused docs because they are moved to GitHub

Browse Source 
R=machenbach@chromium.org
NOTRY=true

Review URL: https://codereview.chromium.org/1459823002

Cr-Commit-Position: refs/heads/master@{#32105}
This commit is contained in:
hablich 2015-11-19 02:23:12 -08:00 committed by Commit bot
parent a8e86c49ec
commit daa6e64d6a
25 changed files with 5 additions and 2640 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
README.md
View File

@ -10,7 +10,7 @@ browser from Google.
V8 can run standalone, or can be embedded into any C++ application.
V8 Project page: https://code.google.com/p/v8/
V8 Project page: https://github.com/v8/v8/wiki
Getting the Code
@ -37,4 +37,4 @@ Contributing
=============
Please follow the instructions mentioned on the
[V8 wiki](https://code.google.com/p/v8-wiki/wiki/Contributing).
[V8 wiki](https://github.com/v8/v8/wiki/Contributing).

2
docs/README.md Normal file
View File

@ -0,0 +1,2 @@
The documentation for V8 can be found at the
[V8 Wiki](https://github.com/v8/v8/wiki).

205
docs/arm_debugging_with_the_simulator.md
View File

@ -1,205 +0,0 @@
# ARM debugging with the simulator
The simulator and debugger can be very helpful when working with v8 code generation.
* It is convenient as it allows you to test code generation without access to actual hardware.
* No cross or native compilation is needed.
* The simulator fully supports the debugging of generated code.
Please note that this simulator is designed for v8 purposes. Only the features used by v8 are implemented, and you might encounter unimplemented features or instructions. In this case, feel free to implement them and submit the code!
## Details on the ARM Debugger
Compile the ARM simulator shell with:
```
make arm.debug
```
on an x86 host using your regular compiler.
### Starting the Debugger
There are different ways of starting the debugger:
```
$ out/arm.debug/d8 --stop_sim_at <n>
```
The simulator will start the debugger after executing n instructions.
```
$ out/arm.debug/d8 --stop_at <function name>
```
The simulator will stop at the given JavaScript function.
Also you can directly generate 'stop' instructions in the ARM code. Stops are generated with
```
Assembler::stop(const char* msg, Condition cond, int32_t code)
```
When the Simulator hits a stop, it will print msg and start the debugger.
### Debugging commands.
**Usual commands:**
Enter `help` in the debugger prompt to get details on available commands. These include usual gdb-like commands, such as stepi, cont, disasm, etc. If the Simulator is run under gdb, the “gdb” debugger command will give control to gdb. You can then use cont from gdb to go back to the debugger.
**Debugger specific commands:**
Here's a list of the ARM debugger specific commands, along with examples.
The JavaScript file “func.js” used below contains:
```
function test() {
print(“In function test.”);
}
test();
```
* **printobject** `<`register`>` (alias po), will describe an object held in a register.
```
$ out/arm.debug/d8 func.js --stop_at test
Simulator hit stop-at
0xb544d6a8 e92d4902 stmdb sp!, {r1, r8, fp, lr}
sim> print r0
r0: 0xb547ec15 -1253577707
sim> printobject r0
r0:
0xb547ec15: [Function]
- map = 0x0xb540ff01
- initial_map =
- shared_info = 0xb547eb2d <SharedFunctionInfo>
- name = #test
- context = 0xb60083f1 <FixedArray[52]>
- code = 0xb544d681 <Code>
#arguments: 0xb545a15d <Proxy> (callback)
#length: 0xb545a14d <Proxy> (callback)
#name: 0xb545a155 <Proxy> (callback)
#prototype: 0xb545a145 <Proxy> (callback)
#caller: 0xb545a165 <Proxy> (callback)
```
* **break** `<`address`>`, will insert a breakpoint at the specified address.
* **del**, will delete the current breakpoint.
You can have only one such breakpoint. This is useful if you want to insert a breakpoint at runtime.
```
$ out/arm.debug/d8 func.js --stop_at test
Simulator hit stop-at
0xb53a1ee8 e92d4902 stmdb sp!, {r1, r8, fp, lr}
sim> disasm 5
0xb53a1ee8 e92d4902 stmdb sp!, {r1, r8, fp, lr}
0xb53a1eec e28db008 add fp, sp, #8
0xb53a1ef0 e59a200c ldr r2, [r10, #+12]
0xb53a1ef4 e28fe004 add lr, pc, #4
0xb53a1ef8 e15d0002 cmp sp, r2
sim> break 0xb53a1ef8
sim> cont
0xb53a1ef8 e15d0002 cmp sp, r2
sim> disasm 5
0xb53a1ef8 e15d0002 cmp sp, r2
0xb53a1efc 359ff034 ldrcc pc, [pc, #+52]
0xb53a1f00 e5980017 ldr r0, [r8, #+23]
0xb53a1f04 e59f1030 ldr r1, [pc, #+48]
0xb53a1f08 e52d0004 str r0, [sp, #-4]!
sim> break 0xb53a1f08
setting breakpoint failed
sim> del
sim> break 0xb53a1f08
sim> cont
0xb53a1f08 e52d0004 str r0, [sp, #-4]!
sim> del
sim> cont
In function test.
```
* Generated `stop` instuctions, will work as breakpoints with a few additional features.
The first argument is a help message, the second is the condition, and the third is the stop code. If a code is specified, and is less than 256, the stop is said to be “watched”, and can be disabled/enabled; a counter also keeps track of how many times the Simulator hits this code.
If we are working on this v8 C++ code, which is reached when running our JavaScript file.
```
__ stop("My stop.", al, 123);
__ mov(r0, r0);
__ mov(r0, r0);
__ mov(r0, r0);
__ mov(r0, r0);
__ mov(r0, r0);
__ stop("My second stop.", al, 0x1);
__ mov(r1, r1);
__ mov(r1, r1);
__ mov(r1, r1);
__ mov(r1, r1);
__ mov(r1, r1);
```
Here's a sample debugging session:
We hit the first stop.
```
Simulator hit My stop.
0xb53559e8 e1a00000 mov r0, r0
```
We can see the following stop using disasm. The address of the message string is inlined in the code after the svc stop instruction.
```
sim> disasm
0xb53559e8 e1a00000 mov r0, r0
0xb53559ec e1a00000 mov r0, r0
0xb53559f0 e1a00000 mov r0, r0
0xb53559f4 e1a00000 mov r0, r0
0xb53559f8 e1a00000 mov r0, r0
0xb53559fc ef800001 stop 1 - 0x1
0xb5355a00 08338a97 stop message: My second stop
0xb5355a04 e1a00000 mov r1, r1
0xb5355a08 e1a00000 mov r1, r1
0xb5355a0c e1a00000 mov r1, r1
```
Information can be printed for all (watched) stops which were hit at least once.
```
sim> stop info all
Stop information:
stop 123 - 0x7b: Enabled, counter = 1, My stop.
sim> cont
Simulator hit My second stop
0xb5355a04 e1a00000 mov r1, r1
sim> stop info all
Stop information:
stop 1 - 0x1: Enabled, counter = 1, My second stop
stop 123 - 0x7b: Enabled, counter = 1, My stop.
```
Stops can be disabled or enabled. (Only available for watched stops.)
```
sim> stop disable 1
sim> cont
Simulator hit My stop.
0xb5356808 e1a00000 mov r0, r0
sim> cont
Simulator hit My stop.
0xb5356c28 e1a00000 mov r0, r0
sim> stop info all
Stop information:
stop 1 - 0x1: Disabled, counter = 2, My second stop
stop 123 - 0x7b: Enabled, counter = 3, My stop.
sim> stop enable 1
sim> cont
Simulator hit My second stop
0xb5356c44 e1a00000 mov r1, r1
sim> stop disable all
sim> con
In function test.
```

40
docs/becoming_v8_committer.md
View File

@ -1,40 +0,0 @@
# Becoming a V8 committer
## What is a committer?
Technically, a committer is someone who has write access to the V8 Git repository. A committer can submit his or her own patches or patches from others.
This privilege is granted with some expectation of responsibility: committers are people who care about the V8 project and want to help meet its goals. A committer is not just someone who can make changes, but someone who has demonstrated his or her ability to collaborate with the team, get the most knowledgeable people to review code, contribute high-quality code, and follow through to fix issues (in code or tests).
A committer is a contributor to the V8 projects' success and a citizen helping the projects succeed. See V8CommittersResponsibility.
## How do I become a committer?
In a nutshell, contribute 20 non-trivial patches and get at least three different people to review them (you'll need three people to support you). Then ask someone to nominate you. You're demonstrating your:
* commitment to the project (20 good patches requires a lot of your valuable time),
* ability to collaborate with the team,
* understanding of how the team works (policies, processes for testing and code review, etc),
* understanding of the projects' code base and coding style, and
* ability to write good code (last but certainly not least)
A current committer nominates you by sending email to v8-committers@googlegroups.com containing:
* your first and last name
* your Google Code email address
* an explanation of why you should be a committer,
* embedded list of links to revisions (about top 10) containing your patches
Two other committers need to second your nomination. If no one objects in 5 working days (U.S.), you're a committer. If anyone objects or wants more information, the committers discuss and usually come to a consensus (within the 5 working days). If issues cannot be resolved, there's a vote among current committers.
Once you get approval from the existing committers, we'll send you instructions for write access to SVN or Git. You'll also be added to v8-committers@googlegroups.com.
In the worst case, this can drag out for two weeks. Keep writing patches! Even in the rare cases where a nomination fails, the objection is usually something easy to address like "more patches" or "not enough people are familiar with this person's work."
## Maintaining committer status
You don't really need to do much to maintain committer status: just keep being awesome and helping the V8 project!
In the unhappy event that a committer continues to disregard good citizenship (or actively disrupts the project), we may need to revoke that person's status. The process is the same as for nominating a new committer: someone suggests the revocation with a good reason, two people second the motion, and a vote may be called if consensus cannot be reached. I hope that's simple enough, and that we never have to test it in practice.
(Source: inspired by http://dev.chromium.org/getting-involved/become-a-committer )

260
docs/building_with_gyp.md
View File

@ -1,260 +0,0 @@
**Build issues? File a bug at code.google.com/p/v8/issues or ask for help on v8-users@googlegroups.com.**
# Building V8
V8 is built with the help of [GYP](http://code.google.com/p/gyp/). GYP is a meta build system of sorts, as it generates build files for a number of other build systems. How you build therefore depends on what "back-end" build system and compiler you're using.
The instructions below assume that you already have a [checkout of V8](using_git.md) but haven't yet installed the build dependencies.
If you intend to develop on V8, i.e., send patches and work with changelists, you will need to install the dependencies as described [here](using_git.md).
## Prerequisite: Installing GYP
First, you need GYP itself. GYP is fetched together with the other dependencies by running:
```
gclient sync
```
## Building
### GCC + make
Requires GNU make 3.81 or later. Should work with any GCC >= 4.8 or any recent clang (3.5 highly recommended).
#### Build instructions
The top-level Makefile defines a number of targets for each target architecture (`ia32`, `x64`, `arm`, `arm64`) and mode (`debug`, `optdebug`, or `release`). So your basic command for building is:
```
make ia32.release
```
or analogously for the other architectures and modes. You can build both debug and release binaries with just one command:
```
make ia32
```
To automatically build in release mode for the host architecture:
```
make native
```
You can also can build all architectures in a given mode at once:
```
make release
```
Or everything:
```
make
```
#### Optional parameters
* `-j` specifies the number of parallel build processes. Set it (roughly) to the number of CPU cores your machine has. The GYP/make based V8 build also supports distcc, so you can compile with `-j100` or so, provided you have enough machines around.
* `OUTDIR=foo` specifies where the compiled binaries go. It defaults to `./out/`. In this directory, a subdirectory will be created for each architecture and mode. You will find the d8 shell's binary in `foo/ia32.release/d8`, for example.
* `library=shared` or `component=shared_library` (the two are completely equivalent) builds V8 as a shared library (`libv8.so`).
* `soname_version=1.2.3` is only relevant for shared library builds and configures the SONAME of the library. Both the SONAME and the filename of the library will be `libv8.so.1.2.3` if you specify this. Due to a peculiarity in GYP, if you specify a custom SONAME, the library's path will no longer be encoded in the binaries, so you'll have to run d8 as follows:
```
LD_LIBRARY_PATH=out/ia32.release/lib.target out/ia32.release/d8
```
* `console=readline` enables readline support for the d8 shell. You need readline development headers for this (`libreadline-dev` on Ubuntu).
* `disassembler=on` enables the disassembler for release mode binaries (it's always enabled for debug binaries). This is useful if you want to inspect generated machine code.
* `snapshot=off` disables building with a heap snapshot. Compiling will be a little faster, but V8’s start up will be slightly slower.
* `gdbjit=on` enables GDB JIT support.
* `liveobjectlist=on` enables the Live Object List feature.
* `vfp3=off` is only relevant for ARM builds with snapshot and disables the use of VFP3 instructions in the snapshot.
* `debuggersupport=off` disables the javascript debugger.
* `werror=no` omits the -Werror flag. This is especially useful for not officially supported C++ compilers (e.g. newer versions of the GCC) so that compile warnings are ignored.
* `strictaliasing=off` passes the -fno-strict-aliasing flag to GCC. This may help to work around build failures on officially unsupported platforms and/or GCC versions.
* `regexp=interpreted` chooses the interpreted mode of the irregexp regular expression engine instead of the native code mode.
* `hardfp=on` creates "hardfp" binaries on ARM.
### Ninja
To build d8:
```
export GYP_GENERATORS=ninja
build/gyp_v8
ninja -C out/Debug d8
```
Specify `out/Release` for a release build. I recommend setting up an alias so that you don't need to type out that build directory path.
If you want to build all targets, use `ninja -C out/Debug all`. It's faster to build only the target you're working on, like `d8` or `unittests`.
Note: You need to set `v8_target_arch` if you want a non-native build, i.e. either
```
export GYP_DEFINES="v8_target_arch=arm"
build/gyp_v8 ...
```
or
```
build/gyp_v8 -Dv8_target_arch=arm ...
```
#### Using goma (Googlers only)
To use goma you need to set the `use_goma` gyp define, either by passing it to `gyp_v8`, i.e.
```
build/gyp_v8 -Duse_goma=1
```
or by setting the environment variable `$GYP_DEFINES` appropriately:
```
export GYP_DEFINES="use_goma=1"
```
Note: You may need to also set `gomadir` to point to the directory where you installed goma, if it's not in the default location.
If you are using goma, you'll also want to bump the job limit, i.e.
```
ninja -j 100 -C out/Debug d8
```
### Cross-compiling
Similar to building with Clang, you can also use a cross-compiler. Just export your toolchain (`CXX`/`LINK` environment variables should be enough) and compile. For example:
```
export CXX=/path/to/cross-compile-g++
export LINK=/path/to/cross-compile-g++
make arm.release
```
### Xcode
From the root of your V8 checkout, run either of:
```
build/gyp_v8 -Dtarget_arch=ia32
build/gyp_v8 -Dtarget_arch=x64
```
This will generate Xcode project files in `build/` that you can then either open with Xcode or compile directly from the command line:
```
xcodebuild -project build/all.xcodeproj -configuration Release
xcodebuild -project build/all.xcodeproj
```
Note: If you have configured your `GYP_GENERATORS` environment variable, either unset it, or set it to `xcode` for this to work.
#### Custom build settings
You can export the `GYP_DEFINES` environment variable in your shell to configure custom build options. The syntax is `GYP_DEFINES="-Dvariable1=value1 -Dvariable2=value2"` and so on for as many variables as you wish. Possibly interesting options include:
* `-Dcomponent=shared_library` (see `library=shared` in the [GCC + make](#Optional_parameters.md) section above)
* `-Dconsole=readline` (see `console=readline`)
* `-Dv8_enable_disassembler=1` (see `disassembler=on`)
* `-Dv8_use_snapshot='false'` (see `snapshot=off`)
* `-Dv8_enable_gdbjit=1` (see `gdbjit=on`)
* `-Dv8_use_liveobjectlist=true` (see `liveobjectlist=on`)
### Visual Studio
You need Visual Studio 2013, older versions might still work at the moment, but this will probably change soon because we intend to use C++11 features.
#### Prerequisites
After you created [checkout of V8](using_git.md), all dependencies will be already installed.
If you are getting errors during build mentioning that 'python' could not be found, add the 'python.exe' to PATH.
If you have Visual Studio 2013 and 2015 installed side-by-side and set the environment variable GYP\_MSVS\_VERSION to '2013'. In that case the right project files are going to be created.
#### Building
* If you use the command prompt:
1. Generate project files:
```
python build\gyp_v8
```
> > > Specify the path to `python.exe` if you don't have it in your PATH.
> > > Append `-Dtarget_arch=x64` if you want to build 64bit binaries. If you switch between ia32 and x64 targets, you may have to manually delete the generated .vcproj/.sln files before regenerating them.
> > > Example:
```
third_party/python_26/python.exe build\gyp_v8 -Dtarget_arch=x64
```
1. Build:
> > > Either open `build\All.sln` in Visual Studio, or compile on the command line as follows (adapt the path as necessary, or simply put `devenv.com` in your PATH):
```
"c:\Program Files (x86)\Microsoft Visual Studio 9.0\Common7\IDE\devenv.com" /build Release build\All.sln
```
> > > Replace `Release` with `Debug` to build in Debug mode.
> > > The built binaries will be in build\Release\ or build\Debug\.
* If you use cygwin, the workflow is the same, but the syntax is slightly different:
1. Generate project files:
```
build/gyp_v8
```
> > > This will spit out a bunch of warnings about missing input files, but it seems to be OK to ignore them. (If you have time to figure this out, we'd happily accept a patch that makes the warnings go away!)
1. Build:
```
/cygdrive/c/Program\ Files\ (x86)/Microsoft\ Visual\ Studio\ 9.0/Common7/IDE/devenv.com /build Release build/all.sln
```
#### Custom build settings
See the "custom build settings" section for [Xcode](#Xcode) above.
#### Running tests
You can abuse the test driver's --buildbot flag to make it find the executables where MSVC puts them:
```
python tools/run-tests.py --buildbot --outdir build --arch ia32 --mode Release
```
### MinGW
Building on MinGW is not officially supported, but it is possible. You even have two options:
#### Option 1: With Cygwin Installed
Requirements:
* MinGW
* Cygwin, including Python
* Python from www.python.org _(yes, you need two Python installations!)_
Building:
1. Open a MinGW shell
1. `export PATH=$PATH:/c/cygwin/bin` _(or wherever you installed Cygwin)_
1. `make ia32.release -j8`
Running tests:
1. Open a MinGW shell
1. `export PATH=/c/Python27:$PATH` _(or wherever you installed Python)_
1. `make ia32.release.check -j8`
#### Option 2: Without Cygwin, just MinGW
Requirements:
* MinGW
* Python from www.python.org
Building and testing:
1. Open a MinGW shell
1. `tools/mingw-generate-makefiles.sh` _(re-run this any time a `*`.gyp`*` file changed, such as after updating your checkout)_
1. `make ia32.release` _(unfortunately -jX doesn't seem to work here)_
1. `make ia32.release.check -j8`
# Final Note
<font color='darkred'><b>If you have problems or questions, please file bugs at code.google.com/p/v8/issues or send mail to v8-users@googlegroups.com. Comments on this page are likely to go unnoticed and unanswered.</b></font>

32
docs/contributing.md
View File

@ -1,32 +0,0 @@
Here you will find information that you'll need to be able to contribute to V8. Be sure to read the whole thing before sending us a contribution, including the small print at the end.
## Before you contribute
Before you start working on a larger contribution V8 you should get in touch with us first through the V8 [contributor mailing list](http://groups.google.com/group/v8-dev) so we can help out and possibly guide you; coordinating up front makes it much easier to avoid frustration later on.
## Getting the code
See [UsingGit](using_git.md).
## Submitting code
The source code of V8 follows the [Google C++ Style Guide](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml) so you should familiarize yourself with those guidelines. Before submitting code you must pass all our [tests](http://code.google.com/p/v8-wiki/wiki/Testing), and have to successfully run the presubmit checks:
> `tools/presubmit.py`
The presubmit script uses a linter from Google, `cpplint.py`. External contributors can get this from [here](http://google-styleguide.googlecode.com/svn/trunk/cpplint/cpplint.py) and place it in their path.
All submissions, including submissions by project members, require review. We use the same code-review tools and process as the chromium project. In order to submit a patch, you need to get the [depot\_tools](http://dev.chromium.org/developers/how-tos/install-depot-tools) and follow these instructions on [requesting a review](http://dev.chromium.org/developers/contributing-code) (using your V8 workspace instead of a chromium workspace).
### Look out for breakage or regressions
Before submitting your code please check the [buildbot console](http://build.chromium.org/p/client.v8/console) to see that the columns are mostly green before checking in your changes. Otherwise you will not know if your changes break the build or not. When your change is committed watch the [buildbot console](http://build.chromium.org/p/client.v8/console) until the bots turn green after your change.
## The small print
Before we can use your code you have to sign the [Google Individual Contributor License Agreement](http://code.google.com/legal/individual-cla-v1.0.html), which you can do online. This is mainly because you own the copyright to your changes, even after your contribution becomes part of our codebase, so we need your permission to use and distribute your code. We also need to be sure of various other things, for instance that you'll tell us if you know that your code infringes on other people's patents. You don't have to do this until after you've submitted your code for review and a member has approved it, but you will have to do it before we can put your code into our codebase.
Contributions made by corporations are covered by a different agreement than the one above, the [Software Grant and Corporate Contributor License Agreement](http://code.google.com/legal/corporate-cla-v1.0.html).
Sign them online [here](https://cla.developers.google.com/)

151
docs/cross_compiling_for_arm.md
View File

@ -1,151 +0,0 @@
<font color='darkred'><b><h2>Building V8 with SCons is no longer supported. See <a href='https://code.google.com/p/v8-wiki/wiki/BuildingWithGYP'>BuildingWithGYP</a>.</h2></b></font>
---
# Using Sourcery G++ Lite
The Sourcery G++ Lite cross compiler suite is a free version of Sourcery G++ from [CodeSourcery](http://www.codesourcery.com). There is a page for the [GNU Toolchain for ARM Processors](http://www.codesourcery.com/sgpp/lite/arm). Determine the version you need for your host/target combination.
The following instructions uses [2009q1-203 for ARM GNU/Linux](http://www.codesourcery.com/sgpp/lite/arm/portal/release858), and if using a different version please change the URLs and `TOOL_PREFIX` below accordingly.
## Installing on host and target
The simplest way of setting this up is to install the full Sourcery G++ Lite package on both the host and target at the same location. This will ensure that all the libraries required are available on both sides. If you want to use the default libraries on the host there is no need the install anything on the target.
The following script will install in `/opt/codesourcery`:
```
#!/bin/sh
sudo mkdir /opt/codesourcery
cd /opt/codesourcery
sudo chown $USERNAME .
chmod g+ws .
umask 2
wget http://www.codesourcery.com/sgpp/lite/arm/portal/package4571/public/arm-none-linux-gnueabi/arm-2009q1-203-arm-none-linux-gnueabi-i686-pc-linux-gnu.tar.bz2
tar -xvf arm-2009q1-203-arm-none-linux-gnueabi-i686-pc-linux-gnu.tar.bz2
```
## Building using scons without snapshot
The simplest way to build is without snapshot, as that does no involve using the simulator to generate the snapshot. The following script will build the sample shell without snapshot for ARM v7.
```
#!/bin/sh
export TOOL_PREFIX=/opt/codesourcery/arm-2009q1/bin/arm-none-linux-gnueabi
export CXX=$TOOL_PREFIX-g++
export AR=$TOOL_PREFIX-ar
export RANLIB=$TOOL_PREFIX-ranlib
export CC=$TOOL_PREFIX-gcc
export LD=$TOOL_PREFIX-ld
export CCFLAGS="-march=armv7-a -mtune=cortex-a8 -mfpu=vfp"
export ARM_TARGET_LIB=/opt/codesourcery/arm-2009q1/arm-none-linux-gnueabi/libc
scons wordsize=32 snapshot=off arch=arm sample=shell
```
If the processor is not Cortex A8 or does not have VFP enabled the `-mtune=cortex-a8` and `-mfpu=vfp` part of `CCFLAGS` needs to be changed accordingly. By default the V8 SCons build adds `-mfloat-abi=softfp`.
If using the default libraries on the target just leave out the setting of `ARM_TARGET_LIB` and if the target libraies are in a different location ARM\_TARGET\_LIB` needs to be adjusted accordingly.
The default for Sourcery G++ Lite is ARM v5te with software floating point emulation, so if testing building for ARM v5te the setting of `CCFLAGS` and `ARM_TARGET_LIB` should be changed to:
```
CCFLAGS=""
ARM_TARGET_LIB=/opt/codesourcery/arm-2009q1/arm-none-linux-gnueabi/libc
scons armeabi=soft ...
```
Relying on defaults in the tool chain might lead to surprises, so for ARM v5te with software floating point emulation the following is more explicit:
```
CCFLAGS="-march=armv5te"
ARM_TARGET_LIB=/opt/codesourcery/arm-2009q1/arm-none-linux-gnueabi/libc
scons armeabi=soft ...
```
If the target has an VFP unit use the following:
```
CCFLAGS="-mfpu=vfpv3"
ARM_TARGET_LIB=/opt/codesourcery/arm-2009q1/arm-none-linux-gnueabi/libc
```
To allow G++ to use Thumb2 instructions and the VFP unit when compiling the C/C++ code use:
```
CCFLAGS="-mthumb -mfpu=vfpv3"
ARM_TARGET_LIB=/opt/codesourcery/arm-2009q1/arm-none-linux-gnueabi/libc/thumb2
```
_Note:_ V8 will not use Thumb2 instructions in its generated code it always uses the full ARM instruction set.
For other ARM versions please check the Sourcery G++ Lite documentation.
As mentioned above the default for Sourcery G++ Lite used here is ARM v5te with software floating point emulation. However beware that this default might change between versions and that there is no unique defaults for ARM tool chains in general, so always passing `-march` and possibly `-mfpu` is recommended. Passing `-mfloat-abi` is not required as this is controlled by the SCons option `armeabi`.
## Building using scons with snapshot
When building with snapshot the simulator is used to build the snapshot on the host and then building for the target with that snapshot. The following script will accomplish that (using both Thumb2 and VFP instructions):
```
#!/bin/sh
V8DIR=..
cd host
scons -Y$V8DIR simulator=arm snapshot=on
mv obj/release/snapshot.cc $V8DIR/src/snapshot.cc
cd ..
export TOOL_PREFIX=/opt/codesourcery/arm-2010.09-103/bin/arm-none-linux-gnueabi
export CXX=$TOOL_PREFIX-g++
export AR=$TOOL_PREFIX-ar
export RANLIB=$TOOL_PREFIX-ranlib
export CC=$TOOL_PREFIX-gcc
export LD=$TOOL_PREFIX-ld
export CCFLAGS="-mthumb -march=armv7-a -mfpu=vfpv3"
export ARM_TARGET_LIB=/opt/codesourcery/arm-2010.09-103/arm-none-linux-gnueabi/libc/thumb2
cd target
scons -Y$V8DIR wordsize=32 snapshot=nobuild arch=armsample=shell
rm $V8DIR/src/snapshot.cc
cd ..
```
This script required the two subdirectories `host` and `target`. V8 is first build for the host with the ARM simulator which supports running ARM code on the host. This is used to build a snapshot file which is then used for the actual cross compilation of V8.
## Building for target which supports unaligned access
The default when building V8 for an ARM target (either cross compiling or compiling on an ARM machine) is to disable unaligned memory access. However in some situations (most noticeably handling of regular expressions) performance will be better if unaligned memory access is used on processors which supports it. To enable unaligned memory access set `unalignedaccesses` to `on` when building:
```
scons unalignedaccesses=on ...
```
When running in the simulator the default is to enable unaligned memory access, so to test in the simulator with unaligned memory access disabled set `unalignedaccesses` to `off` when building:
```
scons unalignedaccesses=off simulator=arm ...
```
## Using V8 with hardfp calling convention
By default V8 uses the softfp calling convention when calling C functions from generated code. However it is possible to use hardfp as well. To enable this set `armeabi` to `hardfp` when building:
```
scons armeabi=hardfp ...
```
Passing `armeabi=hardfp` to SCons will automatically set the compiler flag `-mfloat-abi=hardfp`. If using snapshots remember to pass `armeabi=hardfp` when building V8 on the host for generating the snapshot as well.

101
docs/d8_on_android.md
View File

@ -1,101 +0,0 @@
# Prerequisites
* a Linux/Mac workstation
* v8 r12178 (on Google Code) or later
* an Android emulator or device with matching USB cable
* make sure [building with GYP](http://code.google.com/p/v8-wiki/wiki/BuildingWithGYP) works
# Get the code
* Use the instructions from https://code.google.com/p/v8-wiki/wiki/UsingGit to get the code
* Once you need to add the android dependencies:
```
v8$ echo "target_os = ['android']" >> ../.gclient && gclient sync --nohooks
```
* The sync will take a while the first time as it downloads the Android NDK to v8/third\_party
* If you want to use a different NDK, you need to set the gyp variable android\_ndk\_root
# Get the Android SDK
* tested version: `r15`
* download the SDK from http://developer.android.com/sdk/index.html
* extract it
* install the "Platform tools" using the SDK manager that you can start by running `tools/android`
* now you have a `platform_tools/adb` binary which will be used later; put it in your `PATH` or remember where it is
# Set up your device
* Enable USB debugging (Gingerbread: Settings > Applications > Development > USB debugging; Ice Cream Sandwich: Settings > Developer Options > USB debugging)
* connect your device to your workstation
* make sure `adb devices` shows it; you may have to edit `udev` rules to give yourself proper permissions
* run `adb shell` to get an ssh-like shell on the device. In that shell, do:
```
cd /data/local/tmp
mkdir v8
cd v8
```
# Push stuff onto the device
* make sure your device is connected
* from your workstation's shell:
```
adb push /file/you/want/to/push /data/local/tmp/v8/
```
# Compile V8 for Android
Currently two architectures (`android_arm` and `android_ia32`) are supported, each in `debug` or `release` mode. The following steps work equally well for both ARM and ia32, on either the emulator or real devices.
* compile:
```
make android_arm.release -j16
```
* push the resulting binary to the device:
```
adb push out/android_arm.release/d8 /data/local/tmp/v8/d8
```
* the most comfortable way to run it is from your workstation's shell as a one-off command (rather than starting an interactive shell session on the device), that way you can use pipes or whatever to process the output as necessary:
```
adb shell /data/local/tmp/v8/d8 <parameters>
```
* warning: when you cancel such an "adb shell whatever" command using Ctrl+C, the process on the phone will sometimes keep running.
* Alternatively, use the `.check` suffix to automatically push test binaries and test cases onto the device and run them.
```
make android_arm.release.check
```
# Profile
* compile a binary, push it to the device, keep a copy of it on the host
```
make android_arm.release -j16
adb push out/android_arm.release/d8 /data/local/tmp/v8/d8-version.under.test
cp out/android_arm.release/d8 ./d8-version.under.test
```
* get a profiling log and copy it to the host:
```
adb shell /data/local/tmp/v8/d8-version.under.test benchmark.js --prof
adb pull /data/local/tmp/v8/v8.log ./
```
* open `v8.log` in your favorite editor and edit the first line to match the full path of the `d8-version.under.test` binary on your workstation (instead of the `/data/local/tmp/v8/` path it had on the device)
* run the tick processor with the host's `d8` and an appropriate `nm` binary:
```
cp out/ia32.release/d8 ./d8 # only required once
tools/linux-tick-processor --nm=$ANDROID_NDK_ROOT/toolchain/bin/arm-linux-androideabi-nm
```
# Compile SpiderMonkey for Lollipop
```
cd firefox/js/src
autoconf2.13
./configure \
--target=arm-linux-androideabi \
--with-android-ndk=$ANDROID_NDK_ROOT \
--with-android-version=21 \
--without-intl-api \
--disable-tests \
--enable-android-libstdcxx \
--enable-pie
make
adb push -p js/src/shell/js /data/local/tmp/js
```

934
docs/debugger_protocol.md
View File

@ -1,934 +0,0 @@
# Introduction
V8 has support for debugging the JavaScript code running in it. There are two API's for this a function based API using JavaScript objects and a message based API using a JSON based protocol. The function based API can be used by an in-process debugger agent, whereas the message based API can be used out of process as well.
**> The message based API is no longer maintained. Please ask in v8-users@googlegroups.com if you want to attach a debugger to the run-time.**
The debugger protocol is based on [JSON](http://www.json.org/)). Each protocol packet is defined in terms of JSON and is transmitted as a string value. All packets have two basic elements `seq` and `type`.
```
{ "seq" : <number>,
"type" : <type>,
...
}
```
The element `seq` holds the sequence number of the packet. And element type is the type of the packet. The type is a string value with one of the following values `"request"`, `"response"` or `"event"`.
A `"request"` packet has the following structure:
```
{ "seq" : <number>,
"type" : "request",
"command" : <command>
"arguments" : ...
}
```
A `"response"` packet has the following structure. If `success` is true `body` will contain the response data. If `success` is false `message` will contain an error message.
```
{ "seq" : <number>,
"type" : "response",
"request_seq" : <number>,
"command" : <command>
"body" : ...
"running" : <is the VM running after sending this response>
"success" : <boolean indicating success>
"message" : <if command failed this property contains an error message>
}
```
An `"event"` packet has the following structure:
```
{ "seq" : <number>,
"type" : "event",
"event" : <event name>
body : ...
}
```
# Request/response pairs
## Request `continue`
The request `continue` is a request from the debugger to start the VM running again. As part of the `continue` request the debugger can specify if it wants the VM to perform a single step action.
```
{ "seq" : <number>,
"type" : "request",
"command" : "continue",
"arguments" : { "stepaction" : <"in", "next" or "out">,
"stepcount" : <number of steps (default 1)>
}
}
```
In the response the property `running` will always be true as the VM will be running after executing the `continue` command. If a single step action is requested the VM will respond with a `break` event after running the step.
```
{ "seq" : <number>,
"type" : "response",
"request_seq" : <number>,
"command" : "continue",
"running" : true
"success" : true
}
```
Here are a couple of examples.
```
{"seq":117,"type":"request","command":"continue"}
{"seq":118,"type":"request","command":"continue","arguments":{"stepaction":"out"}}
{"seq":119,"type":"request","command":"continue","arguments":{"stepaction":"next","stepcount":5}}
```
## Request `evaluate`
The request `evaluate` is used to evaluate an expression. The body of the result is as described in response object serialization below.
```
{ "seq" : <number>,
"type" : "request",
"command" : "evaluate",
"arguments" : { "expression" : <expression to evaluate>,
"frame" : <number>,
"global" : <boolean>,
"disable_break" : <boolean>,
"additional_context" : [
{ "name" : <name1>, "handle" : <handle1> },
{ "name" : <name2>, "handle" : <handle2> },
...
]
}
}
```
Optional argument `additional_context` specifies handles that will be visible from the expression under corresponding names (see example below).
Response:
```
{ "seq" : <number>,
"type" : "response",
"request_seq" : <number>,
"command" : "evaluate",
"body" : ...
"running" : <is the VM running after sending this response>
"success" : true
}
```
Here are a couple of examples.
```
{"seq":117,"type":"request","command":"evaluate","arguments":{"expression":"1+2"}}
{"seq":118,"type":"request","command":"evaluate","arguments":{"expression":"a()","frame":3,"disable_break":false}}
{"seq":119,"type":"request","command":"evaluate","arguments":{"expression":"[o.a,o.b,o.c]","global":true,"disable_break":true}}
{"seq":120,"type":"request","command":"evaluate","arguments":{"expression":"obj.toString()", "additional_context": [{ "name":"obj","handle":25 }] }}
```
## Request `lookup`
The request `lookup` is used to lookup objects based on their handle. The individual array elements of the body of the result is as described in response object serialization below.
```
{ "seq" : <number>,
"type" : "request",
"command" : "lookup",
"arguments" : { "handles" : <array of handles>,
"includeSource" : <boolean indicating whether the source will be included when script objects are returned>,
}
}
```
Response:
```
{ "seq" : <number>,
"type" : "response",
"request_seq" : <number>,
"command" : "lookup",
"body" : <array of serialized objects indexed using their handle>
"running" : <is the VM running after sending this response>
"success" : true
}
```
Here are a couple of examples.
```
{"seq":117,"type":"request","command":"lookup","arguments":{"handles":"[1]"}}
{"seq":118,"type":"request","command":"lookup","arguments":{"handles":"[7,12]"}}
```
## Request `backtrace`
The request `backtrace` returns a backtrace (or stacktrace) from the current execution state. When issuing a request a range of frames can be supplied. The top frame is frame number 0. If no frame range is supplied data for 10 frames will be returned.
```
{ "seq" : <number>,
"type" : "request",
"command" : "backtrace",
"arguments" : { "fromFrame" : <number>
"toFrame" : <number>
"bottom" : <boolean, set to true if the bottom of the stack is requested>
}
}
```
The response contains the frame data together with the actual frames returned and the toalt frame count.
```
{ "seq" : <number>,
"type" : "response",
"request_seq" : <number>,
"command" : "backtrace",
"body" : { "fromFrame" : <number>
"toFrame" : <number>
"totalFrames" : <number>
"frames" : <array of frames - see frame request for details>
}
"running" : <is the VM running after sending this response>
"success" : true
}
```
If there are no stack frames the result body only contains `totalFrames` with a value of `0`. When an exception event is generated due to compilation failures it is possible that there are no stack frames.
Here are a couple of examples.
```
{"seq":117,"type":"request","command":"backtrace"}
{"seq":118,"type":"request","command":"backtrace","arguments":{"toFrame":2}}
{"seq":119,"type":"request","command":"backtrace","arguments":{"fromFrame":0,"toFrame":9}}
```
## Request `frame`
The request frame selects a new selected frame and returns information for that. If no frame number is specified the selected frame is returned.
```
{ "seq" : <number>,
"type" : "request",
"command" : "frame",
"arguments" : { "number" : <frame number>
}
}
```
Response:
```
{ "seq" : <number>,
"type" : "response",
"request_seq" : <number>,
"command" : "frame",
"body" : { "index" : <frame number>,
"receiver" : <frame receiver>,
"func" : <function invoked>,
"script" : <script for the function>,
"constructCall" : <boolean indicating whether the function was called as constructor>,
"debuggerFrame" : <boolean indicating whether this is an internal debugger frame>,
"arguments" : [ { name: <name of the argument - missing of anonymous argument>,
value: <value of the argument>
},
... <the array contains all the arguments>
],
"locals" : [ { name: <name of the local variable>,
value: <value of the local variable>
},
... <the array contains all the locals>
],
"position" : <source position>,
"line" : <source line>,
"column" : <source column within the line>,
"sourceLineText" : <text for current source line>,
"scopes" : [ <array of scopes, see scope request below for format> ],
}
"running" : <is the VM running after sending this response>
"success" : true
}
```
Here are a couple of examples.
```
{"seq":117,"type":"request","command":"frame"}
{"seq":118,"type":"request","command":"frame","arguments":{"number":1}}
```
## Request `scope`
The request scope returns information on a givne scope for a givne frame. If no frame number is specified the selected frame is used.
```
{ "seq" : <number>,
"type" : "request",
"command" : "scope",
"arguments" : { "number" : <scope number>
"frameNumber" : <frame number, optional uses selected frame if missing>
}
}
```
Response:
```
{ "seq" : <number>,
"type" : "response",
"request_seq" : <number>,
"command" : "scope",
"body" : { "index" : <index of this scope in the scope chain. Index 0 is the top scope
and the global scope will always have the highest index for a
frame>,
"frameIndex" : <index of the frame>,
"type" : <type of the scope:
0: Global
1: Local
2: With
3: Closure
4: Catch >,
"object" : <the scope object defining the content of the scope.
For local and closure scopes this is transient objects,
which has a negative handle value>
}
"running" : <is the VM running after sending this response>
"success" : true
}
```
Here are a couple of examples.
```
{"seq":117,"type":"request","command":"scope"}
{"seq":118,"type":"request","command":"scope","arguments":{"frameNumber":1,"number":1}}
```
## Request `scopes`
The request scopes returns all the scopes for a given frame. If no frame number is specified the selected frame is returned.
```
{ "seq" : <number>,
"type" : "request",
"command" : "scopes",
"arguments" : { "frameNumber" : <frame number, optional uses selected frame if missing>
}
}
```
Response:
```
{ "seq" : <number>,
"type" : "response",
"request_seq" : <number>,
"command" : "scopes",
"body" : { "fromScope" : <number of first scope in response>,
"toScope" : <number of last scope in response>,
"totalScopes" : <total number of scopes for this frame>,
"scopes" : [ <array of scopes, see scope request above for format> ],
}
"running" : <is the VM running after sending this response>
"success" : true
}
```
Here are a couple of examples.
```
{"seq":117,"type":"request","command":"scopes"}
{"seq":118,"type":"request","command":"scopes","arguments":{"frameNumber":1}}
```
## Request `scripts`
The request `scripts` retrieves active scripts from the VM. An active script is source code from which there is still live objects in the VM. This request will always force a full garbage collection in the VM.
```
{ "seq" : <number>,
"type" : "request",
"command" : "scripts",
"arguments" : { "types" : <types of scripts to retrieve
set bit 0 for native scripts
set bit 1 for extension scripts
set bit 2 for normal scripts
(default is 4 for normal scripts)>
"ids" : <array of id's of scripts to return. If this is not specified all scripts are requrned>
"includeSource" : <boolean indicating whether the source code should be included for the scripts returned>
"filter" : <string or number: filter string or script id.
If a number is specified, then only the script with the same number as its script id will be retrieved.
If a string is specified, then only scripts whose names contain the filter string will be retrieved.>
}
}
```
The request contains an array of the scripts in the VM. This information includes the relative location of the script within the containing resource.
```
{ "seq" : <number>,
"type" : "response",
"request_seq" : <number>,
"command" : "scripts",
"body" : [ { "name" : <name of the script>,
"id" : <id of the script>
"lineOffset" : <line offset within the containing resource>
"columnOffset" : <column offset within the containing resource>
"lineCount" : <number of lines in the script>
"data" : <optional data object added through the API>
"source" : <source of the script if includeSource was specified in the request>
"sourceStart" : <first 80 characters of the script if includeSource was not specified in the request>
"sourceLength" : <total length of the script in characters>
"scriptType" : <script type (see request for values)>
"compilationType" : < How was this script compiled:
0 if script was compiled through the API
1 if script was compiled through eval
>
"evalFromScript" : <if "compilationType" is 1 this is the script from where eval was called>
"evalFromLocation" : { line : < if "compilationType" is 1 this is the line in the script from where eval was called>
column : < if "compilationType" is 1 this is the column in the script from where eval was called>
]
"running" : <is the VM running after sending this response>
"success" : true
}
```
Here are a couple of examples.
```
{"seq":117,"type":"request","command":"scripts"}
{"seq":118,"type":"request","command":"scripts","arguments":{"types":7}}
```
## Request `source`
The request `source` retrieves source code for a frame. It returns a number of source lines running from the `fromLine` to but not including the `toLine`, that is the interval is open on the "to" end. For example, requesting source from line 2 to 4 returns two lines (2 and 3). Also note that the line numbers are 0 based: the first line is line 0.
```
{ "seq" : <number>,
"type" : "request",
"command" : "source",
"arguments" : { "frame" : <frame number (default selected frame)>
"fromLine" : <from line within the source default is line 0>
"toLine" : <to line within the source this line is not included in
the result default is the number of lines in the script>
}
}
```
Response:
```
{ "seq" : <number>,
"type" : "response",
"request_seq" : <number>,
"command" : "source",
"body" : { "source" : <the source code>
"fromLine" : <actual from line within the script>
"toLine" : <actual to line within the script this line is not included in the source>
"fromPosition" : <actual start position within the script>
"toPosition" : <actual end position within the script>
"totalLines" : <total lines in the script>
}
"running" : <is the VM running after sending this response>
"success" : true
}
```
Here are a couple of examples.
```
{"seq":117,"type":"request","command":"source","arguments":{"fromLine":10,"toLine":20}}
{"seq":118,"type":"request","command":"source","arguments":{"frame":2,"fromLine":10,"toLine":20}}
```
## Request `setbreakpoint`
The request `setbreakpoint` creates a new break point. This request can be used to set both function and script break points. A function break point sets a break point in an existing function whereas a script break point sets a break point in a named script. A script break point can be set even if the named script is not found.
```
{ "seq" : <number>,
"type" : "request",
"command" : "setbreakpoint",
"arguments" : { "type" : <"function" or "script" or "scriptId" or "scriptRegExp">
"target" : <function expression or script identification>
"line" : <line in script or function>
"column" : <character position within the line>
"enabled" : <initial enabled state. True or false, default is true>
"condition" : <string with break point condition>
"ignoreCount" : <number specifying the number of break point hits to ignore, default value is 0>
}
}
```
The result of the `setbreakpoint` request is a response with the number of the newly created break point. This break point number is used in the `changebreakpoint` and `clearbreakpoint` requests.
```
{ "seq" : <number>,
"type" : "response",
"request_seq" : <number>,
"command" : "setbreakpoint",
"body" : { "type" : <"function" or "script">
"breakpoint" : <break point number of the new break point>
}
"running" : <is the VM running after sending this response>
"success" : true
}
```
Here are a couple of examples.
```
{"seq":117,"type":"request","command":"setbreakpoint","arguments":{"type":"function,"target":"f"}}
{"seq":118,"type":"request","command":"setbreakpoint","arguments":{type:"script","target":"test.js","line":100}}
{"seq":119,"type":"request","command":"setbreakpoint","arguments":{"type":"function,"target":"f","condition":"i > 7"}}
```
## Request `changebreakpoint`
The request `changebreakpoint` changes the status of a break point.
```
{ "seq" : <number>,
"type" : "request",
"command" : "changebreakpoint",
"arguments" : { "breakpoint" : <number of the break point to clear>
"enabled" : <initial enabled state. True or false, default is true>
"condition" : <string with break point condition>
"ignoreCount" : <number specifying the number of break point hits }
}
```
## Request `clearbreakpoint`
The request `clearbreakpoint` clears a break point.
```
{ "seq" : <number>,
"type" : "request",
"command" : "clearbreakpoint",
"arguments" : { "breakpoint" : <number of the break point to clear>
}
}
```
Response:
```
{ "seq" : <number>,
"type" : "response",
"request_seq" : <number>,
"command" : "clearbreakpoint",
"body" : { "type" : <"function" or "script">
"breakpoint" : <number of the break point cleared>
}
"running" : <is the VM running after sending this response>
"success" : true
}
```
Here are a couple of examples.
```
{"seq":117,"type":"request","command":"clearbreakpoint","arguments":{"type":"function,"breakpoint":1}}
{"seq":118,"type":"request","command":"clearbreakpoint","arguments":{"type":"script","breakpoint":2}}
```
## Request `setexceptionbreak`
The request `setexceptionbreak` is a request to enable/disable breaks on all / uncaught exceptions. If the "enabled" argument is not specify, the debuggee will toggle the state of the specified break type.
```
{ "seq" : <number>,
"type" : "request",
"command" : "setexceptionbreak",
"arguments" : { "type" : <string: "all", or "uncaught">,
"enabled" : <optional bool: enables the break type if true>
}
}
```
In response, the break on exception property of the debuggee will be set accordingly, and the following response message will be dispatched to the debugger.
```
{ "seq" : <number>,
"type" : "response",
"request_seq" : <number>,
"command" : "setexceptionbreak",
“body” : { "type" : <string: "all" or "uncaught" corresponding to the request.>,
"enabled" : <bool: true if the break type is currently enabled as a result of the request>
}
"running" : true
"success" : true
}
```
Here are a few examples.
```
{"seq":117,"type":"request","command":"setexceptionbreak","arguments":{"type":"all"}}
{"seq":118,"type":"request","command":" setexceptionbreak","arguments":{"type":"all",”enabled”:false}}
{"seq":119,"type":"request","command":" setexceptionbreak","arguments":{"type":"uncaught","enabled":true}}
```
## Request `v8flags`
The request v8flags is a request to apply the specified v8 flags (analogous to how they are specified on the command line).
```
{ "seq" : <number>,
"type" : "request",
"command" : "v8flags",
"arguments" : { "flags" : <string: a sequence of v8 flags just like those used on the command line>
}
}
```
In response, the specified flags will be applied in the debuggee if they are legal flags. Their effects vary depending on the implementation of the flag.
```
{ "seq" : <number>,
"type" : "response",
"request_seq" : <number>,
"command" : "v8flags",
"running" : true
"success" : true
}
```
Here are a few examples.
```
{"seq":117,"type":"request","command":"v8flags","arguments":{"flags":"--trace_gc —always_compact"}}
{"seq":118,"type":"request","command":" v8flags","arguments":{"flags":"--notrace_gc"}}
```
## Request `version`
The request `version` reports version of the running V8.
```
{ "seq" : <number>,
"type" : "request",
"command" : "version",
}
```
Response:
```
{ "seq" : <number>,
"type" : "response",
"request_seq" : <number>,
"type" : "request",
"body" : { "V8Version": <string, version of V8>
}
"running" : <is the VM running after sending this response>
"success" : true
}
```
Here is an example.
```
{"seq":1,"type":"request","command":"version"}
{"seq":134,"request_seq":1,"type":"response","command":"version","success":true,"body":{"V8Version":"1.3.19 (candidate)"},"refs":[],"running":false}
```
## Request `disconnect`
The request `disconnect` is used to detach the remote debugger from the debuggee. This will trigger the debuggee to disable all active breakpoints and resumes execution if the debuggee was previously stopped at a break.
```
{ "seq" : <number>,
"type" : "request",
"command" : "disconnect",
}
```
The only response for the `disconnect` request is the response to a connect request if the debugger is still able to get a response before the debuggee successfully disconnects.
Here is an examples:
```
{"seq":117,"type":"request","command":"disconnect"}
```
## Request `gc`
The request `gc` is a request to run the garbage collector in the debuggee.
```
{ "seq" : <number>,
"type" : "request",
"command" : "gc",
"arguments" : { "type" : <string: "all">,
}
}
```
In response, the debuggee will run the specified GC type and send the following response message:
```
{ "seq" : <number>,
"type" : "response",
"request_seq" : <number>,
"command" : "gc",
“body” : { "before" : <int: total heap usage in bytes before the GC>,
"after" : <int: total heap usage in bytes after the GC>
}
"running" : true
"success" : true
}
```
Here is an example.
```
{"seq":117,"type":"request","command":"gc","arguments":{"type":"all"}}
```
## Request `listbreakpoints`
The request `listbreakpoints` is used to get information on breakpoints that may have been set by the debugger.
```
{ "seq" : <number>,
"type" : "request",
"command" : "listbreakpoints",
}
```
Response:
```
{ "seq" : <number>,
"type" : "response",
"request_seq" : <number>,
"command" : "listbreakpoints",
"body" : { "breakpoints": [ { "type" : <string: "scriptId" or "scriptName".>,
"script_id" : <int: script id. Only defined if type is scriptId.>,
"script_name" : <string: script name. Only defined if type is scriptName.>,
"number" : <int: breakpoint number. Starts from 1.>,
"line" : <int: line number of this breakpoint. Starts from 0.>,
"column" : <int: column number of this breakpoint. Starts from 0.>,
"groupId" : <int: group id of this breakpoint.>,
"hit_count" : <int: number of times this breakpoint has been hit. Starts from 0.>,
"active" : <bool: true if this breakpoint is enabled.>,
"ignoreCount" : <int: remaining number of times to ignore breakpoint. Starts from 0.>,
"actual_locations" : <actual locations of the breakpoint.>,
}
],
"breakOnExceptions" : <true if break on all exceptions is enabled>,
"breakOnUncaughtExceptions" : <true if break on uncaught exceptions is enabled>
}
"running" : <is the VM running after sending this response>
"success" : true
}
```
Here is an examples:
```
{"seq":117,"type":"request","command":"listbreakpoints"}
```
## Request `setvariablevalue`
This requests sets the value of a variable from the specified scope.
Request:
```
{ "seq" : <number>,
"type" : "request",
"command" : "setvariablevalue",
"arguments : { "name" : <string: variable name>,
"scope" : { "number" : <scope number>
"frameNumber" : <frame number, optional uses selected frame if missing>
}
}
}
```
Response:
```
{ "seq" : <number>,
"type" : "response",
"request_seq" : <number>,
"type" : "request",
"body" : { "newValue": <object: mirror object of the new value> }
"running" : <is the VM running after sending this response>
"success" : true
}
```
# Events
## Event `break`
The event `break` indicate that the execution in the VM has stopped due to a break condition. This can be caused by an unconditional break request, by a break point previously set, a stepping action have completed or by executing the `debugger` statement in JavaScript.
```
{ "seq" : <number>,
"type" : "event",
"event" : "break",
"body" : { "invocationText" : <text representation of the stack frame>,
"sourceLine" : <source line where execution is stopped>,
"sourceColumn" : <column within the source line where execution is stopped>,
"sourceLineText" : <text for the source line where execution is stopped>,
"script" : { name : <resource name of the origin of the script>
lineOffset : <line offset within the origin of the script>
columnOffset : <column offset within the origin of the script>
lineCount : <number of lines in the script>
"breakpoints" : <array of break point numbers hit if any>
}
}
```
Here are a couple of examples.
```
{"seq":117,"type":"event","event":"break","body":{"functionName":"f","sourceLine":1,"sourceColumn":14}}
{"seq":117,"type":"event","event":"break","body":{"functionName":"g","scriptData":"test.js","sourceLine":12,"sourceColumn":22,"breakpoints":[1]}}
{"seq":117,"type":"event","event":"break","body":{"functionName":"h","sourceLine":100,"sourceColumn":12,"breakpoints":[3,5,7]}}
```
## Event `exception`
The event `exception` indicate that the execution in the VM has stopped due to an exception.
```
{ "seq" : <number>,
"type" : "event",
"event" : "exception",
"body" : { "uncaught" : <boolean>,
"exception" : ...
"sourceLine" : <source line where the exception was thrown>,
"sourceColumn" : <column within the source line from where the exception was thrown>,
"sourceLineText" : <text for the source line from where the exception was thrown>,
"script" : { "name" : <name of script>
"lineOffset" : <number>
"columnOffset" : <number>
"lineCount" : <number>
}
}
}
```
# Response object serialization
Some responses contain objects as part of the body, e.g. the response to the evaluate request contains the result of the expression evaluated.
All objects exposed through the debugger is assigned an ID called a handle. This handle is serialized and can be used to identify objects. A handle has a certain lifetime after which it will no longer refer to the same object. Currently the lifetime of handles match the processing of a debug event. For each debug event handles are recycled.
An object can be serialized either as a reference to a given handle or as a value representation containing the object content.
An object serialized as a reference looks follows this where `<handle>` is an integer.
```
{"ref":<handle>}
```
For objects serialized as value they all contains the handle and the type of the object.
```
{ "handle" : <handle>,
"type" : <"undefined", "null", "boolean", "number", "string", "object", "function" or "frame">
}
```
In some situations special transient objects are created by the debugger. These objects are not really visible in from JavaScript, but are created to materialize something inside the VM as an object visible to the debugger. One example of this is the local scope object returned from the `scope` and `scopes` request. Transient objects are identified by having a negative handle. A transient object can never be retrieved using the `lookup` request, so all transient objects referenced will be in the `refs` part of the response. The lifetime of transient objects is basically the request they are involved in.
For the primitive JavaScript types `undefined` and `null` the type describes the value fully.
```
{"handle":<handle>,"type":"undefined"}
```
```
{"handle":<handle>,"type":"null"}
```
For the rest of the primitive types `boolean`, `number` and `string` the value is part of the result.
```
{ "handle":<handle>,
"type" : <"boolean", "number" or "string">
"value" : <JSON encoded value>
}
```
Boolean value.
```
{"handle":7,"type":"boolean","value":true}
```
Number value.
```
{"handle":8,"type":"number","value":42}
```
String value.
```
{"handle":9,"type":"string","value":"a string"}
```
An object is encoded with additional information.
```
{ "handle" : <handle>,
"type" : "object",
"className" : <Class name, ECMA-262 property [[Class]]>,
"constructorFunction" : {"ref":<handle>},
"protoObject" : {"ref":<handle>},
"prototypeObject" : {"ref":<handle>},
"properties" : [ {"name" : <name>,
"ref" : <handle>
},
...
]
}
```
The difference between the `protoObject` and the `prototypeObject` is that the `protoObject` contains a reference to the actual prototype object (for which accessibility is not defined in ECMA-262, but in V8 it is accessible using the `__proto__` property) whereas the `prototypeObject` is the value of the `prototype` property.
Here is an example.
```
{"handle":3,"type":"object","className":"Object","constructorFunction":{"ref":4},"protoObject":{"ref":5},"prototypeObject":{"ref":6},"properties":[{"name":"a","ref:7},{"name":"b","ref":8}]}
```
An function is encoded as an object but with additional information in the properties `name`, `inferredName`, `source` and `script`.
```
{ "handle" : <handle>,
"type" : "function",
"className" : "Function",
"constructorFunction" : {"ref":<handle>},
"protoObject" : {"ref":<handle>},
"prototypeObject" : {"ref":<handle>},
"name" : <function name>,
"inferredName" : <inferred function name for anonymous functions>
"source" : <function source>,
"script" : <reference to function script>,
"scriptId" : <id of function script>,
"position" : <function begin position in script>,
"line" : <function begin source line in script>,
"column" : <function begin source column in script>,
"properties" : [ {"name" : <name>,
"ref" : <handle>
},
...
]
}
```

63
docs/gdb_jit_interface.md
View File

@ -1,63 +0,0 @@
# Prerequisites
* V8 3.0.9 or newer
* GDB 7.0 or newer
* Linux OS
* CPU with Intel-compatible architecture (ia32 or x64)
# Introduction
GDB JIT interface integration allows V8 to provide GDB with the symbol and debugging information for a native code emitted in runtime.
When GDB JIT interface is disabled a typical backtrace in GDB will contain frames marked with ??. This frames correspond to dynamically generated code:
```
#8 0x08281674 in v8::internal::Runtime_SetProperty (args=...) at src/runtime.cc:3758
#9 0xf5cae28e in ?? ()
#10 0xf5cc3a0a in ?? ()
#11 0xf5cc38f4 in ?? ()
#12 0xf5cbef19 in ?? ()
#13 0xf5cb09a2 in ?? ()
#14 0x0809e0a5 in v8::internal::Invoke (construct=false, func=..., receiver=..., argc=0, args=0x0,
has_pending_exception=0xffffd46f) at src/execution.cc:97
```
However enabling GDB JIT integration allows GDB to produce more informative stack trace:
```
#6 0x082857fc in v8::internal::Runtime_SetProperty (args=...) at src/runtime.cc:3758
#7 0xf5cae28e in ?? ()
#8 0xf5cc3a0a in loop () at test.js:6
#9 0xf5cc38f4 in test.js () at test.js:13
#10 0xf5cbef19 in ?? ()
#11 0xf5cb09a2 in ?? ()
#12 0x0809e1f9 in v8::internal::Invoke (construct=false, func=..., receiver=..., argc=0, args=0x0,
has_pending_exception=0xffffd44f) at src/execution.cc:97
```
Frames still unknown to GDB correspond to native code without source information. See [GDBJITInterface#KnownLimitations](GDBJITInterface#KnownLimitations.md) for more details.
GDB JIT interface is specified in the GDB documentation: http://sourceware.org/gdb/current/onlinedocs/gdb/JIT-Interface.html
# Enabling GDB JIT integration
GDBJIT currently is by default excluded from the compilation and disabled in runtime. To enable it:
1. Build V8 library with `ENABLE_GDB_JIT_INTERFACE` defined. If you are using scons to build V8 run it with `gdbjit=on`.
1. Pass `--gdbjit` flag when starting V8.
To check that you have enabled GDB JIT integration correctly try setting breakpoint on `__jit_debug_register_code`. This function will be invoked to notify GDB about new code objects.
# Known Limitations
* GDB side of JIT Interface currently (as of GDB 7.2) does not handle registration of code objects very effectively. Each next registration takes more time: with 500 registered objects each next registration takes more than 50ms, with 1000 registered code objects - more than 300 ms. This problem was reported to GDB developers (http://sourceware.org/ml/gdb/2011-01/msg00002.html) but currently there is no solution available. To reduce pressure on GDB current implementation of GDB JIT integration operates in two modes: _default_ and _full_ (enabled by `--gdbjit-full` flag). In _default_ mode V8 notifies GDB only about code objects that have source information attached (this usually includes all user scripts). In _full_ - about all generated code objects (stubs, ICs, trampolines).
* On x64 GDB is unable to properly unwind stack without `.eh_frame` section (Issue 1053 (on Google Code))
* GDB is not notified about code deserialized from the snapshot (Issue 1054 (on Google Code))
* Only Linux OS on Intel-compatible CPUs is supported. For different OSes either a different ELF-header should be generated or a completely different object format should be used.
* Enabling GDB JIT interface disables compacting GC. This is done to reduce pressure on GDB as unregistering and registering each moved code object will incur considerable overhead.
* GDB JIT integration provides only _approximate_ source information. It does not provide any information about local variables, function's arguments, stack layout etc. It does not enable stepping through JavaScript code or setting breakpoint on the given line. However one can set a breakpoint on a function by it's name.

24
docs/handling_of_ports.md
View File

@ -1,24 +0,0 @@
# General
This article describes how ports should be handled.
# MIPS
## Straight-forward MIPS ports
1. Do them yourself.
## More complicated MIPS ports
1. CC the MIPS team in the CL. Use the mailing list v8-mips-ports.at.googlegroups.com for that purpose.
1. The MIPS team will provide you with a patch which you need to merge into your CL.
1. Then land the CL.
# PPC (not officially supported)
1. Contact/CC the PPC team in the CL if needed. Use the mailing list v8-ppc-ports.at.googlegroups.com for that purpose.
# x87 (not officially supported)
1. Contact/CC the x87 team in the CL if needed. Use the mailing list v8-x87-ports.at.googlegroups.com for that purpose.
# ARM
## Straight-forward ARM ports
1. Do them yourself.
## When you are lost
1. CC the ARM team in the CL. Use the mailing list v8-arm-ports.at.googlegroups.com for that purpose.

44
docs/i18n_support.md
View File

@ -1,44 +0,0 @@
# ECMAScript 402
V8 optionally implements the [ECMAScript 402](http://www.ecma-international.org/ecma-402/1.0/) API. The API is enabled by default, but can be turned off at compile time.
## Prerequisites
The i18n implementation adds a dependency on ICU. If you run
```
make dependencies
```
a suitable version of ICU is checked out into `third_party/icu`.
### Alternative ICU checkout
You can check out the ICU sources at a different location and define the gyp variable `icu_gyp_path` to point at the `icu.gyp` file.
### System ICU
Last but not least, you can compile V8 against a version of ICU installed in your system. To do so, specify the gyp variable `use_system_icu=1`. If you also have `want_separate_host_toolset` enabled, the bundled ICU will still be compiled to generate the V8 snapshot. The system ICU will only be used for the target architecture.
## Embedding V8
If you embed V8 in your application, but your application itself doesn't use ICU, you will need to initialize ICU before calling into V8 by executing:
```
v8::V8::InitializeICU();
```
It is safe to invoke this method if ICU was not compiled in, then it does nothing.
## Compiling without i18n support
To build V8 without i18n support use
```
make i18nsupport=off native
```

6
docs/javascript.md
View File

@ -1,6 +0,0 @@
# Introduction
JavaScript is a dynamically typed scripting language universally used to
script web content in browsers.
Its specification by ECMA can be found [here](http://www.ecma-international.org/publications/standards/Ecma-262.htm).

161
docs/javascript_stack_trace_api.md
View File

@ -1,161 +0,0 @@
All internal errors thrown in V8 capture a stack trace when they are created that can be accessed from JavaScript through the error.stack property. V8 also has various hooks for controlling how stack traces are collected and formatted, and for allowing custom errors to also collect stack traces. This document outlines V8's JavaScript stack trace API.
### Basic stack traces
By default, almost all errors thrown by V8 have a `stack` property that holds the topmost 10 stack frames, formatted as a string. Here's an example of a fully formatted stack trace:
```
ReferenceError: FAIL is not defined
at Constraint.execute (deltablue.js:525:2)
at Constraint.recalculate (deltablue.js:424:21)
at Planner.addPropagate (deltablue.js:701:6)
at Constraint.satisfy (deltablue.js:184:15)
at Planner.incrementalAdd (deltablue.js:591:21)
at Constraint.addConstraint (deltablue.js:162:10)
at Constraint.BinaryConstraint (deltablue.js:346:7)
at Constraint.EqualityConstraint (deltablue.js:515:38)
at chainTest (deltablue.js:807:6)
at deltaBlue (deltablue.js:879:2)
```
The stack trace is collected when the error is created and is the same regardless of where or how many times the error is thrown. We collect 10 frames because it is usually enough to be useful but not so many that it has a noticeable performance impact. You can control how many stack frames are collected by setting the variable
```
Error.stackTraceLimit
```
Setting it to 0 will disable stack trace collection. Any finite integer value will be used as the maximum number of frames to collect. Setting it to `Infinity` means that all frames will be collected. This variable only affects the current context, it has to be set explicitly for each context that needs a different value. (Note that what is known as a "context" in V8 terminology corresponds to a page or iframe in Google Chrome). To set a different default value that affects all contexts use the
```
--stack-trace-limit <value>
```
command-line flag to V8. To pass this flag to V8 when running Google Chrome use
```
--js-flags="--stack-trace-limit <value>"
```
### Stack trace collection for custom exceptions
The stack trace mechanism used for built-in errors is implemented using a general stack trace collection API that is also available to user scripts. The function
```
Error.captureStackTrace(error, constructorOpt)
```
adds a stack property to the given `error` object that will yield the stack trace at the time captureStackTrace was called. The reason for not just returning the formatted stack trace directly is that this way we can postpone the formatting of the stack trace until the stack property is accessed and avoid formatting completely if it never is.
The optional `constructorOpt` parameter allows you to pass in a function value. When collecting the stack trace all frames above the topmost call to this function, including that call, will be left out of the stack trace. This can be useful to hide implementation details that won't be useful to the user. The usual way of defining a custom error that captures a stack trace would be:
```
function MyError() {
Error.captureStackTrace(this, MyError);
// any other initialization
}
```
Passing in MyError as a second argument means that the constructor call to MyError won't show up in the stack trace.
### Customizing stack traces
Unlike Java where the stack trace of an exception is a structured value that allows inspection of the stack state, the stack property in V8 just holds a flat string containing the formatted stack trace. This is for no other reason than compatibility with other browsers. However, this is not hardcoded but only the default behavior and can be overridden by user scripts.
For efficiency stack traces are not formatted when they are captured but on demand, the first time the stack property is accessed. A stack trace is formatted by calling
```
Error.prepareStackTrace(error, structuredStackTrace)
```
and using whatever this call returns as the value of the `stack` property. If you assign a different function value to `Error.prepareStackTrace` that function will be used to format stack traces. It will be passed the error object that it is preparing a stack trace for and a structured representation of the stack. User stack trace formatters are free to format the stack trace however they want and even return non-string values. It is safe to retain references to the structured stack trace object after a call to prepareStackTrace completes so that it is also a valid return value. Note that the custom prepareStackTrace function is immediately called at the point when the error object is created (e.g. with `new Error()`).
The structured stack trace is an Array of CallSite objects, each of which represents a stack frame. A CallSite object defines the following methods
* **getThis**: returns the value of this
* **getTypeName**: returns the type of this as a string. This is the name of the function stored in the constructor field of this, if available, otherwise the object's `[[Class]]` internal property.
* **getFunction**: returns the current function
* **getFunctionName**: returns the name of the current function, typically its name property. If a name property is not available an attempt will be made to try to infer a name from the function's context.
* **getMethodName**: returns the name of the property of this or one of its prototypes that holds the current function
* **getFileName**: if this function was defined in a script returns the name of the script
* **getLineNumber**: if this function was defined in a script returns the current line number
* **getColumnNumber**: if this function was defined in a script returns the current column number
* **getEvalOrigin**: if this function was created using a call to eval returns a CallSite object representing the location where eval was called
* **isToplevel**: is this a toplevel invocation, that is, is this the global object?
* **isEval**: does this call take place in code defined by a call to eval?
* **isNative**: is this call in native V8 code?
* **isConstructor**: is this a constructor call?
The default stack trace is created using the CallSite API so any information that is available there is also available through this API.
To maintain restrictions imposed on strict mode functions, frames that have a strict mode function and all frames below (its caller etc.) are not allow to access their receiver and function objects. For those frames, `getFunction()` and `getThis()` will return `undefined`.
### Compatibility
The API described here is specific to V8 and is not supported by any other JavaScript implementations. Most implementations do provide an `error.stack` property but the format of the stack trace is likely to be different from the format described here. The recommended use of this API is
* Only rely on the layout of the formatted stack trace if you know your code is running in v8.
* It is safe to set `Error.stackTraceLimit` and `Error.prepareStackTrace` regardless of which implementation is running your code but be aware that it will only have an effect if your code is running in V8.
### Appendix: Stack trace format
The default stack trace format used by V8 can for each stack frame give the following information:
* Whether the call is a construct call.
* The type of the this value (Type).
* The name of the function called (functionName).
* The name of the property of this or one of its prototypes that holds the function (methodName).
* The current location within the source (location)
Any of these may be unavailable and different formats for stack frames are used depending on how much of this information is available. If all the above information is available a formatted stack frame will look like this:
```
at Type.functionName [as methodName] (location)
```
or, in the case of a construct call
```
at new functionName (location)
```
If only one of functionName and methodName is available, or if they are both available but the same, the format will be:
```
at Type.name (location)
```
If neither is available `<anonymous>` will be used as the name.
The Type value is the name of the function stored in the constructor field of this. In v8 all constructor calls set this property to the constructor function so unless this field has been actively changed after the object was created it it will hold the name of the function it was created by. If it is unavailable the `[[Class]]` property of the object will be used.
One special case is the global object where the Type is not shown. In that case the stack frame will be formatted as
```
at functionName [as methodName] (location)
```
The location itself has several possible formats. Most common is the file name, line and column number within the script that defined the current function
```
fileName:lineNumber:columnNumber
```
If the current function was created using eval the format will be
```
eval at position
```
where position is the full position where the call to eval occurred. Note that this means that positions can be nested if there are nested calls to eval, for instance:
```
eval at Foo.a (eval at Bar.z (myscript.js:10:3))
```
If a stack frame is within V8's libraries the location will be
```
native
```
and if is unavailable it will be
```
unknown location
```

67
docs/merging_and_patching.md
View File

@ -1,67 +0,0 @@
# Introduction
If you have a patch to the master branch (e.g. an important bug fix) that needs to be merged into one of the production V8 branches, read on.
For the examples, a branched 2.4 version of V8 will be used. Substitute "2.4" with your version number.
**An associated issue on Chromium's or V8's issue tracker is mandatory if a patch is merged. This helps with keeping track of merges.
You can use [a template](https://code.google.com/p/v8/issues/entry?template=Merge%20request) to create an issue.**
# Merge process outlined
The merge process in the Chromium and V8 tracker is driven by labels in the form of
```
Merge-[Status]-[Branch]
```
The currently important labels for V8 are:
1. Merge-Request-## initiates the process => This fix should be merged into M-##
1. Merge-Review-## The merge is not approved yet for M-## e.g. because Canary coverage is missing
1. Merge-Approved-## => Simply means that the Chrome TPM are signing the merge off
1. Merge-Merged-$BRANCHNUMBER$ => When the merge is done the Merge-Approved label is swapped with this one. $BRANCHNUMBER$ is the name/number of the V8 branch e.g. 4.3 for M-43.
# Instructions for git using the automated script
## How to check if a commit was already merged/reverted
Use mergeinfo.py to get all the commits which are connected to the HASH according to Git.
```
tools/release/mergeinfo.py HASH
```
## Step 1: Run the script
Let's assume you're merging revision af3cf11 to branch 2.4 (please specify full git hashes - abbreviations are used here for simplicity).
```
tools/release/merge_to_branch.py --branch 2.4 af3cf11
```
Run the script with '-h' to display its help message, which includes more options (e.g. you can specify a file containing your patch, or you can reverse a patch, specify a custom commit message, or resume a merging process you've canceled before). Note that the script will use a temporary checkout of v8 - it won't touch your work space.
You can also merge more than one revision at once, just list them all.
```
tools/release/merge_to_branch.py --branch 2.4 af3cf11 cf33f1b sf3cf09
```
## Step 2: Send a notification letter to hablich@chromium.org
Saying something like this:
```
_Subject:_ Regression fix merged into V8 2.4 branch (Chrome 8)
_Body:_ We have merged a fix to the V8 version 2.4 branch (the version used in Chrome 8)
Version 2.4.9.10: Issue xxx: The parser doesn't parse.
```
# FAQ
## I get an error during merge that is related to tagging. What should I do?
When two people are merging at the same time a race-condition can happen in the merge scripts. If this is the case, contact machenbach@chromium.org and hablich@chromium.org.
## Is there a TL;DR;?
1. [Create issue on issue tracker](https://code.google.com/p/v8/issues/entry?template=Merge%20request)
1. Add Merge-Request-{Branch} to the issue
1. Wait until somebody will add Merge-Approved-{Branch}
1. Merge

34
docs/profiling_chromium_with_v8.md
View File

@ -1,34 +0,0 @@
# Introduction
V8's CPU & Heap profilers are trivial to use from V8's shells (see V8Profiler), but it may appear confusing how to use them with Chromium. This page should help you with it.
# Instructions
## Why using V8's profilers with Chromium is different from using them with V8 shells?
Chromium is a complex application, unlike V8 shells. Below is the list of Chromium features that affect profiler usage:
* each renderer is a separate process (OK, not actually each, but let's omit this detail), so they can't share the same log file;
* sandbox built around renderer process prevents it from writing to a disk;
* Developer Tools configure profilers for their own purposes;
* V8's logging code contains some optimizations to simplify logging state checks.
## So, how to run Chromium to get a CPU profile?
Here is how to run Chromium in order to get a CPU profile from the start of the process:
```
./Chromium --no-sandbox --js-flags="--logfile=%t.log --prof"
```
Please note that you wouldn't see profiles in Developer Tools, because all the data is being logged to a file, not to Developer Tools.
### Flags description
* **--no-sandbox** - turns off the renderer sandbox, obviously must have;
* **--js-flags** - this is the containers for flags passed to V8:
* **--logfile=%t.log** - specifies a name pattern for log files; **%t** gets expanded into current time in milliseconds, so each process gets its own log file; you can use prefixes and suffixes if you want, like this: **prefix-%t-suffix.log**;
* **--prof** - tells V8 to write statistical profiling information into the log file.
## Notes
Under Windows, be sure to turn on .MAP file creation for **chrome.dll**, but not for **chrome.exe**.

57
docs/release_process.md
View File

@ -1,57 +0,0 @@
# Introduction
The V8 release process is tightly connected to [Chrome's](https://www.chromium.org/getting-involved/dev-channel). The V8 team is using all four Chrome release channels to push new versions to the users.
If you want to look up what V8 version is in a Chrome release you can check [OmahaProxy](https://omahaproxy.appspot.com/). For each Chrome release a separate branch is created in the V8 repository to make the trace-back easier e.g. for [Chrome 45.0.2413.0](https://chromium.googlesource.com/v8/v8.git/+/chromium/2413).
# Canary releases
Every day a new Canary build is pushed to the users via [Chrome's Canary channel](https://www.google.com/chrome/browser/canary.html?platform=win64). Normally the deliverable is the latest, stable enough version from [master](https://chromium.googlesource.com/v8/v8.git/+/roll).
Branches for a Canary normally look like this
```
remotes/origin/4.5.35
```
# Dev releases
Every week a new Dev build is pushed to the users via [Chrome's Dev channel](https://www.google.com/chrome/browser/desktop/index.html?extra=devchannel&platform=win64). Normally the deliverable includes the latest stable enough V8 version on the Canary channel.
Branches for a Dev normally look like this
```
remotes/origin/4.5.35
```
# Beta releases
Roughly every 6 weeks a new major branch is created e.g. [for Chrome 44](https://chromium.googlesource.com/v8/v8.git/+log/branch-heads/4.4). This is happening in sync with the creation of [Chrome's Beta channel](https://www.google.com/chrome/browser/beta.html?platform=win64). The Chrome Beta is pinned to the head of V8's branch. After approx. 6 weeks the branch is promoted to Stable.
Changes are only cherry-picked onto the branch in order to stabilize the version.
Branches for a Beta normally look like this
```
remotes/branch-heads/4.5
```
They are based on a Canary branch.
# Stable releases
Roughly every 6 weeks a new major Stable release is done. No special branch is created as the latest Beta branch is simply promoted to Stable. This version is pushed to the users via [Chrome's Stable channel](https://www.google.com/chrome/browser/desktop/index.html?platform=win64).
Branches for a Stable normally look like this
```
remotes/branch-heads/4.5
```
They are promoted (reused) Beta branches.
# Which version should I embed in my application?
The tip of the same branch that Chrome's Stable channel uses.
We often backmerge important bug fixes to a stable branch, so if you care about stability and security and correctness, you should include those updates too -- that's why we recommend "the tip of the branch", as opposed to an exact version.
As soon as a new branch is promoted to Stable, we stop maintaining the previous stable branch. This happens every six weeks, so you should be prepared to update at least this often.
Example: The current stable Chrome release is [44.0.2403.125](https://omahaproxy.appspot.com), with V8 4.4.63.25. So you should embed [branch-heads/4.4](https://chromium.googlesource.com/v8/v8.git/+/branch-heads/4.4). And you should update to branch-heads/4.5 when Chrome 45 is released on the Stable channel.

7
docs/runtime_functions.md
View File

@ -1,7 +0,0 @@
# Runtime functions
Much of the JavaScript library is implemented in JavaScript code itself,
using a minimal set of C++ runtime functions callable from JavaScript.
Some of these are called using names that start with %, and using the flag
"--allow-natives-syntax". Others are only called by code generated by the
code generators, and are not visible in JS, even using the % syntax.

41
docs/source.md
View File

@ -1,41 +0,0 @@
# Source
**Quick links:** [browse](https://chromium.googlesource.com/v8/v8/) | [browse bleeding edge](https://chromium.googlesource.com/v8/v8/+/master) | [changes](https://chromium.googlesource.com/v8/v8/+log/master).
## Command-Line Access
### Git
See [UsingGit](using_git.md).
### Subversion (deprecated)
Use this command to anonymously check out the up-to-date stable version of the project source code:
> `svn checkout http://v8.googlecode.com/svn/trunk/ v8`
If you plan to contribute to V8 but are not a member, use this command to anonymously check out a read-only version of the development branch:
> `svn checkout http://v8.googlecode.com/svn/branches/bleeding_edge/ v8`
If you're a member of the project, use this command to check out a writable development branch as yourself using HTTPS:
> `svn checkout https://v8.googlecode.com/svn/branches/bleeding_edge/ v8 --username <your username>`
When prompted, enter your generated [googlecode.com](http://code.google.com/hosting/settings) password.
## Source Code Branches
There are several different branches of V8; if you're unsure of which version to get, you most likely want the up-to-date stable version in `trunk/`. Here's an overview of the different branches:
* The bleeding edge, `branches/bleeding_edge/`, is where active development takes place. If you're considering contributing to V8 this is the branch to get.
* Under `trunk/` is the "stable edge", which is updated a few times per week. It is a copy of the bleeding edge that has been successfully tested. Use this if you want to be almost up to date and don't want your code to break whenever we accidentally forget to add a file on the bleeding edge. Some of the trunk revisions are tagged with X.Y.Z.T version labels. When we decide which of X.Y.**.** is the "most stable", it becomes the X.Y branch in subversion.
* If you want a well-tested version that doesn't change except for bugfixes, use one of the versioned branches (e.g. `branches/3.16/` at the time of this writing). Note that usually only the last two branches are actively maintained; any older branches could have unfixed security holes. You may want to follow the V8 version that Chrome is shipping on its stable (or beta) channels, see http://omahaproxy.appspot.com.
## V8 public API compatibility
V8 public API (basically the files under include/ directory) may change over time. New types/methods may be added without breaking existing functionality. When we decide that want to drop some existing class/methods, we first mark it with [V8\_DEPRECATED](https://code.google.com/p/chromium/codesearch#search/&q=V8_DEPRECATED&sq=package:chromium&type=cs) macro which will cause compile time warnings when the deprecated methods are called by the embedder. We keep deprecated method for one branch and then remove it. E.g. if `v8::CpuProfiler::FindCpuProfile` was plain non deprecated in _3.17_ branch, marked as `V8_DEPRECATED` in _3.18_, it may well be removed in _3.19_ branch.
## GUI and IDE Access
This project's Subversion repository may be accessed using many different client programs and plug-ins. See your client's documentation for more information.

58
docs/testing.md
View File

@ -1,58 +0,0 @@
V8 includes a test framework that allows you to test the engine. The framework lets you run both our own test suites that are included with the source code and others, currently only the Mozilla tests.
## Running the V8 tests
Before you run the tests, you will have to build V8 with GYP using the instructions [here](http://code.google.com/p/v8-wiki/wiki/BuildingWithGYP)
You can append `.check` to any build target to have tests run for it, e.g.
```
make ia32.release.check
make ia32.check
make release.check
make check # builds and tests everything (no dot before "check"!)
```
Before submitting patches, you should always run the quickcheck target, which builds a fast debug build and runs only the most relevant tests:
```
make quickcheck
```
You can also run tests manually:
```
tools/run-tests.py --arch-and-mode=ia32.release [--outdir=foo]
```
Or you can run individual tests:
```
tools/run-tests.py --arch=ia32 cctest/test-heap/SymbolTable mjsunit/delete-in-eval
```
Run the script with `--help` to find out about its other options, `--outdir` defaults to `out`. Also note that using the `cctest` binary to run multiple tests in one process is not supported.
## Running the Mozilla and Test262 tests
The V8 test framework comes with support for running the Mozilla as well as the Test262 test suite. To download the test suites and then run them for the first time, do the following:
```
tools/run-tests.py --download-data mozilla
tools/run-tests.py --download-data test262
```
To run the tests subsequently, you may omit the flag that downloads the test suite:
```
tools/run-tests.py mozilla
tools/run-tests.py test262
```
Note that V8 fails a number of Mozilla tests because they require Firefox-specific extensions.
## Running the WebKit tests
Sometimes all of the above tests pass but WebKit build bots fail. To make sure WebKit tests pass run:
```
tools/run-tests.py --progress=verbose --outdir=out --arch=ia32 --mode=release webkit --timeout=200
```
Replace --arch and other parameters with values that match your build options.

22
docs/triaging_issues.md
View File

@ -1,22 +0,0 @@
# How to get an issue triaged
* *V8 tracker*: Set the state to `Untriaged`
* *Chromium tracker*: Set the state to `Untriaged` and add the label `Cr-Blink-JavaScript`
# How to assign V8 issues in the Chromium tracker
Please assign issues to the V8 specialty sheriffs of one of the
following categories:
* Stability: jkummerow@c....org, adamk@c....org
* Performance: bmeurer@c....org, mvstanton@c....org
* Clusterfuzz: Set the bug to the following state:
* `label:ClusterFuzz label:Cr-Blink-JavaScript status:Available -has:owner`
* Will show up in [this](https://code.google.com/p/chromium/issues/list?can=2&q=label%3AClusterFuzz+label%3ACr-Blink-JavaScript+status%3AAvailable+-has%3Aowner&colspec=ID+Pri+M+Week+ReleaseBlock+Cr+Status+Owner+Summary+OS+Modified&x=m&y=releaseblock&cells=tiles) query.
* CC mstarzinger@ and ishell@
Please CC hablich@c....org on all issues.
Assign remaining issues to hablich@c....org.
Use the label Cr-Blink-JavaScript on all issues.
**Please note that this only applies to issues tracked in the Chromium issue tracker.**

147
docs/using_git.md
View File

@ -1,147 +0,0 @@
# Git repository
V8's git repository is located at https://chromium.googlesource.com/v8/v8.git
V8's master branch has also an official git mirror on github: http://github.com/v8/v8-git-mirror.
**Don't just `git-clone` either of these URLs** if you want to build V8 from your checkout, instead follow the instructions below to get everything set up correctly.
## Prerequisites
1. **Git**. To install using `apt-get`:
```
apt-get install git
```
1. **depot\_tools**. See [instructions](http://dev.chromium.org/developers/how-tos/install-depot-tools).
1. For **push access**, you need to setup a .netrc file with your git password:
1. Go to https://chromium.googlesource.com/new-password - login with your committer account (e.g. @chromium.org account, non-chromium.org ones work too). Note: creating a new password doesn't automatically revoke any previously created passwords.
1. Follow the instructions in the "Staying Authenticated" section. It would ask you to copy-paste two lines into your ~/.netrc file.
1. In the end, ~/.netrc should have two lines that look like:
```
machine chromium.googlesource.com login git-yourusername.chromium.org password <generated pwd>
machine chromium-review.googlesource.com login git-yourusername.chromium.org password <generated pwd>
```
1. Make sure that ~/.netrc file's permissions are 0600 as many programs refuse to read .netrc files which are readable by anyone other than you.
## How to start
Make sure depot\_tools are up-to-date by typing once:
```
gclient
```
Then get V8, including all branches and dependencies:
```
fetch v8
cd v8
```
After that you're intentionally in a detached head state.
Optionally you can specify how new branches should be tracked:
```
git config branch.autosetupmerge always
git config branch.autosetuprebase always
```
Alternatively, you can create new local branches like this (recommended):
```
git new-branch mywork
```
## Staying up-to-date
Update your current branch with git pull. Note that if you're not on a branch, git pull won't work, and you'll need to use git fetch instead.
```
git pull
```
Sometimes dependencies of v8 are updated. You can synchronize those by running
```
gclient sync
```
## Sending code for reviewing
```
git cl upload
```
## Committing
You can use the CQ checkbox on codereview for committing (preferred). See also the [chromium instructions](http://www.chromium.org/developers/testing/commit-queue) for CQ flags and troubleshooting.
If you need more trybots than the default, add the following to your commit message on rietveld (e.g. for adding a nosnap bot):
```
CQ_INCLUDE_TRYBOTS=tryserver.v8:v8_linux_nosnap_rel
```
To land manually, update your branch:
```
git pull --rebase origin
```
Then commit using
```
git cl land
```
# For project members
## Try jobs
### Creating a try job from codereview
1. Upload a CL to rietveld.
```
git cl upload
```
1. Try the CL by sending a try job to the try bots like this:
```
git cl try
```
1. Wait for the try bots to build and you will get an e-mail with the result. You can also check the try state at your patch on codereview.
1. If applying the patch fails you either need to rebase your patch or specify the v8 revision to sync to:
```
git cl try --revision=1234
```
### Creating a try job from a local branch
1. Commit some changes to a git branch in the local repo.
1. Try the change by sending a try job to the try bots like this:
```
git try
```
1. Wait for the try bots to build and you will get an e-mail with the result. Note: There are issues with some of the slaves at the moment. Sending try jobs from codereview is recommended.
### Useful arguments
The revision argument tells the try bot what revision of the code base will be used for applying your local changes to. Without the revision, our LKGR revision is used as the base (http://v8-status.appspot.com/lkgr).
```
git try --revision=1234
```
To avoid running your try job on all bots, use the --bot flag with a comma-separated list of builder names. Example:
```
git try --bot=v8_mac_rel
```
### Viewing the try server
http://build.chromium.org/p/tryserver.v8/waterfall
### Access credentials
If asked for access credentials, use your @chromium.org email address and your generated password from [googlecode.com](http://code.google.com/hosting/settings).

3
docs/v8_c_plus_plus_styleand_sops.md
View File

@ -1,3 +0,0 @@
# V8 C++ Style Guide
In general, V8 should conform to Google's/Chrome's C++ Style Guide for new code that is written. Your V8 code should conform to them as much as possible. There will always be cases where Google/Chrome Style Guide conformity or Google/Chrome best practices are extremely cumbersome or underspecified for our use cases. We document these exceptions here.

39
docs/v8_committers_responsibility.md
View File

@ -1,39 +0,0 @@
# V8 committer's responsibility
## Basic commit guidelines
When you're committing to the V8 repositories, ensure that you follow those guidelines:
1. Find the right reviewer for your changes and for patches you're asked to review.
1. Be available on IM and/or email before and after you land the change.
1. Watch the [waterfall](http://build.chromium.org/p/client.v8/console) until all bots turn green after your change.
1. When landing a TBR change (To Be Reviewed), make sure to notify the people whose code you're changing. Usually just send the review e-mail.
In short, do the right thing for the project, not the easiest thing to get code committed, and above all: use your best judgement.
**Don't be afraid to ask questions. There is always someone who will immediately read messages sent to the v8-committers mailing list who can help you.**
## Changes with multiple reviewers
There are occasionally changes with a lot of reviewers on them, since sometimes several people might need to be in the loop for a change because of multiple areas of responsibility and expertise.
The problem is that without some guidelines, there's no clear responsibility given in these reviews.
If you're the sole reviewer on a change, you know you have to do a good job. When there are three other people, you sometimes assume that somebody else must have looked carefully at some part of the review. Sometimes all the reviewers think this and the change isn't reviewed properly.
In other cases, some reviewers say "LGTM" for a patch, while others are still expecting changes. The author can get confused as to the status of the review, and some patches have been checked in where at least one reviewer expected further changes before committing.
At the same time, we want to encourage many people to participate in the review process and keep tabs on what's going on.
So, here are some guidelines to help clarify the process:
1. When a patch author requests more than one reviewer, they should make clear in the review request email what they expect the responsibility of each reviewer to be. For example, you could write this in the email:
* larry: bitmap changes
* sergey: process hacks
* everybody else: FYI
1. In this case, you might be on the review list because you've asked to be in the loop for multiprocess changes, but you wouldn't be the primary reviewer and the author and other reviewers wouldn't be expecting you to review all the diffs in detail.
1. If you get a review that includes many other people, and the author didn't do (1), please ask them what part you're responsible for if you don't want to review the whole thing in detail.
1. The author should wait for approval from everybody on the reviewer list before checking in.
1. People who are on a review without clear review responsibility (i.e. drive-by reviews) should be super responsive and not hold up the review. The patch author should feel free to ping them mercilessly if they are.
1. If you're an "FYI" person on a review and you didn't actually review in detail (or at all), but don't have a problem with the patch, note this. You could say something like "rubber stamp" or "ACK" instead of "LGTM." This way the real reviewers know not to trust that you did their work for them, but the author of the patch knows they don't have to wait for further feedback from you. Hopefully we can still keep everybody in the loop but have clear ownership and detailed reviews. It might even speed up some changes since you can quickly "ACK" changes you don't care about, and the author knows they don't have to wait for feedback from you.
(Adapted from: http://dev.chromium.org/developers/committers-responsibility )

141
docs/v8_profiler.md
View File

@ -1,141 +0,0 @@
# Introduction
V8 has built-in sample based profiling. Profiling is turned off by default, but can be enabled via the --prof command line option. The sampler records stacks of both JavaScript and C/C++ code.
# Build
Build the d8 shell following the instructions at [BuildingWithGYP](BuildingWithGYP.md).
# Command Line
To start profiling, use the `--prof` option. When profiling, V8 generates a `v8.log` file which contains profiling data.
Windows:
```
build\Release\d8 --prof script.js
```
Other platforms (replace "ia32" with "x64" if you want to profile the x64 build):
```
out/ia32.release/d8 --prof script.js
```
# Process the Generated Output
Log file processing is done using JS scripts running by the d8 shell. For this to work, a `d8` binary (or symlink, or `d8.exe` on Windows) must be in the root of your V8 checkout, or in the path specified by the environment variable `D8_PATH`. Note: this binary is just used to process the log, but not for the actual profiling, so it doesn't matter which version etc. it is.
Windows:
```
tools\windows-tick-processor.bat v8.log
```
Linux:
```
tools/linux-tick-processor v8.log
```
Mac OS X:
```
tools/mac-tick-processor v8.log
```
## Snapshot-based VM build and builtins reporting
When a snapshot-based VM build is being used, code objects from a snapshot that don't correspond to functions are reported with generic names like _"A builtin from the snapshot"_, because their real names are not stored in the snapshot. To see the names the following steps must be taken:
* `--log-snapshot-positions` flag must be passed to VM (along with `--prof`); this way, for deserialized objects the `(memory address, snapshot offset)` pairs are being emitted into profiler log;
* `--snapshot-log=<log file from mksnapshot>` flag must be passed to the tick processor script; a log file from the `mksnapshot` program (a snapshot log) contains address-offset pairs for serialized objects, and their names; using the snapshot log, names can be mapped onto deserialized objects during profiler log processing; the snapshot log file is called `snapshot.log` and resides alongside with V8's compiled files.
An example of usage:
```
out/ia32.release/d8 --prof --log-snapshot-positions script.js
tools/linux-tick-processor --snapshot-log=out/ia32.release/obj.target/v8_snapshot/geni/snapshot.log v8.log
```
# Programmatic Control of Profiling
If you would like to control in your application when profile samples are collected, you can do so.
First you'll probably want to use the `--noprof-auto` command line switch which prevents the profiler from automatically starting to record profile ticks.
Profile ticks will not be recorded until your application specifically invokes these APIs:
* `V8::ResumeProfiler()` - start/resume collection of data
* `V8::PauseProfiler()` - pause collection of data
# Example Output
```
Statistical profiling result from benchmarks\v8.log, (4192 ticks, 0 unaccounted, 0 excluded).
[Shared libraries]:
ticks total nonlib name
9 0.2% 0.0% C:\WINDOWS\system32\ntdll.dll
2 0.0% 0.0% C:\WINDOWS\system32\kernel32.dll
[JavaScript]:
ticks total nonlib name
741 17.7% 17.7% LazyCompile: am3 crypto.js:108
113 2.7% 2.7% LazyCompile: Scheduler.schedule richards.js:188
103 2.5% 2.5% LazyCompile: rewrite_nboyer earley-boyer.js:3604
103 2.5% 2.5% LazyCompile: TaskControlBlock.run richards.js:324
96 2.3% 2.3% Builtin: JSConstructCall
...
[C++]:
ticks total nonlib name
94 2.2% 2.2% v8::internal::ScavengeVisitor::VisitPointers
33 0.8% 0.8% v8::internal::SweepSpace
32 0.8% 0.8% v8::internal::Heap::MigrateObject
30 0.7% 0.7% v8::internal::Heap::AllocateArgumentsObject
...
[GC]:
ticks total nonlib name
458 10.9%
[Bottom up (heavy) profile]:
Note: percentage shows a share of a particular caller in the total
amount of its parent calls.
Callers occupying less than 2.0% are not shown.
ticks parent name
741 17.7% LazyCompile: am3 crypto.js:108
449 60.6% LazyCompile: montReduce crypto.js:583
393 87.5% LazyCompile: montSqrTo crypto.js:603
212 53.9% LazyCompile: bnpExp crypto.js:621
212 100.0% LazyCompile: bnModPowInt crypto.js:634
212 100.0% LazyCompile: RSADoPublic crypto.js:1521
181 46.1% LazyCompile: bnModPow crypto.js:1098
181 100.0% LazyCompile: RSADoPrivate crypto.js:1628
...
```
# Timeline plot
The timeline plot visualizes where V8 is spending time. This can be used to find bottlenecks and spot things that are unexpected (for example, too much time spent in the garbage collector). Data for the plot are gathered by both sampling and instrumentation. Linux with gnuplot 4.6 is required.
To create a timeline plot, run V8 as described above, with the option `--log-timer-events` additional to `--prof`:
```
out/ia32.release/d8 --prof --log-timer-events script.js
```
The output is then passed to a plot script, similar to the tick-processor:
```
tools/plot-timer-events v8.log
```
This creates `timer-events.png` in the working directory, which can be opened with most image viewers.
# Options
Since recording log output comes with a certain performance overhead, the script attempts to correct this using a distortion factor. If not specified, it tries to find out automatically. You can however also specify the distortion factor manually.
```
tools/plot-timer-events --distortion=4500 v8.log
```
You can also manually specify a certain range for which to create the plot or statistical profile, expressed in milliseconds:
```
tools/plot-timer-events --distortion=4500 --range=1000,2000 v8.log
tools/linux-tick-processor --distortion=4500 --range=1000,2000 v8.log
```
# HTML 5 version
Both statistical profile and timeline plot are available [in the browser](http://v8.googlecode.com/svn/branches/bleeding_edge/tools/profviz/profviz.html). However, the statistical profile lacks C++ symbol resolution and the Javascript port of gnuplot performs an order of magnitude slower than the native one.