Web Apocrypha

Welcome to our first lesson on how to build a web browser!

We presume that you have already read the Introduction and have a Chromium repository set up as well. If you need more help setting up Chromium, here is what we did (when this guide was created the Chromium version was 47.0.2526.73).

$ # with depot tools in the PATH
$ fetch chromium
$ cd src
$ git fetch origin 47.0.2526.73
$ git reset --hard 47.0.2526.73
$ gclient sync --with_branch_heads

Before we jump into the details, let’s clarify some important things.

First of all, we do everything from scratch (creating a git repository, committing patches, etc.) and our changes are attached as a git diff. So you don’t need to type everything by yourself.

You can also check the git repository where you can find and reuse our instructions. In the repository, every branch is a lesson, so you can just checkout one and continue from that point.

Let's start with a local repository to track your progress:

## Change your current directory to chromium/src
$ mkdir sprocket
$ cd sprocket
$ git init

Now we have an empty repository. It is recommended to add some basic files to the repository such as gitignore, license, readme, etc. If you store the diff files in your repository, we suggest to ignore them in the .gitignore file.

The diff file here contains the modifications above.

The following command shows the generic form of applying a diff file:

$ git apply <lesson_file>.diff

If you are done, it is time to make your initial commit. In the sprocket folder execute these commands:

$ git add --all
$ git commit -m “Initial commit”
## if you have an online repository, you can push it or leave it as it is

The Content API is a set of abstract classes which are found in content/public folder. Implementing these classes is the way to use the API. In this project, we follow the style recommendation of the Content API (like the naming conventions of its directory structure: app, browser, renderer, etc).

Our first source file will be a C++ file containing a main function: app/main.cc. The first step is to include the Content API’s main header file.

#include "content/public/app/content_main.h"

Then create the entry point of the application:

int main(int argc, const char** argv) {
  content::ContentMainParams params(NULL);
  // pass through the command line arguments
  params.argc = argc;
  params.argv = argv;
  return content::ContentMain(params);
}

The Content API’s main function is the ContentMain, whose initialization arguments are passed as a structure.

We are ready to build our first browser!

Chromium’s build system is based on gyp and ninja tools. The build files are generated with gyp (Generate Your Project) and ninja is responsible for invoking the generated commands. The gyp file contains a python dictionary with specific build options. You can read more about gyp and ninja by clicking on these two links. The gyp file defines build targets and their dependencies, environmental variables and source files. In order to connect our newly created main file to the rest of Chromium’s build system we have to create a new gyp file (let’s call it sprocket.gyp):

'targets': [
  {
    'target_name': 'sprocket',
    'type': 'executable',
    'dependencies': [
      'sprocket_lib',
    ],
    'sources': [
      'app/main.cc',
    ],
  }
]

It is just a part of the full gyp file, the whole file is available here, or in the repository.

Keep in mind that every new source file which you want to build should be added to your gyp file! The diffs for each lesson always contain the gyp related lines as well.

At this point, you should be able to compile and run our example. The first build may take a longer time, but this time will be reduced by incremental builds later.

$ ./build/gyp_chromium sprocket/sprocket.gyp
$ ninja -C out/Release sprocket
$ ./out/Release/sprocket

When you run the binary, nothing will be displayed on the screen. This is expected since we didn’t create any views in the application. In the next lessons we will show you how to create a view with Content API.

Now we have reached the end of our first lesson, and we hope you enjoyed it. Next time we start working on the application’s window.

Stay tuned for the upcoming lesson!

The Lesson 1 repository can be found here.

Attachments: Init, Main.