An iOS super app with billions of users, with 10 years of code changes, have you noticed?

By Dustin Shahidehpour

Planning | Yan Zheng

Facebook for iOS (FBiOS) is arguably Meta’s oldest mobile codebase. Since the app was rewritten in 2012, thousands of engineers have worked on it and shipped it to billions of users, supporting hundreds of engineers iterating on it at a time.

The evolution of FBiOS architecture to where it is today was not intentional. It reflects 10 years of development, driven by technical decisions, stability, and most importantly, user experience required by the growing number of engineers developing the app.

Additional knowledge:

As of 2022, the code base has passed its tenth anniversary, and I would like to explain some of the technical decisions behind this evolution and their historical context.

After years of iteration, the Facebook codebase is different from the typical iOS codebase:

(1) It includes C++, Objective-C(++), and Swift.

(2) It has dozens of dynamically loaded libraries (dylibs), and too many classes to load them all at once into Xcode.

(3) Original usage of the Apple SDK is almost zero - everything is wrapped or replaced by internal abstractions.

(4) The application makes heavy use of code generation, driven by our custom build system, Buck.

(5) If our build system didn’t have a large cache, engineers would have to spend all day waiting for their application to build.

2014: Building our own mobile framework

In 2014, two years into the native rewrite of the Facebook app, the News Feed codebase began to experience reliability issues. At the time, the News Feed data model was backed by Apple’s default framework for managing data models: Core Data. Objects in Core Data were mutable, which was not a good fit for the multi-threaded architecture of the News Feed. To make matters worse, News Feed utilized a bidirectional data flow, which stemmed from its use of Apple’s de facto design pattern for Cocoa apps: Model View Controller.

Ultimately, this design fostered the creation of nondeterministic code where errors were difficult to debug or reproduce. It became clear that this architecture was unsustainable and it was time to rethink.

While considering a new design, one engineer looked into React, Facebook's (open source) UI framework that's very popular in the Javascript community. React's declarative design abstracts the tricky imperative code that caused problems with Feed (on the web) and leverages unidirectional data flow, which makes the code easier to reason about. These characteristics seemed a good fit for the problems facing News Feed: there was no declarative UI in Apple's SDK.

Swift will be released in a few months, and SwiftUI (Apple’s declarative UI framework) will be released before 2019. If NewsFeed wants to have a declarative UI, then the team must build a new UI framework.

Ultimately, that’s what they did.

After spending several months building and migrating the news feed to run on the new declarative UI and new data model, FBiOS performance increased by 50%.

A few months later, they open-sourced ComponentKit, a mobile UI framework based on React. To this day, ComponentKit remains the de facto choice for building native UIs at Facebook. It provides countless performance improvements to apps through view reuse pools, view flattening, and background layout calculations. It also inspired its Android counterparts Litho and SwiftUI.

Ultimately, the choice to replace the UI and data layer with custom infrastructure was a trade-off. In order to achieve a delightful user experience that could be reliably maintained, new employees had to set aside their industry knowledge of Apple APIs and learn custom internal infrastructure.

This wouldn’t be the last time FBiOS had to make decisions about balancing end-user experience with developer experience and speed. As we headed into 2015, the app’s success would spark what we call a feature explosion. This also brought with it a unique set of challenges.

2. 2015: Architecture Inflection Point

By 2015, Meta doubled down on its "mobile first" mantra, and the number of daily contributors to the FBiOS codebase increased dramatically. As more and more products were integrated into the app, its launch time began to decrease, and people began to notice. By the end of 2015, launch performance was so slow (close to 30 seconds!) that it was in danger of being killed by the phone's OS.

After investigation, it became clear that there were many factors that contributed to the slow startup performance. For the sake of brevity, we will focus only on those aspects that have a long-term impact on the application architecture:

(1) As the size of the application grows with each product, the “lead time” of the application is growing at an unbounded rate.

(2) The application’s “module” system provides each product with unregulated access to all of the application’s resources. This leads to a tragedy of the commons as each product launches using its “hooks” to perform computationally expensive operations to quickly navigate to that product.

The changes required to ease and improve launch will fundamentally change the way product engineers write code for FBiOS.

2016: Dylibs and Modularity

According to Apple's wiki on improving release time, many operations must be performed before the app's "main" function is called. Generally, the more code an app has, the longer it takes.

While “pre-main” only contributes a small fraction of 30 seconds to the release process, it’s a particular concern because FBiOS will continue to grow at an unbounded rate as it accumulates new features.

To help mitigate the unbounded growth in application release times, our engineers began moving large amounts of product code into a lazy-loaded container called a dynamic library (dylib). When code is moved into a dynamically loaded library, it does not need to be loaded before the application's main() function.

