Better Know a Virtual Machine - SquirrelFish Edition

I've probably spent more time than I should reading Digg/reddit. While Digg is always thoroughly entertaining, reddit is more thought provoking. One things that comes up often on reddit is something related to compilers. Even when I was taking intro compiler courses, my advisor Michael Franz said every book is pretty outdated or overly complex. The best resource online I could find was people in forums or WikiBooks - Compiler Construction. Both are severely lacking. So to help everyone out there, I'm going to start a new series called "Better Know a Virtual Machine", just like Stephen Colbert's "Better Know a District". This series is also a way for me to learn about VMs and spit out what I learned in my adventures. I'm going to be starting with SquirrelFish Extreme (SFX) since it's so freaking fast. Bravo SquirrelFish team.

In particular, I was recently illuminated to my lack of knowledge about Garbage Collection (GC) and Object Models (OM). I'll be focusing on the general SFX architecture, with specifics about the GC and Objects. To get started, let's see how to build SFX on Windows. The instructions on the WebKit site are only part of the solution and didn't quite work for me. Hopefully this step by step guide on how to build SquirrelFish and ONLY SquirrelFish using Visual Studio 2005 Professional on Windows XP will you save some gray hairs. Here we go:
  1. Download the developer tools following the WebKit Instructions. Install SP1 for Visual Studio 2005 Team Edition even if you have professional. Use the WebKit SP1 link.
  2. When you install cygwin, make sure you add the packages 'curl' and 'unzip'. Also, even if you have cygwin installed, don't skip the cygwin part. I solved a lot of random problems by starting from scratch and using their cygwin distro.
  3. You don't need the Quicktime SDK if you only want to build SquirrelFish.
  4. Checkout the source code following the WebKit instructions. Twiddle thumbs.
  5. Load up cygwin and update the WebKit source code from the trunk using the update-webkit script. You HAVE TO DO THIS, even if you just checked out. Begin whistling.
  6. Unzip the WebKit Support Libraries to {WebKitRoot}/WebKitSupportLibrary.
  7. Add the cygwin '/usr/bin' utilities to your Windows PATH. The cygwin location for these programs is {cygwin installation}/bin.
  8. Create the directory "WebKitOuputDir" in the WebKit directory.
  9. Set the Environmental User (NOT SYSTEM) Variable for the WebKit build result binary location. When I set it to something custom, it totally fubared. Set variable name "WebKitOutputDir" to "{WebKitRoot}\WebKitBuild". All the scripts/visual studio solution assume its there.
  10. Set the Environmental User (NOT SYSTEM) Variable for some WebKit libraries. Set the "WebKitLibrariesDir" to "{WebKitRoot}\WebKitLibraries\win". Make sure you add the win. Boy oh boy did that take a lot of digging to figure out.
  11. Double click the Visual Studio Solution in {WebKitRoot}\JavaScriptCore\JavaScriptCore.vcproj\JavaScriptCore.sln.
  12. We need to add some include libraries for WebKit to build. First stdint.h! Go to tools->Options->Projects and Solutions->VC++ Directories. Change the "Show Directories For" to "Include Files".
  13. Add the following directories. Use the full paths:
    • {WebKitRoot}\WebCore\icu
    • {WebKitRoot}\WebKitSupportLibrary\win\include
    • {WebKitRoot}\WebKitLibraries\win\include
    • {WebKitRoot}\WebKitLibraries\win\include\pthreads
    • {WebKitRoot}\JavaScriptCore\os-win32
  14. Change the "Show Directories For" from "Include Files" to "Library Files". Add the following directories:
    • {WebKitRoot}\WebKitLibraries\win\lib
  15. Pray you don't have any errors, change the build configuration to Release, and push the build button. You can ignore the warning "Variable ${Production} isn't defined".
  16. The result should be in {WebKitRoot}\WebKitBuild\bin\jsc.exe.
  17. ???
  18. PROFIT! You can stop screaming at the monitor now.
*Note: If you have Visual Studio open already and change an environmental variable, reload Visual Studio for the changes to take effect. A lot of these changes are also global settings and may conflict with other VC++ projects you have.

Hopefully everything was built successfully. But alas we are not done. If you run jsc.exe, you may get a nice error complaining that a icuuc36.dll doesn't exist. There are three dlls that are needed to run SquirrelFish. The three .dlls come with the binary release of Safari from Apple, not within the WebKit source. You can either add the Safari installation directory (C:\Program Files\Safari) to your environment PATH or copy the three dlls to another directory and add that directory to your PATH. The three dlls are:
  • icudt36.dll
  • icuuc36.dll
  • pthreadVC2.dll
Once your path is all setup, double click jsc.exe again, and hopefully you'll be in an interactive shell with SquirrelFish.


The Why the **** Won't It Compile Problems:
1) There is no stdint.h, pthreads.h, or unicode/something.h!
Check that the the global VC++ settings (tools->options->Projects and Solutions->VC++ Directories) included these directories in the "include files". path. These directories are not for specific projects, but global Visual Studio VC++ paths. If you're missing:
  • stdint.h -> add {WebKitRoot}\JavaScriptCore\os-win32
  • pthreads.h -> add {WebKitRoot}\WebKitLibraries\win\include\pthreads
  • unicode/something.h -> add {WebKitRoot}\WebCore\icu
  • CoreFoundation -> add {WebKitRoot}\WebKitSupportLibrary\win\include
2) When I try to run jsc.exe, I get the error "Unable to locate Component: the application failed to start because icudt36.dll/icuu36.dll/pthreadVC2.dll was not found. Re-installing the application may fix this problem".
This means that one of these dlls isn't in your PATH. Create a new directory and dump this dll in that directory. Add the newly created directory to your PATH. I did a search on my system and found that the .dll was included with the Safari binary that is with the official Safari release. Or you can just add the whole Safari directory into your PATH.

3) When the project "jsc" is compiling, I get a bunch of linker errors that are something like this: WTF.lib(CollatorICU.obj) : error LNK2001: unresolved external symbol _ul_open_3_2
Out of the blue, it means that the Environmental Variable "WebKitLibrariesDir" wasn't correctly set. Who would've thunk. Check to ensure that this points to the correct location. I need to find out why there is a Visual Studio project called "WTF" :).

4) I get the compilation error complaining about "icuin.dll" missing.
The WebKitLibraries library path isn't added within visual studio. Add the "{WebKitRoot}\WebKitLibraries\win\lib" directory to the VC++ included library path.

5) Visual Studio can't find ArrayPrototype.lut.h or any *.lut.h.
Check that the cygwin bin directory is added to your environmental PATH variable. This is caused since some files are auto generated at the beginning of the compilation process using some cygwin commands. Also make sure that your environmental user variable WebkitOutputDir is {WebKitRoot}/WebKitBuild.

6) The following error occurs when building project jsc: LINK : fatal error LNK1104: cannot open file 'icuin_debug.lib'.
Change the build configuration from "debug_internal" to either debug or release.

7) Should I waste my time trying to build SquirrelFish on Visual Studio 2003/2008?
Sure be my guest! It's not supported and I wasted two days of my life trying to get VS 2008 working. If you can figure out how to do it, please tell me!

* I deleted all of my setup changes from when it first worked and followed these steps. I may have missed something. If so, please let me know and I'll add it.