Do It Yourself - Chromium Web Application Container

Table of Contents

1 Howto Build a Chromium based HTML5 Hybrid Application from scratch on Ultrabook

This tutorial will walk your through the process of creating a hybrid HTML5/C++ application container.

A hybrid application allows the developer to have more flexibility accessing computer resources that traditionally have been reserved for native code applications. For exapmle, the developer could access a camera, accelerometer or other hardware sensors.

Another advantage to a hybrid application is that the developer can package it and submit in to an application store, such as the Intel AppUp Center. The web runtime that is part of the hybrid application ensures that the developer has a know environment for building HTML5 applications.

The procedure in this tutorial was tested on Windows 7 edition.

1.1 The Chromium  Project

The Chromium Project is an enormous collaboration consisting of many tens of thousands of source code files. The project, of course, was originally founded by Google, but now enjoys contributions from many and varied sources. Consequently, the Chromium Web Platform is on the cutting edge of browser and HTML5 technology. This makes it an ideal candidate from which to build our hybrid application container.

Chromium also has its own source control management tools, called the depot tools. These ease the process of checking out and synchronizating files to the stable or head releases of the repository. The depot tools can manage a repository using either Git or SVN depending on your gclient configuration file. The main tool that we will use during this tutorial is gclient. Let's walk through setting up your environment and then setting up the Chromium depot tools.

For more information please refer to the Chromium Wiki.

1.2 Setting Up Your Build Environment

In order to successfully build the Chromium project, you will need to set up a number of prerequisite software tools, development libraries and several patches. Let's step through each of them.

1.2.1 Install Visual Studio 2010

First you'll need to install Microsoft Visual Studio 2010. According to the Chromium wiki this is the preferred toolchain for building Chromium on Windows. Support for Microsoft Visual Studio 2008 will be deprecated in the near future. The Chromium discussion groups have a few posts on attempting to build with the Mingw32 compiler. However it's not supported by the Chromium Project, and gclient does not create project files for this compiler. Some people also attempt to use Cygwin, and have got it working. However, staying within the preferred toolchain is definitely the path of least resistance.

Microsoft Visual Studio 2010 express can also be used for building the Chromium project. For complete details on this please see the Chromium wiki. There aren't many deviations from what was tested in this article but there are few.

*info*Download and install a copy of Microsoft Visual Studio from Microsoft's website or through the Microsoft Developer Network. Also you can download the Microsoft Visual C++ 2010 Express for free.*endinfo*

1.2.2 Install Microsoft Windows SDK for Windows 7 and .NET Framework 4

Next you'll need to install the Microsoft Windows SDK for Windows 7 and .NET Framework 4. This SDK contains compilers, header files and libraries that you'll need to compile the Chromium Project, and most any Win32 application.

*info*Download and install the Microsoft Windows SDK for Windows 7 and .NET Framework 4.*endinfo*

1.2.3 Install June 2010 DirectX SDK

Next you need to install the DirectX Software Development Kit. DirectX is a build dependency of the Chromium Project and is needed to support accelerated graphics which are often used in HTML5 application.

1.2.4 Install VS2010 SP1

Even though it's not the second Tuesday of the month (patch Tuesday), the you will still need a patch. Before Chromium can be compiled, it's a good idea to install Visual Studio 2010's Service Patch one.

1.2.5 Install Your Preferred Version Control System (Git or SVN)

Since the Chromium Project is available either by Git or SVN, the developer has some flexibility to choose the tools that integrate best into his or her workflow. For the purposes of this article, all we need to do is to synchronize with the repository. So either Git or SVN will do just fine.

  • Installing Git

    Git on Windows has traditionally been difficult and not very well supported. However, the msysgit project has made this project much easier, you can also combine this tool with the TortoiseGit project which provides access to Git from the Windows Explorer context menu.

  • Installing Subversion (SVN)

    If Subversion is your preferred version control system, then the TortoiseSVN is a well-known project that has been around for a number of years. SVN was the original version control system that the Tortoise team integrated into Windows Explorer.

1.2.6 Install Chromium Depot Tools

  • Install with Git
    Lastly, you will need to install the Chromium depot tools. If you've installed msysgit, you can open up the GitBash application, change directories to your preferred installation directory for the depot tools, and type the following.

    terminal $ cd c:/ $ mkdir chromium $ cd chromium $ git clone https://git.Chromium.org/Chromium/tools/depot_tools.git endterminal

    This will make a copy of the depot tools repository to your local computer.

    For detailed information on how to do this you can see the Install Depot Tools Page on the Chromium wiki.

    Lastly, add the depot tools directory to your Windows Path variable.

  • Install Subversion

    If you're using TortoiseSVN an open Windows Explorer to the directory into which you wish to install the depot tools. right-click and select "SVN Checkout". In the "URL of Repository" text field enter the following URL:

    https://src.Chromium.org/viewvc/chrome/trunk/tools/depot_tools/

    This will make a copy of the depot tools directory from the Chromium subversion source repository.

    When you're finished copying the repository, you will need to add it to the directory to the Windows path variable. For example if you downloaded the depot tools to the directory c:\Chromium\depottools, you will need to add the directoryc:\Chromium\depottools\bin to the Windows PATH environmental variable.

  • Put Depot Tools Directory in the PATH

    info*Add the depot tools directory to your the PATH environment variable*endinfo

  • Installing the dependencies for depot tools

    The first time that you run gclient, it will install the dependencies that it needs to run including: git, python and subversion. After the dependencies are finished installing, a list of all the commands that can be used with gclient are printed. these commands are very similar to other commands that you may have used in Subversion or Git,such as cleanup, fetch, diff, revert, status, sink and update. image 13

    Now to the depot tools are installed and ready to use we can proceed to configuring them and obtaining a copy of the Chromium source code.

