I started my v8 build journey on the following page, which was short enough and made me think that I would be done within a couple of hours:
The reality turned out to be a couple of evenings that I had to spend troubleshooting shortcomings in the Google's build process and looking for ways to configure the build system to produce what I need.
1. Download Google's depot_tools from this location:
, and unzip the archive into any directory. I will use C:\projects\v8\depot_tools\ throughout this post.
2. Add the depot_tools location to the system path. You can do it just within the command line prompt where you are building the v8, as you will not need it after you are done with the build, so no need to litter the system path with this location.
3. Some depot_tools scripts invoke Python without the file extension (i.e. python) and some use the full file name (i.e. python.exe), so the first form one finds python.bat in C:\projects\v8\depot_tools\, while the second results in an error because there is no python.exe in depot_tools. Add this directory to the path, unless you are using some other version of Python that is compatible with the v8 build process:
4. Google build process is intended for Google employees and pulls many dependencies from Google's internal repositories, which are not accessible from outside (e.g. the build is supposed to pull and install the Visual Studio from Google's internal repository). Prevent this by setting this environment variable:
Indicate the version of Visual Studio you have by setting this environment variable:
Note that this variable seems to be a holdover from the GYP build, so it's possible that it could change in the future to reflect the GN build.
5. Google build process completely bypasses all conventions of how to obtain Windows SDK files and reaches into Windows SDK directories for the files they need, such as dbghelp.dll, based on the directory structure of the specific Windows SDK version. Consequently, none of the official Windows SDK versions shipped with Visual Studio 2017 will work because Microsoft changes their internal directory structure from time to time and the v8 build will fail because dbghelp.dll and other files will not be found in new Windows SDK installations. The only way current v8 build works is that if you install an archived version of the Windows SDK from Microsoft's archives:
Hopefully this archive link will work for a while until Google figures out how to reference Windows development files in a portable way.
6. When installing Visual Studio 2017, make sure to include ATL MFC component. Check this section for additional Visual Studio dependencies:
7. Configure gclient to connect to the v8 repository. Google documentation says that running gclient on its own will do that, but in the setup on the moment of this writing gclient reported an error that I'm missing some arguments when I did that, so I explicitly supplied the v8 repository URL:
gclient config https://github.com/v8/v8.git
Note that I used the Github repository, which is cloned from the Chrome repository just to maintain the v8. This step creates a file called .gclient in the current directory.
8. Now we can grab the v8 source code with this command:
This will take a while and will create a v8 directory in the current directory.
9. Follow up with this command to make sure the source is up-to-date:
10. Now we are ready to work with the v8 source code. Make sure the current command prompt environment is initialized for x64 VC++ builds.
Note that vcvarsall.bat isn't on the path, so you will need to prefix the batch file with the full path leading to the file for your edition of Visual Studio (e.g. in the Community edition this batch file is in C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\).
11. Change to the v8 directory:
12. Use git to check out the revision of the v8 engine you would like to build. As a general rule, the v8 engine revision should be the one that is released with a stable Chrome release, which you can look up on this page:
Find a stable win64 Chrome release and scroll to the right to see the corresponding v8 release. For example, a stable win64 Chrome release on the moment of this writing is 63.0.3239.132 and the corresponding v8 version is 6.3.292.49. Google tags v8 revisions with the version, so you can check out this version to make a build:
git checkout 6.3.292.49
An alternative way to figure out the v8 revision that corresponds to a stable Chrome release is described on this page and seems to be based on how Google creates release branches:
However, it's always a good idea to make a build off a tag rather than a branch because the latter is a moving target in general, but may work in some branch setups, which seems to be the case here.
13. Generate build scripts for debug and release x64 builds:
python tools/dev/v8gen.py x64.release python tools/dev/v8gen.py x64.debug
You will need both, debug and release builds, even if you don't intend to dive into Google's code.
Note that 32-bit builds will not work on a true 32-bit machine because Google assumes that 32-bit stuff is located in WOW64 and fails to find them in their original locations on a 32-bit machine.
14. Surprisingly, Google builds static libraries by default. Not only that, but they also don't pack all of v8 into one or two libraries, but instead advise people to link against object files. That is, if you just attempt to link against the two libraries generated by default, which are v8_libbase.lib and v8_libplatform.lib, you will end up with a bunch of undefined symbols during linking.
A more usable approach is to build the v8 as a DLL and you will need to run these two commands to tell GN to build DLLs:
echo is_component_build = true >> out.gn\x64.release\args.gn echo is_component_build = true >> out.gn\x64.debug\args.gn
You can also manually add this line into both configuration files.
15. Now you can build the v8 with this command, one platform at a time:
ninja -C out.gn/x64.release
16. Once the build is finished, run these tests for the last build. Note that this command won't work against an arbitrary build.
python tools\run-tests.py --gn
One test failed in my setup, but the failure was in the wrong currency symbol and wasn't that important for me to troubleshoot any further, so I left it alone.
17. Repeat the last two steps for x64.debug.
18. The last two steps produce a set of import libraries and DLLs that you can use for your projects. Specifically, link against these libraries:
v8.dll.lib v8_libbase.dll.lib v8_libplatform.dll.lib icui18n.dll.lib icuuc.dll.lib
You will need to package DLLs corresponding to these libraries with your application.
One important note is that Google packs all Microsoft libraries in the v8 build, such as those that come with Windows (e.g. api-ms-win-crt-runtime-l1-1-0.dll), as well as VC runtime (e.g. vcruntime140.dll) and Universal C runtime (e.g. ucrtbase.dll). Tempting as it is, avoid shipping these libraries with your application unless you plan to ship security updates released for these libraries by Microsoft. Universal C runtime is shipped with Windows Updates and VC++ runtime should be installed using the corresponding version of the VC++ redistributable package.
19. If you intend to copy v8 samples into your own project to experiment with v8 constructs, keep in mind that all of the samples incorrectly include v8 headers as #include <include/v8.h>, so these includes will not be found if you add the v8/include directory into your project's include search path. You will need to change them to #include <v8.h> to make it work.
20. One more problem I ran into after successfully building a test v8 application in my own project was crashing when trying to allocate a v8 context with the v8::Isolate::New call and the error was just a heap check failure. It turns out that one needs to copy natives_blob.bin and snapshot_blob.bin files from the v8 build directory into whatever directory is supplied to the v8::V8::InitializeExternalStartupData call.
At this point you should be able to build and run your own code using v8 libraries.