Initially, the FBiOS dylib structure is as follows:

Two product dylibs are created (FBCamera and NotOnStartup) and a third dylib (FBShared) is used to share code between the different dylibs and the main application's binary.

The dylib solution works well. FBiOS is able to suppress the unbounded growth of app startup time. Over time, most code ends up in dylibs so that startup performance remains fast and is not affected by the constant fluctuations of adding or removing products from the app.

The addition of dylibs triggered a mindset shift in the way Meta product engineers wrote code. With the addition of dylibs, runtime APIs like NSClassFromString() ran the risk of runtime failures because the required class existed in an unloaded dylib. Since many of FBiOS's core abstractions were built on top of iterating through all classes in memory, FBiOS had to rethink how its core systems worked.

In addition to runtime failures, dylibs introduce a new class of linker errors. If code in Facebook (the launch set) references code in a dylib, engineers will see linker errors like the following:

 Undefined symbols for architecture arm64 :
 "_OBJC_CLASS_$_SomeClass" , referenced from :
 objc - class - ref in libFBSomeLibrary - 9032370 .a ( FBSomeFile .mm .o )

To solve this problem, engineers need to wrap their code with a special function that can load the dylib if necessary, such as:

 int main ( ) {
 DoSomething ( context ) ;
 }

 It looks like this:
 int main ( ) {
 FBCallFunctionInDylib (
 NotOnStatupFramework ,
 DoSomething ,
 context
 ) ;
 }

This solution works, but has a lot of weirdness:

(1) Application-specific dylib enumerations are hard-coded into various call sites. All applications of Meta must share a dylib enumeration, and it is the reader's responsibility to determine whether the application in which the code runs uses that dylib.

(2) If the wrong dylib enumeration was used, the code would fail, but only at runtime. Given the large amount of code and functionality in the application, this delayed signal led to a lot of frustration during development.

On top of that, the only system we had to prevent these calls from being introduced during startup was runtime based, and many releases were delayed while applications introduced last minute regressions.

Ultimately, dylib optimizations curbed the unbounded growth in app release times, but this represented a huge turning point in app architecture. FBiOS engineers spent the next few years redesigning the app to smooth out some of the rough edges introduced by dylibs, and we (ultimately) shipped with an app architecture that was more powerful than ever before.

4. 2017: Rethinking FBiOS Architecture

With the introduction of dylibs, several key components of FBiOS need to be rethought:

(1) The "module registration system" can no longer be runtime-based.

(2) Engineers need a way to understand whether any code path during startup will trigger a dylib load.

(3) To solve these problems, FBiOS turned to Meta's open source build system Buck.

In Buck, each "target" (app, dylib, library, etc.) is declared with some configuration, like this:

 apple_binary (
 name = "Facebook" ,
 ...
 deps = [
 ":NotOnStartup#shared" ,
 ":FBCamera#shared" ,
 ] ,
 )

 apple_library (
 name = "NotOnStartup" ,
 srcs = [
 "SomeFile.mm" ,
 ] ,
 labels = [ "special_label" ] ,
 deps = [
 ":PokesModule" ,
 ...
 ] ,
 )

Each "target" lists all the information needed to build it (dependencies, compiler flags, sources, etc.), and when "buck build" is called it builds all of this information into a graph that can be queried.

 $ buck query "deps ( : Facebook ) "
 > : NotOnStartup
 > : FBCamera

 $ buck query "attrfilter ( labels , special_label , deps ( : Facebook ) ) "
 > : NotOnStartup

Using this core concept (and some special sauce), FBiOS began generating some buck queries that could generate a holistic view of the classes and functions in the application during the build process. This information would become the cornerstone of the next generation architecture of the application.

2018: The surge in generated code

Since FBiOS can use Buck to query code information in dependencies, it can create a "function/classes->dylibs" mapping that can be generated on the fly.

 {
 "functions" : {
 "DoSomething" : Dylib .NotOnStartup ,
 ...
 } ,
 "classes" : {
 "FBSomeClass" : Dylib .SomeOtherOne
 }
 }

Using that map as input, FBiOS uses it to generate code that abstracts the dylib enumeration from the call site:

 static std :: unordered_map < const char * , Dylib > functionToDylib { {
 { "DoSomething" , Dylib .NotOnStartup } ,
 { "FBSomeClass" , Dylib .SomeOtherOne } ,
 ...
 } } ;

Swipe left and right to view the complete code

Using code generation is attractive for several reasons:

(1) Because the code is regenerated based on local input, there is nothing to check in and no more merge conflicts! Considering that FBiOS's engineering size doubles every year, this is a huge development efficiency win.