1.3 Download the Chromium Source Code

Before you do a checkout with gclient, it will speed up the process if you first download a tarball of the Chromium source. The Chromiumn Wiki gives this link to a tarball as a starting point.

Even though you download a zip archive of the source repository, you should still expect that syncing with the repository will take a long time. If you have an older tarball of the source then go have a nice meal at your favorite restuarant.

1.4 Configure Your Tools in Preparation for Building Chromium

For building Chromium there are a number of configurations that need to be done to ensure that the build runs. First, specify what type of project configuration and make files GYP should generate. Second, we'll create some environment variables and use them to configure our projects include and library paths. Third, we will configure gclient and last we will generate the Chromium project files.

1.4.1 GYP - Generate Your Project

GYP is a Python tool that allows you to specify build configuration information in a Python dictionary. It's platform independent which is a big advantage from a multi-platform project such as Chromium. GYP can generate platforms specific project descriptions and build scripts, including Microsoft Visual Studio Solution files, Xcode project files and GNU make files.

  • Configure GYP before generating the Visual Studio Solution Files
    In order to build on a Windows platform only a very small amount of configuration needs be done. Specify the version of the Windows SDK by setting the 'msbuildtoolset' variable in %USERPROFILE%\.gyp\include.gypi.

    info mkdir $Env:userprofile\.gyp cd $Env:userprofile\.gyp notepad include.gypi endinfo

    Create the file if needed and copy this into it:

    {
      'target_defaults': {
        'msbuild_toolset': 'Windows7.1SDK',
      },
    }
    

1.4.2 Create Windows ENV variables

For the configurations files that we are about to setup, we'll create a couple of environment variables. These act as shorter names to specific directories or as configuration variables.

Create a Windows environmental variable called DXSDKDIR and set it equal to the location of the Direct X SDK. Create a Windows environmental variable called GYPMSVSVERSION and set it equal to '2010'. This will cause GYP to generator files for Microsoft Visual Studio 2010.

1.4.3 Add the libaries to your project paths

Add the include and library paths to the Microsoft.Cpp.Win32.user.props files. It's located in '%LOCALAPPDATA%\Microsoft\MSBuild\v4.0\' directory. On my computer, I'm logged in as the user "intelssg" and the value of %LOCALAPPDATA% is equal to 'c:\Users\intelssg\AppData\Local\'

Under "Include files" add $(DXSDKDIR)\include. Under "Library files" add $(DXSDKDIR)lib\x86.

Be sure you are adding both entries to the front of the lists.

The contents of the file on my Ultrabook looks like this:

<?xml version="1.0" encoding="utf-8"?> <Project DefaultTargets="Build" ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003"> <PropertyGroup> <IncludePath>$(DXSDKDIR)\include;$(IncludePath);$(WDKDIR)\inc\atl71;$(WDKDIR)\inc\mfc42</IncludePath> <LibraryPath>$(DXSDKDIR)\lib\x86;$(LibraryPath);$(WDKDIR)\lib\ATL\i386</LibraryPath> </PropertyGroup> </Project>

1.4.4 Configure gclient

*info*cd %CHROMIUMHOME% $ gclient config http://git.chromium.org/chromium/src.git –git-deps endinfo Configure the gclient by typing 'gclient config'

Open your .gclient file and insert the following text

solutions = [
  { "name"        : "src",
    "url"         : "http://src.chromium.org/svn/trunk/src",
    "deps_file"   : "DEPS",
    "managed"     : True,
    "custom_deps" : {
      "src/third_party/WebKit/LayoutTests": None,
      "src/chrome_frame/tools/test/reference_build/chrome": None,
      "src/chrome/tools/test/reference_build/chrome_mac": None,
      "src/chrome/tools/test/reference_build/chrome_win": None,
      "src/chrome/tools/test/reference_build/chrome_linux": None,
    },
    "safesync_url": "",
  },
] 

For more information about the initial check out using Git see UsingNewGit

1.4.5 Generate the Visual Studio Solution Files

<div class="terminal">gclient runhooks</div>

1.4.6 Update though gclient

