Add new file to Xcode project

[artemnovichkov]

Context 🕵️‍♀️

I have a clear task: create a new image and add it to Xcode project to root group

What 🌱

I did it with this code:

do {
    let project = try XcodeProj(path: "Test.xcodeproj")
    let reference = "06B7C9B61F9738E100DAB44D"
    let fileReference = PBXFileReference(reference: reference,
                                         sourceTree: .group,
                                         lastKnownFileType: "image.png",
                                         path: "[email protected]")
    project.pbxproj.fileReferences.append(fileReference)
    let group = project.pbxproj.groups.first { $0.name == nil && $0.path == nil }!
    group.children.insert(reference, at: 0)
    try project.write(path: "Test.xcodeproj", override: true)
    print(project)
}
catch {
    print(error)
}

But it looks weird. What reference I should use? What does mean sourceTree and lastKnownFileType? It's too complicate, I want to use something simple like:

project.pbxproj.addFile(atPath: "[email protected]")

Proposal 🎉

What do you think? Should xcproj have APIs for it?

[toshi0383]

I think it should be group.addFiles.
Checkout my library for example.
https://github.com/toshi0383/Pbxproj#add-a-existing-folder-recursively-under-maingroup

[pepicrft]

Hey @artemnovichkov, I see your use case but I've got a few concerns regarding exposing such API:

• Which group do you add the file to?
• Which target? What if you want to add it to multiple targets?

I think if we start supporting such cases we'll most likely end up with a complex API that does a lot of things. I'm thinking if rather than going with such API we can introduce a certain level of abstraction that simplifies things a bit. I think knowing what each of those objects is, and what the properties mean is something the developer needs to know in advance, and xcproj could help with that by improving the documentation of the project and adding some examples.

I'm just sharing my humble opinion, what do you think? Also, what do you think @yonaskolb, @keith and @esttorhe about this?

[esttorhe]

I agree with @pepibumur and with @toshi0383 on this one.
First I think that over simplifying the API could be a bad idea because we'll either end up with a confusing API or a monstruos one that handles a lot of different things instead of one simple thing.

That being said the idea of group.addFiles makes sense to me; although it is important to note that this would still require the consumer of the tool to traverse the project and find the desired group where they want to add a file and then once you have the desired path adding files to it the way that @toshi0383 suggested seems like a nice and clean way to do it.

[artemnovichkov]

I agree with you, guys. As I understand, for this case I should write a wrapper in my project to incapsulate this logic, because it's not a deal of xcproj, right?

[yonaskolb]

I also agree that simply adding extension to the project and the pbxobjects might be detrimental, as things will get complicated fast. But yes, there should definitely be a higher level API that handles this stuff. It can be in a seperate repo, but what about just a seperate module within this one. Some sort of "ProjectBuilder" (name?)

[toshi0383]

How about XCProjFiles?
I think we should stick with XCProj prefix, just to be safe.

[demensdeum]

Agree, this project needs more high level API.
Have to move to objc xcodeditor, because my team does not have time to understand all low-level references thing.

[pepicrft]

Hey @demensdeum I'm very sorry to hear that. We are open to new ideas and proposals. Don't hesitate to open an issue with your concerns and maybe a proposal of how you would like the API of xcproj to be. If it doesn't meet the xcproj's responsibilities we can think about creating a new tool/layer that suits yours and other developers needs.

[ilyapuchka]

Hi guys. I have been working on the same task over last few days and it seems to me like it's one of the basic functionalities that such project should provide, but right now it requires a lot of manual steps.

1. get target
2. create or get existing group (creating group named "Sources/Something" should create two groups) 3. create or get existing file reference (to avoid adding the same file several times)

• if file reference already exists:
  i. check that group does not contain this reference already and then add it
• if file reference does not exists:
  i. create new file reference and add it to project file references
  ii. get sources build phase for the target
  iii. create new build file reference and add it to build build files and to sources build phase
  iv. check that group does not contain this reference already and then add it

If not implemented as a convenience API in this project or any other (honestly I think doing it in another project is an overkill), there might be smaller helper methods which automate these tasks allowing necessary flexibility (like adding file reference as absolute paths or relative to group). I've submitted a PR for that (#213).

Otherwise it will be beneficial for users to have this code at least as an example, along with already existing examples in README, maybe extracted to a separate doc file dedicated to such recipes.

[pepicrft]

Hi @ilyapuchka. I personally think there's no problem in adding these convenience methods to the xcproj API. As you pointed out, having a second project for it would be a bit overkill. My concerns when it comes to adding such API is that:

1. They solve very specific needs. I think we can have a look at the PR you opened and with some feedback from others, we can try to make it as generic as possible so that everyone can benefit from it.
2. It abstracts so much that developers forget about understanding the underlying principles. What is a PBXGroup? What is a PBXBuildFile? This is hard to prevent, and we've seen that in Core Data wrappers where people didn't care much about how Core Data works.

Let's move the discussion to the PR. I like what you suggested about having a separate document where we can document all these recipes.

[demensdeum]

@pepibumur please look at appsquickly/XcodeEditor, I like their API, but their project is for ObjC.

[pepicrft]

Thanks for sharing it @demensdeum, I had no idea about that tool. Which of these convenience methods would you be interested in? If you bring them up we can discuss whether or not they'd be within the scope of the project. You are also welcome to contribute as @ilyapuchka did. We're not against having a convenient API but it needs a thoughtful discussion to prevent the project from assuming too many responsibilities.