Header/Import Guidelines (#5765)

Author: paulb777

AddNewPod.md

@@ -46,6 +46,10 @@ explicit import by other Firebase pods)
 * `FirebaseFoo/Tests/Sample` - Optional
 * `FirebaseFoo/Tests/{Other}` - Optional
 
+## Headers and Imports
+
+See [Headers and Imports](HeadersImports.md) for details on managing headers and imports.
+
 ## Continous Integration
 
 Set up a GitHub Action workflow for the pod. A good example template is
@@ -61,7 +65,10 @@ For GitHub tag management and public header change detection, add a GitHub api t
 
 ## Firebase Integration
 
-* Make sure the public headers are imported via [Firebase.h](CoreOnly/Sources/Firebase.h).
+For top-level Firebase pods that map to documented products:
+
+* Make sure the public umbrella header is imported via [Firebase.h](CoreOnly/Sources/Firebase.h)
+  wrapped in `__has_include`. Follow the existing examples for details.
 * Update [Firebase.podspec](Firebase.podspec).
 * Register library via registerInternalLibrary API like this
   [Storage example](FirebaseStorage/Sources/FIRStorageComponent.m).

HeadersImports.md

@@ -0,0 +1,88 @@
+# 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`. 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.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](https://stackoverflow.com/a/8016333) and CocoaPods refer to these as "Private Headers".
+  Note that the usage CocoaPods `private_headers` is deprecated and should instead
+  the `source_files` attribute should be used for access them with a repo-relative import.
+
+* *Interop Headers* - A special kind of private header that defines an interface to another library.
+  Details in [Firebase Component System docs](Interop/FirebaseComponentSystem.md).
+
+* *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](https://stackoverflow.com/a/8016333) refers to
+  these as "Project Headers".
+
+## 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/Sources/Private/FirebaseCoreInternal.h`. For CocoaPods, these files should be
+  added to the podspec in the `preserved_path` attribute like:
+```
+  s.preserve_paths = 'Interop/Auth/Public/*.h', 'FirebaseCore/Sources/Private/*.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](https://stackoverflow.com/a/8016333) 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.

README.md

@@ -98,7 +98,7 @@ Instructions for installing binary frameworks via
 To develop Firebase software in this repository, ensure that you have at least
 the following software:
 
-  * Xcode 10.1 (or later)
+  * Xcode 10.3 (or later)
   * CocoaPods 1.7.2 (or later)
   * [CocoaPods generate](https://github.com/square/cocoapods-generate)
 
@@ -129,6 +129,10 @@ Firestore has a self contained Xcode project. See
 
 See [AddNewPod.md](AddNewPod.md).
 
+### Managing Headers and Imports
+
+See [HeadersImports.md](HeadersImports.md).
+
 ### Code Formatting
 
 To ensure that the code is formatted consistently, run the script

scripts/check_no_module_imports.sh

@@ -29,7 +29,8 @@ function exit_with_error {
 
 git grep "${options[@]}" \
   -- ':(exclude,glob)**/Example/**' ':(exclude,glob)**/Sample/**' \
-     ':(exclude)FirebaseCore/Sources/Private/FirebaseCoreInternal.h' && exit_with_error
+     ':(exclude)FirebaseCore/Sources/Private/FirebaseCoreInternal.h' \
+     ':(exclude)HeadersImports.md' && exit_with_error
 
 # Tests are under the Example directory, so we have to separately grep them for
 # @import statements (otherwise they'd be excluded).