(2) An application-specific dylib is no longer required (and can therefore be renamed to "FBCallFunction"). Instead, calls will be read from a static map generated for each application during the build.

Combining Buck queries with code generation proved so successful that FBiOS used it as the basis for a new plugin system that eventually replaced the runtime-based app module system.

1. Left shift signal

Using a plugin system powered by Buck, FBiOS was able to replace most runtime failures with build-time warnings by migrating infra to a plugin-based architecture.

When building FBiOS, Buck can generate a diagram showing the location of all plugins in your application, like this:

From this perspective, the plugin system can surface build time errors so engineers can be warned:

(1) "Plugins D, E may trigger dylib loading. This is not allowed because the callers of these plugins are in the application's startup path."

(2) "There is no plugin in the application for presenting the profile...which means navigating to that screen will not work."

(3) "There are two plugins for rendering groups (Plugin A, Plugin B). One of them should be removed."

With the old app module system, these errors would be "lazy" runtime assertions. Now, engineers have confidence that when FBiOS builds successfully, it will not fail due to missing functionality, dylib loading during app startup, or invariants in the module runtime system.

2. The cost of code generation

While migrating FBiOS to a plugin system improved the reliability of the app, provided faster signaling to engineers, and enabled the app to easily share code with other mobile apps, it came at a cost:

(1) It is difficult to find answers to plugin errors on Stack Overflow, and debugging can be a bit difficult.

(2) The plug-in system based on code generation and Buck is completely different from traditional iOS development.

(3) Plugins introduce an intermediate layer to the code base. Most applications have a registry file that contains all the functions, which is generated by FBiOS and is difficult to find.

There is no doubt that plugins take FBiOS away from idiomatic iOS development, but the tradeoff seems worth it. Our engineers can change the code used in many of Meta's apps and be sure that if the plugin system works well, no app will break due to missing functionality in a rarely tested code path. Teams like News Feed and Groups can build an extension point for plugins and ensure that product teams can integrate into their surfaces without touching the core code.

6. 2020: Swift and language architecture

The architectural changes were caused by application scale issues, but changes in Apple's SDK also forced FBiOS to reconsider some of its architectural decisions.

In 2020, FBiOS started to see an increase in the number of Swift-specific APIs from Apple, and a growing desire to use more Swift in the code base. It’s finally time to accept that Swift is an unavoidable tenant in FB apps.

Historically, FBiOS has used C++ as a lever to build abstractions, which saves code size because of C++'s "zero overhead" principle. But C++ is not yet interoperable with Swift. For most FBiOS APIs (such as ComponentKit), some kind of shim must be created to be used in Swift, resulting in code bloat.

Here is a diagram outlining the issues in the codebase:

With this in mind, we began to form a language strategy for when and where to use various codes:

Eventually, the FBiOS team began suggesting that product-facing APIs/code should not contain C++, allowing us to freely use Apple's Swift and future Swift APIs. Using plugins, FBiOS could abstract away the C++ implementations so that they still powered the app but were hidden from most engineers.

This type of workflow means some changes in the way FBiOS engineers build abstractions. Since 2014, the biggest factors influencing the construction of the framework have been the contribution to the size and expressiveness of the application (this is why ComponentKit chose Objective-C++ instead of Objective-C).

The introduction of Swift has led to reduced efficiency for developers, but don’t worry, we will see more in the future.

7. 2022: 1% of the journey completed

FBiOS architecture has changed a lot since 2014:

(1) It introduces a lot of internal abstractions, such as ComponentKit and GraphQL.

(2) It uses dylibs to keep the "pre-main" time to a minimum and helps to start the application quickly.

(3) It introduced a plugin system (powered by Buck) that abstracted dylibs from engineers so code could be easily shared between applications.

(4) It introduced language guidelines about when and where to use various languages ​​and began changing the code base to reflect these language guidelines.

Meanwhile, Apple has made exciting improvements to its phones, OS, and SDKs:

(1) Their new phones are very fast. The cost of loading is much smaller than before.

(2) Operating system improvements such as dyld3 and chain repair provide software that makes code load faster.

(3) They introduced SwiftUI, a declarative API for UI that shares many concepts with ComponentKit.

(4) They provide an improved SDK and an API for which we can build custom frameworks (such as interruptible animations in iOS8).

As Facebook, Messenger, Instagram, and WhatsApp share more experiences, FBiOS is revisiting all of these optimizations to see where we can get closer to platform canon. Ultimately, we found that the easiest way to share code is to use something that the apps provide for free, or to build something that has few dependencies and can be integrated between all apps.

We'll see you there in 2032, looking back on the codebase's 20th anniversary! ​