Skip to main content

Headers and Imports

Introduction​

Follow this set of guidelines when creating header files and importing them. The guidelines are designed to support a wide range of build systems and usage scenarios.

In this document, the term library refers to a buildable package. In CocoaPods, it's a CocoaPod. In Swift Package Manager, it's a library target.

Header File Types and Locations - For Header File Creators​

  • Public Headers - Headers that define the library's API. They should be located in FirebaseFoo/Sources/Public/FirebaseFoo. Any additions require a minor version update. Any changes or deletions require a major version update.

  • Public Umbrella Header - A single header that includes the full library's public API located at FirebaseFoo/Sources/Public/FirebaseFoo/FirebaseFoo.h.

  • Private Headers - Headers that are available to other libraries in the repo, but are not part of the public API. These should be located in FirebaseFoo/Sources/Private. Xcode. They should be accessed with a repo-relative import. For CocoaPods, do not use the private_headers attribute. Instead include them in both the provider and client's source_files attribute.

  • Interop Headers - A special kind of private header that defines an interface to another library. Details in Firebase Component System docs.

  • Private Umbrella Header - A single header that includes the library's public API plus any APIs provided for other libraries in the repo. Any package manager complexity should be localized to this umbrella header.

  • Library Internal Headers - Headers that are only used by the enclosing library. These headers should be located among the source files. Xcode refers to these as "Project Headers".

  • Library C++ Internal Headers - In CocoaPods, C++ internal headers should not be included in the source_files attribute. Instead, they should be defined with the preserve_paths attribute to avoid filename collisions in the generated Xcode workspace. C++ does not assume a global header map, so if filenames are qualified at all, it's generally by directory, not a filename prefix like in Objective-C.

Imports - For Header File Consumers​

  • Headers within the Library - Use a repo-relative path for all of the header types above.

    • Exception - Public header imports from other public headers should do an unqualified import like #import "publicHeader.h" to avoid public module collisions.

  • Private Headers from other Libraries - Import a private umbrella header like FirebaseCore/Extension/FIRebaseCoreInternal.h. For CocoaPods, these files should be added to the podspec in the source_files attribute like:

  s.source_files = [ 'FirebaseFoo/Sources/**/*.[mh]'
                     'FirebaseAuth/Interop/*.h',
                     'FirebaseCore/Internal/*.h',
                   ]
  • Headers from an external dependency - Do a module import for Swift Package Manager and an umbrella header import otherwise, like:
#if SWIFT_PACKAGE
@import GTMSessionFetcherCore;
#else
#import <GTMSessionFetcher/GTMSessionFetcher.h>
#endif

Additional Background​

Here is some additional detail that should give deeper insight onto the above guidelines.

Build Systems​

We support building with CocoaPods, cmake, internal Google build system, and Swift Package Manager (in development). Using repo-relative headers is a key enabler since it allows all headers to be found with a single path specifier no matter what the build system.

CocoaPods Build Systems​

CocoaPods itself has a range of options that impact the functionality of header imports.

The use_frameworks! option enables @import {module-name}. CocoaPods creates a directory structure such that #import <pod-name/header> works whether or not frameworks are built.

CocoaPods builds a different directory structure for a Development Pods install versus an install from a published podspec. This can hide errors resulting from header search path pointing outside of a particular pod's sources.

"Internal" versus "Private"​

"Internal" and "Private" are often used interchangeably since Xcode and CocoaPods usage is inconsistent with expectations of C++ developers. "Private" headers are available to clients via an explicit import. "Internal" or "Project" headers are only available to their enclosing library. Many file names in this repo include "Private" or "Internal" do not comply. Always check the build definition to see how the file is used.

Public Header Location Explanation​

CocoaPods flattens all headers specified in the podspec and makes them available via #import "FirebaseFoo/Header.h". Swift Package Manager does not flatten. Therefore, the directory structure described above allows clients to import headers from either package manager without #if checks.