Improve the documentation / tooling for dependency by explaining the consequence of static / dynamic / mixed framework

[tychota]

First of all, the existing page (Dependencies · Projects · Develop · Guides · Tuist) is awesome and there is a lot of interesting content.

I realize:

• it is a huge amount of work (thank you for doing what we have now)
• it is complex topic anyway : dependency on iOS are a mess imo
• it is not well known

I think it is one of the major blocking point though when going to Tuist.
I migrated a existing big XCode project to Tuist and spend probably 70% of the time messing with deps.

I think there is actually 3 main topics an they are a bit mixed up in actual tuist documentation.

Current topics in doc

If I look at existing docs, here are the topic.
They can be separated / reworked to make them clearer.

1) How XCode deps works

• static framework
• dynamic framewok
• lipo for xcframework

2) Why tuist chose to do

The global vision, aka:

• explicit and static graph
• debugable graph
• less cascading effect

3) Some troubleshouting

• Firebase
• ObjC

What I think is missing / can be improve

Tuist graph

Tuist graph is awesome. Because it give information about the reality.

But there is little to no doc about it now. And I think we can improve it.

Let’s take an example.

• It would be nice to have a legend in documentation, at least something like this.
  

  

• It would be nice to have way of grouping stuff that belong to same SPM target
  

  

• It would be nice to have a way to distinguish external framework from targets. Eg bold border on internal stuff.

A flow chart

I think it is currently hard to implement and debug it : there is quite a few decison to take (staic / dynamic), framework that depends on current env (spm / carthage/ pods). And there are exceptions (Google libs).

We don’t have much of a flow chart of the decision making.

It would be nice to have a tutorial like section explaining how to setup think, including usage of tuist graph.

Eg:

• you want to have static in prod, dynamic in dev => Goal 1
• how to setup modular target (eg µFramework) to meet Goal 1
• how to setup dependencies to meet Goal 1
• how to use tuist graph to debug the graph and adapt from the result of tuist graph : see next section

Some use cases

Some impact are not really clear.

It would be nice if we help user understand:

• what the impact of having dynamic framework depends on static : good and bad
• what the impact of having static framework depends on dynamic : good and bad
• how to manage the exception (firebase want static framework)

[pepicrft]

Hi @tychota,

I couldn’t agree more with your points on this topic.

More and more, it’s becoming clear that we should document the implications of the following:

• Linking type: static or dynamic
• Product type: library or frameworks
• Precompiled or as sources
• Programming language: Swift or Objective-C

As well as common scenarios that people encounter. You might have noticed that SPM has the “automatic” option, which means they’ll do their best to make the graph compile. However, this doesn’t span to Xcode targets. This poses the question of “should Tuist have that option”?

let target = Target(product: .automatic) // Or .module

However, I’m not sure we can reliably make a good decision there. And if we can’t, I’m hesitant to add that feature because we’ll suddenly have many bugs to be distracted by. I’d instead provide first-class documentation, as you suggested, and guide developers through that decision-making. I think a solution to this should be provided at a lower level. For example, Apple introduced that type in Xcode projects, which we’d surface through the Tuist DSL.

Would you be interested in contributing this documentation?

Tuist graph documentation

Yes! We need to improve it following your suggestions. We are a bit overloaded with some other work, but if you feel like it, I can give you pointers to contribute those improvements to the documentation. We might be able to leverage some features from the dot language to make graphs easy to parse visually.

Flow chart

We can try to come up with one. I think this would be insanely valuable not only for developers using Tuist, but also for Xcode developers.

Impact of some decisions

100%, we need to include this one too. The CLI outputs something along the lines of, “there are side effects”, but it’s impossible as a user to know what a side effect means.

---

I created an issue to turn this into something actionable. We also have plans to enhance the tuist graph command to provide an interactive web-based experience where the developer can filter, re-arrange, and zoom-in/out as needed. Tools like Nx from the JavaScript ecosystem have a similar command and their graph command experience is way ahead of us.

Thanks a lot @tychota for your candid feedback