You can get the source code to the Chromium project from its repository. Here you will want to read over the Chromium wiki page entitled how to get the code. http://www.Chromium.org/developers/how-tos/get-the-code The Google guide to using Git is an excellent source for learning how to wield Git. It can be found at http://code.google.com/p/Chromium/wiki/UsingNewGit. Create a directory to hold your source code. This example assumes c:\Chromiumtrunk, but other names are fine. Important: Make sure the full directory path has no spaces. In a shell window, execute the following commands: cd c:\Chromiumtrunk gclient config https://src.Chromium.org/chrome/trunk/src svn ls https://src.Chromium.org/chrome and permanently accept the SSL certificate. To download the initial code, update your checkout as described below.

For faster updates gclient can be given a jobs flag liek this.

For a faster update, use the -j / –jobs flag to update multiple repositories in parallel, for example: gclient sync –jobs 12

  • Get a specific version of the Chromium source code.

    For a production application you will probably want to checkout a specific release of Chromium rather than the bleed edge of the repository.

    For example, if you wanted the source for build 5.0.330.0, the following command would be appropriate:

    gclient config https://src.Chromium.org/chrome/releases/5.0.330.0

1.5 Compile Chromium

Open the chrome/chrome.sln solution file in Visual Studio and build the solution. According to the Chromium Wiki: Build Instructions for Windows, "this can take from 10 minutes to 2 hours. More likely 1 hour." However, on my laptop which only has 6GB of RAM and not the recommended 8GB minimum, it took the better part of the day. I started the build at the end of the day and came back to it the following day.

This will build the entire Chromium source tree, including all of the browser tests. If you'd like to learn more about speeding up the build then see Accelerating the Build on the Chromium Wiki: Build Instructions for Windows.

1.5.1 The Content Shell

The Chromium Content module is located src\content directory of the Chromium project, and it contains all the functionality to render a page using a multi-process sandboxed browser. This includes the features of the web platform, HTML5, JavaScript, CSS and GPU acceleration.

The Chromium Content module exists to isolate developers from in the inner workings for page rendering, and to build the Content API that is the preferred way that developers can access content functionality. The Content module should rely completely on the Content API and be separate from other parts of the system and other API calls.

The Content Shell is a minimal application that embeds the content module to render web pages. This also means that developer looking to embedded Chromium can begin with the Content module as use the Content Shell application as a guide for their own embedding projects.

For more information about the Chromium Content Module or the Content API, you can visit http://www.Chromium.org/developers/content-module and http://www.Chromium.org/developers/content-module/content-api

1.5.2 Modifications to Chromium

Your first task will be to create a directory that hosts the starting point of your HTML5 application.

In the directory, %CHROMIUMROOT%\src\content\shell open "shellbrowsermainparts.cc" and go to line 32 in the GetStartupURL() functions. Change the startup URL from "http://www.google.com/" to "///__app/index.html", or whatever you like. This will allow you to create a directory named "_app" (or what you like) in the same directory as the contentshell.exe that contains an entry point for your HTML5 application.

Next, we'll comment out the browser chrome (menus, buttons, toolbars, etc …) so that the contentshell.exe is nothing but a blank canvas for you HTML5 application.

In the same directory, %CHROMIUMROOT%\src\content\shell open "shellwin.cc" and go to line 30.

Change: const int kURLBarHeight = 24; const int kURLBarHeight = 0;

Then jump down to line 110 which is:

HWND hwnd;

Begin a multi-line comment.

/* HWND hwnd;

Jump down to line 146, just before the ShowWindow function call.

ShowWindow(window_, SW_SHOW);

and end the comment and set the menu to null

*/
SetMenu(window_, NULL);
ShowWindow(window_, SW_SHOW);

Congratulations, you may now compile.

1.6 Extracting the HTML5 Hybrid Application

Now that you have compiled the contentshell, we need to find the files that are needed to create a standalone HTML5 hybrid application container.

Change directory %CHROMIUMROOT%\src\build\Release

and create a new directory named hybridApp c:\tmp\hybridApp

We will copy the main executable file and it's dependencies from the Chromium release build directory to our newly created, standalone directory.

Copy these files: contentshell.exe - the main application which I renamed hybridApp.exe libEGL.dll libGLESv2.dll contentshell.pak avcodec-54.dll avformat-54.dll avutil-51.dll icudt.dll

1.7 Conclusion

Congratulations, you now have a standalone directory with a HTML5 Hybrid Application Container.

Before we end the article though, it is useful be able to understand what the level of HTML5 compliance is in your new hybrid application environment. #+HTMLCONTAINERCLASS terminal

hybridApp.exe http://html5test.com/ - View the compatibility and HTML5 compliance of the hybrid app container.

Also see Peter Beverloo's list of command line options that you can use when starting Chromium. Just a warning though, most of these swtich apply to both Chromium and the content shell, but not all of them.

Para obtener más información sobre las optimizaciones del compilador, consulte el aviso sobre la optimización.