Skip to content

Latest commit

 

History

History
223 lines (164 loc) · 9.79 KB

working_with_files.md

File metadata and controls

223 lines (164 loc) · 9.79 KB
Raw

Working With Files

Adding, removing, and renaming files in iOS Chromium needs to follow a specific procedure that will be unfamiliar to engineers coming from other iOS projects. Conceptually, every file is recorded in four locations: the local filesystem, git, the BUILD.gn files, and the XCode projects. Of these, the XCode project is wholly generated from the others.

[TOC]

Overview

Do not use XCode to manipulate files. The XCode project used for iOS Chromium is generated; it's functionally a build artifact. The various BUILD.gn files in Chromium define structure of the XCode project file. Running gclient runhooks causes the project files to be regenerated.

Individual files can have their contents edited within XCode, and all of the regular testing and debugging activities can be done within XCode. It just can't be used to create files, rename files, delete files, or manipulate the project group structure in any way. To do these things, follow the procedures below.

Adding files

To add any files (new headers, .mm or .cc implementation files, asset files of any kind), the following general steps need to happen:

  1. The file needs to exist in the correct directory of the file system for your Chromium checkout. New files need to be created, or assets need to be copied to the right location.

  2. The new files need to be added to git.

  3. The new files need to be added to a target in a BUILD.gn file (usually in the same directory as the newly added file).

  4. The XCode project needs to be regenerated.

For adding new header or implementation files, the following procedure is recommended:

  1. Generate the new files using tools/boilerplate.py. This will generate the correct header guard macros and include the copyright boilerplate.

  2. Add the newly created files using git add.

  3. Edit the BUILD.gn file for the directory where the files were added. For each file, add it to the sources list for the correct source_set in the BUILD.gn file. Note that gn format (which is run as part of git cl format) will take care of alphabetizing the lists along with other formatting, so there's no need to manually do these things. (BUILD.gn files cand be edited directly in XCode, or in another editor such as vi).

  4. Once all of the files have been created, added and all BUILD.gn files have been updated, run gclient runhooks to regenerate all XCode projects.

  5. If XCode is open, it may prompt to "Autocreate Schemes". If so, click on the highlighted "Automatically Create Schemes" button.

In the shell, this procedure would look like this:

// Step 1 -- generate new files.
$ tools/boilerplate.py ios/chrome/browser/some_feature/feature_class.h
$ tools/boilerplate.py ios/chrome/browser/some_feature/feature_class.mm
$ tools/boilerplate.py ios/chrome/browser/some_feature/feature_class_unittest.mm
// Step 2 -- add the new files.
$ git add ios/chrome/browser/some_feature/feature_class*
// Step 3 -- edit the BUILD.gn file in the editor of your choice
$ vi ios/chrome/browser/some_feature/BUILD.gn
// Step 4 -- regenerate the XCode Projects
$ gclient runhooks

To add asset files, follow this procedure:

  1. Copy the asset files to the correct directory, with the correct names (including @2x and @3x suffixes) Note that images are stored in .imageset directories, conventionally inside resources directories for a given UI feature. New directories, if needed, are created in the usual way (mkdir). Note that there is no equivalent of boilerplate.py for images or other asset files.

  2. Create or copy Contents.json files for each new .imageset directory, with the appropriate contents.

  3. Add all image and Contents.json files using git add.

  4. Edit the BUILD.gn file in the containing resources directory, adding imageset entries for each added .imageset directory, and then grouping all assets into a new or existing group() declaration with a public_deps list containing all of the imageset targets.

  5. Regenerate the XCode project with gclient runhooks.

To add Markdown documentation files, the procedure is much simpler. These files are automatically added to the XCode project without BUILD.gn entries, and they have no required boilerplate. So adding new docs is as simple as:

  1. Create a new .md file in the appropriate directory (docs/ios, for example).

  2. git add the file.

The newly added file will be visible in XCode after the next gclient runhooks.

Moving and renaming files.

