Workflow: Merging a DevTools Submodule into its Parent

This document outlines the process for merging a submodule (e.g., panels/timeline/extensions) into its parent module (e.g., panels/timeline) within the DevTools build system. The goal is to simplify the build configuration by consolidating BUILD.gn files while keeping the original source file directory structure.

Prerequisites

You will need the following information:

• Parent Module Path: The path to the directory containing the primary module.
• Child Module Path: The path to the directory of the submodule to be merged.

Workflow Steps

1. Analyze Build Configurations

Read the contents of the BUILD.gn file from both the child module and the parent module. Identify the following from the child's BUILD.gn:

• The list of sources in the devtools_module.
• The list of ts_deps (and non-TypeScript deps) in the devtools_module.
• The entrypoint for the devtools_entrypoint("bundle").

2. Modify the Parent BUILD.gn

Edit the BUILD.gn file in the parent module's directory to incorporate the child module's configuration.

1. Add Child's Sources: Append the list of sources from the child's devtools_module to the parent's sources list. Remember to maintain the relative path from the parent's directory (e.g., extensions/ExtensionUI.ts).
2. Merge Dependencies: Add the ts_deps from the child's devtools_module to the parent's ts_deps list (and merge any non-TypeScript deps). Remove any duplicate entries.
3. Remove Child Bundle Dependency: Delete the dependency on the child's bundle from the parent's ts_deps list (e.g., remove ./extensions:bundle).

3. Delete the Child BUILD.gn

Once the parent BUILD.gn is updated and contains all the necessary information, the child's BUILD.gn is no longer needed. Delete it.

bash
rm <child_module_path>/BUILD.gn

4. Update devtools_grd_files.gni

The global .gni file that lists all resources needs to be updated to reflect that the child module is no longer a separate, bundled entrypoint.

1. Locate and Read the File: Open config/gni/devtools_grd_files.gni.
2. Remove Bundled Source: Find and remove the line for the child's bundled JavaScript file from the grd_files_bundled_sources list. This path usually corresponds to the child's entrypoint.
3. Add Unbundled Sources: Add the paths to all of the child's original TypeScript source files (.ts) to the grd_files_unbundled_sources list.

Example: Merging panels/timeline/extensions into panels/timeline

• Parent Module: panels/timeline
• Child Module: panels/timeline/extensions

1. panels/timeline/BUILD.gn Modification

Before:

gni
devtools_module("timeline") {
  sources = [
    ...
    "UIDevtoolsUtils.ts",
  ]

  ts_deps = [
    ...
    "./components:bundle",
    "./extensions:bundle",
    "./overlays:bundle",
    ...
  ]
}

After:

gni
devtools_module("timeline") {
  sources = [
    ...
    "UIDevtoolsUtils.ts",
    "extensions/ExtensionUI.ts", # Added from child
  ]

  ts_deps = [
    ...
    "./components:bundle",
    # "./extensions:bundle", # Removed
    "./overlays:bundle",
    ...
    # Dependencies from extensions/BUILD.gn are merged here
    "../../../ui/components/helpers:bundle",
    "../../../ui/components/render_coordinator:bundle",
    "../../../ui/legacy:bundle",
  ]
}

2. panels/timeline/extensions/BUILD.gn Deletion

bash
rm front_end/panels/timeline/extensions/BUILD.gn

3. config/gni/devtools_grd_files.gni Modification

Before:

gni
grd_files_bundled_sources = [
  ...
  "front_end/panels/timeline/components/components.js",
  "front_end/panels/timeline/extensions/extensions.js",
  "front_end/panels/timeline/overlays/overlays.js",
  ...
]

grd_files_unbundled_sources = [
  ...
  "front_end/panels/timeline/extensions/ExtensionUI.ts", # This might not have been present before
  ...
]

After:

gni
grd_files_bundled_sources = [
  ...
  "front_end/panels/timeline/components/components.js",
  # "front_end/panels/timeline/extensions/extensions.js", # Removed
  "front_end/panels/timeline/overlays/overlays.js",
  ...
]

grd_files_unbundled_sources = [
  ...
  "front_end/panels/timeline/extensions/extensions.ts", # Added
  "front_end/panels/timeline/extensions/ExtensionUI.ts",   # Added
  ...
]

Removing Barrel Files

After merging modules, you may still have remaining barrel files (e.g. index.ts or extensions.ts that just re-export other files). These should be removed to simplify the module structure.

Manually updating all imports that rely on these barrels can be tedious and error-prone. The tool unbarrelify can automate this process. It analyzes your codebase and replaces imports from barrel files with direct imports from the source files.

Usage: Follow the instructions in the unbarrelify repository to install and run the tool on your project. This is highly recommended to complete the refactoring process efficiently.