Epic: Incremental generation mode

[brentleyjones]

This issue doesn't include every PR that went into implementing incremental generation mode. It's primary purpose is to track high level changes on the way to completion of the feature.

What is it/why should I use it?

Incremental generation mode is a new way for rules_xcodeproj to generate your project. Unlike the Build Mode (BwB or BwX), this should only really affect the process by which rules_xcodeproj takes to generate the project, not how the project itself behaves (with some small caveats). Here are some of the benefits of using incremental generation mode over the current (a.k.a "legacy") generation mode:

• Much faster generation. Numbers from a large example project:
  • Clean
    • Analysis: 12% faster (62s vs 71s)
    • Execution: 41% faster (72s vs 123s)
  • Minimal incremental (add file to a top-level target)
    • Analysis: 36% faster (13s vs 21s)
    • Execution: 93% faster (8.5s vs 123s)
• Lower Starlark memory usage (I need to do a little more work to get bigger gains)
  • Currently estimated to be about 33% lower
• Improved target consolidation and target merging
  • Some targets can now consolidate better
  • Libraries can merge into multiple top-level targets
  • Mixed-language targets merge better
• Improved indexing
  • All Swift compiler flags are now in the project, working around more SourceKit issues
• Improved debugging
• Improved handling of extra files (mainly around target focusing)
• Improved Xcode Previews support
• (for maintainers:) Vastly improved maintainability (docs, tests, code structure, etc.)

Early access

You can try out incremental generation mode before everything lands by doing the following:

• Check out the wip/incremental-generation-mode branch
• Create a release archive
• Depend on that release archive with archive_override (Bzlmod) or http_archive (WORKSPACE)
  • Be sure to set the hash correctly, to pick up changes if you upgrade to a newer version
  • I highly recommend using this method, instead of pointing to a source archive or git_repository, because incremental generation mode uses many generators, and your initial generation time can be a lot slower without using a release archive
• Use xcodeproj.generation_mode = "incremental"
• (Optionally) use xcodeproj.xcschemes (you need to use this instead ofxcodeproj.schemes)

The //tools:xcodeproj target shows an example.

Progress

pbxproj_prefix

• Add PBXProject prefix PBXProj partial generator #2155

files_and_groups

• Add files_and_groups generator #2243

pbxtargetdependencies

• Add pbxproject_targets generator #2351

import_indexstores

• Convert import_indexstores.sh into a Swift binary #2671
• Allow remapping indexstores to multiple target names #2680

xcschemes

• Add XCScheme library #2578
• Add xcschemes generator #2678
  • Write more tests for xcschemes generator #2814
• Add xcschemes Starlark integration #2686

target_build_settings

• Add TargetSwiftDebugSettings to PBXProj #2708
• Add target_build_settings generator #2704
  • Write more tests for target_build_settings generator #2815
• Add target_build_settings Starlark integreation #2737

swift_debug_settings

• Add swift_debug_settings generator #2707
  • Write more tests for swift_debug_settings generator #2816
• Add swift_debug_settings Starlark integration #2738

pbxnativetargets

• Add pbxnativetargets generator #2712
  • Write more tests for pbxnativetargets generator #2817
• Add pbxnativetargets Starlark integration #2800
  • Write tests for pbxproj_partials.write_targets #2818

.xcfilelists

• Add pbxproj_partials.write_generated_xcfilelist #2801
  • Write tests for pbxproj_partials.write_generated_xcfilelist #2819

project.pbxproj

• Add pbxproj_partials.write_project_pbxproj #2811
  • Write tests for pbxproj_partials.write_project_pbxproj #2820

Other Starlark

• Add incremental generation mode #2813
  • Write tests for other incremental generation Starlark integration #2821

[brentleyjones]

Deferred some tests to non-blocking issues.