diff --git a/README.md b/README.md index 804df5edb47e..840c4971f915 100644 --- a/README.md +++ b/README.md @@ -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 @@ -36,5 +36,5 @@ configuration in `.git/config`: Contributing ============= -Please follow the instructions mentioned on the -[V8 wiki](https://code.google.com/p/v8-wiki/wiki/Contributing). +Please follow the instructions mentioned on the +[V8 wiki](https://github.com/v8/v8/wiki/Contributing). diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000000..0eded673b84c --- /dev/null +++ b/docs/README.md @@ -0,0 +1,2 @@ +The documentation for V8 can be found at the +[V8 Wiki](https://github.com/v8/v8/wiki). diff --git a/docs/arm_debugging_with_the_simulator.md b/docs/arm_debugging_with_the_simulator.md deleted file mode 100644 index fbb415614237..000000000000 --- a/docs/arm_debugging_with_the_simulator.md +++ /dev/null @@ -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 -``` -The simulator will start the debugger after executing n instructions. - -``` -$ out/arm.debug/d8 --stop_at -``` - -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 - - name = #test - - context = 0xb60083f1 - - code = 0xb544d681 - #arguments: 0xb545a15d (callback) - #length: 0xb545a14d (callback) - #name: 0xb545a155 (callback) - #prototype: 0xb545a145 (callback) - #caller: 0xb545a165 (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 diff --git a/docs/becoming_v8_committer.md b/docs/becoming_v8_committer.md deleted file mode 100644 index 0a927b3ca9f7..000000000000 --- a/docs/becoming_v8_committer.md +++ /dev/null @@ -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 ) diff --git a/docs/building_with_gyp.md b/docs/building_with_gyp.md deleted file mode 100644 index 0183fd2de519..000000000000 --- a/docs/building_with_gyp.md +++ /dev/null @@ -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 -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. \ No newline at end of file diff --git a/docs/contributing.md b/docs/contributing.md deleted file mode 100644 index aa8e6659762d..000000000000 --- a/docs/contributing.md +++ /dev/null @@ -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/) \ No newline at end of file diff --git a/docs/cross_compiling_for_arm.md b/docs/cross_compiling_for_arm.md deleted file mode 100644 index 30a7196b4a9c..000000000000 --- a/docs/cross_compiling_for_arm.md +++ /dev/null @@ -1,151 +0,0 @@ -

Building V8 with SCons is no longer supported. See BuildingWithGYP.

 - ---- - - -# 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 diff --git a/docs/d8_on_android.md b/docs/d8_on_android.md deleted file mode 100644 index eda641934593..000000000000 --- a/docs/d8_on_android.md +++ /dev/null @@ -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 -``` - * 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 diff --git a/docs/debugger_protocol.md b/docs/debugger_protocol.md deleted file mode 100644 index 2cc618fbd4cb..000000000000 --- a/docs/debugger_protocol.md +++ /dev/null @@ -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" : , - "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" : , - "type" : "request", - "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" : , - "type" : "response", - "request_seq" : , - "command" : - "body" : ... - "running" : - "success" : - "message" : -} -``` - -An `"event"` packet has the following structure: - -``` -{ "seq" : , - "type" : "event", - "event" : - 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" : , - "type" : "request", - "command" : "continue", - "arguments" : { "stepaction" : <"in", "next" or "out">, - "stepcount" : - } -} -``` - -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" : , - "type" : "response", - "request_seq" : , - "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" : , - "type" : "request", - "command" : "evaluate", - "arguments" : { "expression" : , - "frame" : , - "global" : , - "disable_break" : , - "additional_context" : [ - { "name" : , "handle" : }, - { "name" : , "handle" : }, - ... - ] - } -} -``` - -Optional argument `additional_context` specifies handles that will be visible from the expression under corresponding names (see example below). - -Response: - -``` -{ "seq" : , - "type" : "response", - "request_seq" : , - "command" : "evaluate", - "body" : ... - "running" : - "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" : , - "type" : "request", - "command" : "lookup", - "arguments" : { "handles" : , - "includeSource" : , - } -} -``` - -Response: - -``` -{ "seq" : , - "type" : "response", - "request_seq" : , - "command" : "lookup", - "body" : - "running" : - "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" : , - "type" : "request", - "command" : "backtrace", - "arguments" : { "fromFrame" : - "toFrame" : - "bottom" : - } -} -``` - -The response contains the frame data together with the actual frames returned and the toalt frame count. - -``` -{ "seq" : , - "type" : "response", - "request_seq" : , - "command" : "backtrace", - "body" : { "fromFrame" : - "toFrame" : - "totalFrames" : - "frames" : - } - "running" : - "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" : , - "type" : "request", - "command" : "frame", - "arguments" : { "number" : - } -} -``` - -Response: - -``` -{ "seq" : , - "type" : "response", - "request_seq" : , - "command" : "frame", - "body" : { "index" : , - "receiver" : , - "func" : , - "script" :