WebKit has several different build systems; which is used depends on the platform and port. When adding files used by more than one port, its tricky to remember all the different build system files that the file must be added. This page documents how to do so, and common gotchas.

How to add a file

Adding Source Files (.cpp/.mm)

Due to the size of the WebKit project it uses a system called unified sources to build files. This means that we pass multiple source files to the compiler to treat as a single source file. The bundling of source files is done automatically in the build system. Sources are passed to the bundling code via source list files and a particular port might use more than one source list file. e.g. The iOS port uses the Sources.txt, SourcesCocoa.txt, and the SourcesIOS.txt files. Both the Xcode and CMake build systems use unified sources but the way the sources are bundled should be the same across both build systems.

Choosing the right source list file depends on what ports the file is built on. If the source should be compiled on every port then add it to Sources.txt. If it's on Mac and iOS add it to SourcesCocoa.txt. Otherwise, add it to the appropriate Sources<Port>.txt file for that port.

The source list files also support conditionally adding sources based on feature flags. If a source file, say webfeature/source.cpp, is specific to a particular feature you can do:

#if ENABLE_WEB_FEATURE

webfeature/source.cpp

#endif

and webfeature/source.cpp will only be compiled if "web feature" is enabled.

Xcode (for Mac, iOS)

Xcode-based builds use Xcode projects named after the respective WebKit components. For example, the Xcode project directory for WebCore is at Source/WebCore/WebCore.xcproj/ and the actual project file in called project.pbxproj. To add a file, you'll need to open the appropriate project in Xcode.

Adding a directory

Usually, file system directories are mapped one-to-one to Xcode project groups (which have folder icons). To add a directory, right-click in the navigation sidebar and "Add Group". Name and alphabetize the group, and then open the item details sidebar by selecting the group. If the group corresponds to a filesystem directory, ensure that location is set to "Relative to Group", and just below, select the directory. (By doing this, Xcode knows to look in the filesystem directory when adding new files to the group.)

Adding a file

Find the group that corresponds to the file's directory, then right-click and select "Add Files to ProjectName..." and select the files in the file chooser dialog. Ensure that the file is added to correct target. The correct target is almost always the framework named after the project, not the "All" target. Lastly, alphabetize the file within its group in the navigation sidebar.

If adding a header file that should be accessible from other frameworks (say, using a WebCore framework from WebKit2), then you must alter the file's target membership from "Project" to "Private" in the "Target Membership" details sidebar, using the drop-down next to the framework. If using headers from JavaScriptCore inside WebCore, you must also add a forwarding header in Source/WebCore/ForwardingHeaders in the appropriate mirrored directory structure.

It is important to make sure that any source file added is not compiled by Xcode if it is in a source file list. If this happens it's likely that there will be an error in the linker that complains about duplicate symbols.

Adding code generators / generated files

Aside from adding the build dependencies to DerivedSources.make (which is used by all ports), you may need to do the following:

• If the code generator from one framework is used by another, you will need to add it to the Private Headers group. For non-header files, temporarily set the file type to C Header, change the header group to Private, and then change back to the correct file type.
• If the rules added to DerivedSources.make rely on environment variables, you need to set those in make-generated-sources.sh.

CMake (EFL, GTK, Win, Mac)

Find the relevant CMakeLists.txt file in the project directory (WebCore, WebKit2, DumpRenderTree, etc). Then, add entries to various lists in the files depending on what is being added. Platform-specific rules and dependencies are located in files like PlatformGTK.cmake and PlatformEFL.cmake.

Adding a directory

• If the directory contains header or implementation files, add it to Project_INCLUDE_DIRECTORIES.
• If the directory contains IDL files, add it to Project_IDL_INCLUDES.
• If the directory has headers used outside the current project (i.e., a WebCore directory's headers are used by WebKit2), then you must add the referenced directory to referencing project's CMakeLists.txt (e.g., WebKit2).

Adding a file

• If it's an IDL file, add to the section Project_IDL_FILES.
• If it's a new Inspector domain, add to Project_INSPECTOR_DOMAINS.
• If it's a CPP file, add it to Project_SOURCES.
• If the file depends on a feature flag, then wrap it in a conditional that appends extra values to the main lists if the feature is enabled. See existing CMakeLists.txt for examples of how to do this.

Adding code generators / generated files

You'll need to add a custom command, and append the generated files to Project_SOURCES or some other list. This adds the generated file as a build dependency, and the custom rule tells CMake how to derive the generated files. See existing files for examples.

How Source Files are bundled.

TODO - Be more specific about how this works

It's mostly based on the directory of the source file. Although, there is also a limit of 8 sources per bundle to provide a balance between incremental and clean builds

Tips

TODO - feel free to add your hard-won lessons here.