Output Option: NumberOfFiles

[Iron-Ham]

Use case

Currently, we output one file per operation or fragment definition. However, we've found that we can improve our overall compile time by limiting the number of output files in codebases with many generated files.

For example, in our app, we previously had a whopping 5,807 generated files. By reducing it such that we only had under 1000 files generated in total (leaving the files generated under Schema/ alone) per supported GraphQL schema, that we were able to isolate a 45% reduction in the compile time for our GraphQL targets.

While we can script the outputs into a given set of bucketed files, this seems like a universally useful argument for ApolloCodegenConfiguration.OutputOptions or ApolloCodegenConfiguration.FileOutput, such that we can specify a number of output files for the operations and have operations bucketed by Apollo.

Describe the solution you'd like

Ideally:

ApolloCodegenConfiguration(
  ...
  options: ApolloCodegenConfiguration.OutputOptions(
    selectionOutputFiles: .grouped(.alphabet) // or .standard, .grouped(.numerical(10))
  )
)

[AnthonyMDev]

That's really interesting! I didn't know that this would affect compile times significantly!

If you recall, Apollo iOS 0.x created a single generated API.swift file. That was one massive file, and it was actually causing issues with crashing/hanging Xcode when you tried to view it.

I do like the concept of this feature, but I'm not sure what the right way to have this behave is. Grouping them into files alphabetically or by a number of operations per file would likely result in some files being much larger than others. I'm wondering if it would be better to have a limit on the number of lines per file and group them that way.

The idea of this really irritates the part of my brain that is obsessed with clean project organization. Not having a file with the name of each operation/fragment feels bad to me... But I guess operations are still equally easy to find by symbol name instead of file name?

[Iron-Ham]

@AnthonyMDev totally, I'm right there with you. This was an unintended side effect on our part; our goal was to prevent the addition/deletion of a new file to prevent our xcodegen project generation from invalidating the cache. The moment that we measured it I realized what had happened: we were bottlenecking during the batch compilation stage. The performance characteristics of this are alluded to in the Apple compiler performance docs. Primarily, this is around primary-file compilation modes (i.e., whole-module-optimization turned off, meaning this conversation is largely only relevant in DEBUG configurations). To quote relevant bits from that doc:

In the batch sub-mode, it runs one frontend job per CPU, identifying an equal-sized "batch" of the module's files as primaries.
Running [...] in batch mode, and on a system with 4 CPUs will run 4 frontend subprocesses, each of which will parse all 100 inputs (for a total of 400 parses), and then each subprocess will (in parallel) compile the definitions of 25 primary files (one quarter of the module in each process).

That's assuming you're only building a single module, but the build system queues these jobs based on the results of dependency resolution of your project. Apple Silicon devices (ignoring the Ultra-series) range from 4-12 P-cores (4/8/12), and ARM does not support Intel-style hyperthreading – meaning that the P-core count is the total number of "CPUs" that will be used for this.

As the number of files scales out rapidly, performance degrades despite compiling the same code. Similarly: moving down to a single file will also tank performance. There's a sweet spot – and what that is I'll leave to people trying to hyper-optimize. What I can say is that at 5800 files we were experiencing severe performance degradation on M1 Max chips relative to ~900 files (even when it's all just the same content).

Back to the topic at hand: I suppose the answer of how these are grouped depends on the outcomes/goals in mind:

• Are we optimizing such that Xcode won't lock up due to file length? That seems dependent on a number of factors (individual machine performance, maybe Xcode version, maybe even the symbol resolution inherent to a given schema?)
• Are we optimizing for compile time? That also depends on a number of factors, as discussed above.
• Are we optimizing for normalization by number of definitions in a given file / lines of code / something else?
• etc

I think each of those could be defined as separate modes, but there are some that could be implemented initially with others that can follow later?

enum FileOutputMode {
  case standard // Each operation gets its own file
  case alphabet // A,B,C,
  case alphabetBucketed // Arbitrary but something like `["AB", "C", "DE", "FGHI", "JKLMNO", "P", "QR", "ST", "UVWXYZ"]` – useful for projects with uneven bucketing? Could even be user defined, but assumes that users will provide ALL valid buckets… 
  case numericCount(number: Int)
  case evenLinesOfCodeCount // Could take a number?
  case evenDefinitionCount // Could take a number?
  case somethingElse // ?
}

Of these, I think just the addition of an alphabet mode is a win and represents a clearly defined goal; the rest can be added later or as-needed?

Though we use alphabetBucketed internally, that's largely because we have no operations/fragments that would land in a Y.graphql.swift or Z.graphql.swift (etc) and introduces some risk that we end up creating a file at some point that would invalidate our cache.

[AnthonyMDev]

Very interesting info. Thanks for all the details!

I don't think we're going to prioritize this work any time soon, but I'm open to the addition, so if you want to put a PR up for this, I'd be happy to merge the feature. I think it would be nice to include an option that balances the files based on a max lines of code, but I'm also fine to include an alphabet or alphabetBucketed option. Those are probably a lot easier to implement, so if we wanted to just start there and add others later that's alright too.