Skip to content

V
V8
Commit 6e0cd215 authored by andybons's avatar andybons Committed by Commit bot
Browse files
Options

[Docs] Add wiki content to Markdown docs 

NOTE: You will have to land this as I don’t have write perms to this repo.

BUG=none
R=hablich@chromium.org

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

Cr-Commit-Position: refs/heads/master@{#30972}
parent b2d82a22
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 2642 additions and 0 deletions
docs/arm_debugging_with_the_simulator.md 0 → 100644
View file @ 6e0cd215
# 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.
```
\ No newline at end of file
docs/becoming_v8_committer.md 0 → 100644
View file @ 6e0cd215
## What is a committer?
Technically, a committer is someone who has write access to the V8 SVN 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 )
\ No newline at end of file
docs/building_with_gyp.md 0 → 100644
View file @ 6e0cd215
This diff is collapsed.
docs/contributing.md 0 → 100644
View file @ 6e0cd215
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/)
\ No newline at end of file
docs/cross_compiling_for_arm.md 0 → 100644
View file @ 6e0cd215
<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.
\ No newline at end of file
docs/d8_on_android.md 0 → 100644
View file @ 6e0cd215
# 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
```
\ No newline at end of file
docs/debugger_protocol.md 0 → 100644
View file @ 6e0cd215
This diff is collapsed.
docs/gdb_jit_interface.md 0 → 100644
View file @ 6e0cd215
# 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.
\ No newline at end of file
docs/handling_of_ports.md 0 → 100644
View file @ 6e0cd215
# 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.
\ No newline at end of file
docs/i18n_support.md 0 → 100644
View file @ 6e0cd215
# 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
```
\ No newline at end of file
docs/javascript.md 0 → 100644
View file @ 6e0cd215
# 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).
\ No newline at end of file
docs/javascript_stack_trace_api.md 0 → 100644
View file @ 6e0cd215
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
```
\ No newline at end of file
docs/merging_and_patching.md 0 → 100644
View file @ 6e0cd215
# 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 is mandatory if a patch is merged. This helps with keeping track of merges.**
# 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
1. Add Merge-Request-{Branch} to the issue
1. Wait until somebody will add Merge-Approved-{Branch}
1. Merge
\ No newline at end of file
docs/profiling_chromium_with_v8.md 0 → 100644
View file @ 6e0cd215
# 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**.
\ No newline at end of file
docs/release_process.md 0 → 100644
View file @ 6e0cd215
# 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.
\ No newline at end of file
docs/runtime_functions.md 0 → 100644
View file @ 6e0cd215
# Introduction
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.
<a href='Hidden comment:
= Details =
Here are the V8 runtime functions, their JS names, if they are visible,
and their documentation.
<wiki:comment>
\ No newline at end of file
docs/source.md 0 → 100644
View file @ 6e0cd215
**Quick links:** [browse](http://code.google.com/p/v8/source/browse) | [browse bleeding edge](http://code.google.com/p/v8/source/browse/branches/bleeding_edge) | [changes](https://chromium.googlesource.com/v8/v8.git).
## 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.
\ No newline at end of file
docs/testing.md 0 → 100644
View file @ 6e0cd215
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.
\ No newline at end of file
docs/triaging_issues.md 0 → 100644
View file @ 6e0cd215
# Instructions on how to assign V8 issues in the Chromium tracker
Please assign any 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.**
\ No newline at end of file
docs/using_git.md 0 → 100644
View file @ 6e0cd215
# 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).
\ No newline at end of file
docs/v8_c_plus_plus_styleand_sops.md 0 → 100644
View file @ 6e0cd215
# Introduction
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.
# Details
Coming Soon
\ No newline at end of file
docs/v8_committers_responsibility.md 0 → 100644
View file @ 6e0cd215
## 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:
```
a. larry: bitmap changes
b. sergey: process hacks
c. 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 )
\ No newline at end of file
docs/v8_profiler.md 0 → 100644
View file @ 6e0cd215
# 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.
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment