Let's simplify example integrations with XcodeGen #188
Description
Swift Package Manager support is around the corner, thanks to @stevenzeck.
With it, we will need to add more Xcode targets to show how to use them. Currently the Test App has four of them, which adds some maintenance load:
I think this also adds confusion for integrators, since the project contains artifacts for a few different types of integration.
Instead, I suggest removing the Xcode project entirely from r2-testapp-swift and instead add one XcodeGen project definition YAML file per integration example.
XcodeGen is a command line tool written in Swift that generates your Xcode project using your folder structure and a project spec. The project spec is a YAML or JSON file that defines your targets, configurations, schemes, custom build settings and many other options.
Pros
- Xcode projects are not Git-friendly and it's frequent to have merge issues. Getting rid of it would solve the problem.
- The Xcode projects generated by XcodeGen would be simpler and a clearer example of the chosen integration type.
- XcodeGen's YAML files are human-readable and in my opinion also a better example on what's needed to integrate Readium than digging into Xcode's build settings.
name: ReadingApp packages: R2Shared: url: https://github.com/readium/r2-shared-swift from: 2.0.0 R2Navigator: path: ./r2-navigator-swift-local-clone targets: ReadingApp: dependencies: - package: R2Shared - package: R2Navigator
Cons
- This requires integrators to install a third-party tool.
- Integrators can always create the project by hand following the YAML file, which should be straightforward even when not familiar with XcodeGen.
- XcodeGen might stop being maintained in the future.
- We can always commit again the generated Xcode projects at some point.
- There are similar alternatives.
- This dependency is only for the test app, and not other Readium 2 modules.
One step further
Not related to XcodeGen, but r2-workspace-swift also brings some maintenance load with its 4 different integration branches.
I suggest archiving this repository and instead adding the submodules directly in r2-testapp-swift, when used for development purposes.
- Simpler for onboarding, there is a single entry-point repo to check out hosting the documentation.
- It better represents the structure of an integrator's reading app, which when using submodules would have them in the app's repo.
- We can commit the submodule changes after each PR, making it much easier to pinpoint regressions using
git bisect. Right nowr2-workspace-swiftis only updated after each release, making it not so useful.- EDIT: To be fair, this is something we could do in
r2-workspace-swifttoo. However, having them inr2-testapp-swiftties any change in the Test App itself to particular commits of the R2 modules.
- EDIT: To be fair, this is something we could do in
- Users are free to ignore (and not checkout) the submodules when using SPM or Carthage with the test app. The only place where it would show is as empty directories on the file system.