Renaming a file involves updating the filename in all of the places where it exists: the file names in the filesystem, the file names in git, header guards in files, import declarations in files, listings in BUILD.gn files, and internally in the XCode project. As with adding a file, different tools are used for each of these. Unlike creating a file, which starts with actually adding a file to the filesystem, a rename starts with updating git (via git mv), then using the mass-rename tool to update file contents.

tools/git/mass-rename.py works by looking at uncommitted file moves in git, and then updating all includes, header guards, and BUILD.gn entries to use the new name. It doesn't update some other files, such as Contents.json files for image assets. It also doesn't change any symbols in code, so class and variable names won't be changed.

For many file moves, it will be simpler to use another tool, tools/git/move_source_file.py, which combines git mv and mass-rename in a single action. For example, renaming feature_class to renamed_class would be done like this:

    $ tools/git/move_source_file.py ios/chrome/browser/some_feature/feature_class.h \
        ios/chrome/browser/some_feature/renamed_class.h
    $ tools/git/move_source_file.py ios/chrome/browser/some_feature/feature_class.mm \
        ios/chrome/browser/some_feature/renamed_class.mm

The step-by-step procedure for a rename is:

  1. If there are other uncommitted changes before the move, it's usually cleanest to commit before starting the move.

  2. move_source_file each file that needs to be renamed. This renames the file in both the file system and in git, and in most places where it's used in code.

  3. Run gclient runhooks to update the XCode project. Check that all of the needed name changes have been made (for example, by building all targets). Make any other needed fixes.

  4. If any classes or other symbols need to be renamed (remember that the name of the primary interface in each file must match the file name), make those changes. Find-and-replace tools like tools/git/mffr.py or XCode's Find/Replace can help here, but there are no compiler-aware tools that can do a "smart" rename.

  5. Commit all changes (git commit -a -m <your comment>).

A move—where a file is moved to a different directory—is in most respects performed using the same steps as a rename. However, while mass-rename.py (and thus move_source_file.py) will update existing file names in BUILD.gn files, it won't move entries from one BUILD.gn file to another. To move files to a different directory, the preceding procedure is used, but between steps 2 and 3 (after moving the files, but before regenerating the XCode project), the old filenames will need to be removed from the BUILD.gn files in the old directories and added to the BUILD.gn files in the new directories.

Also note that while move_source_file must be used separately for each file being renamed within a directory, it (just like git mv) can move multiple files without renaming to a new directory in a single command:

$ tools/git/mass-rename.py ios/chrome/browser/some_feature/feature_class.* \
    ios/chrome/browser/some_feature/feature_class_unittest.mm \
    ios/chrome/browser/other_feature/

Deleting files.

Deleting files follows the same patterns as adding and moving files. As with a file move, it's best to begin with deleting the files from git.

Typically, before actually removing a file, first all usage of the interface(s) in the file(s) will be removed, and the file will no longer be #imported anywhere.

Step-by step:

  1. git rm the files you want to remove. This will also remove the files from the filesystem.

  2. Manually remove the BUILD.gn entries for the files.

  3. Regenerate the XCode project (with gclient runhooks) to remove the files from XCode.

Finally.

It's easy to miss some uses of a file that was renamed or deleted, and fixing compilation errors discovered in the commit queue means another commit-upload-dry run cycle (at least). To minimize this, after any change that adds, renames, moves, or deletes files, be sure to take the following steps:

  1. git cl format to update the formatting of all files.

  2. gn check to make sure that any new or moved files follow the dependency rules (for example: gn check -C out/Debug-iphonesimulator/).

  3. Build all targets, to make sure that everything has been added, changed, or removed correctly. This can be done by selecting the "All" target in XCode and building (⌘-B), or from the command line (for example, autoninja -C out/Debug-iphonesimulator/).

Changes that involve adding or deleting more than a few files, and most renames of any size, should be in a single CL with no other changes, for ease of reviewing and (if necessary) reverting or cherry-picking.

Recovering from accidental XCode Project usage.

If files are accidentally added, renamed, or moved through XCode, other settings in the XCode project may be changed that will introduce strange local build failures. In this case, take the following steps to recover.

  1. Quit XCode.

  2. Delete all generated XCode projects and associated files: rm -rf out/build.

  3. Regenerate all XCode projects: gclient runhooks.