iOS UmbrellaHeader

Lexical or Preprocessor Issue - Umbrella header for module 'xxx' does not include header 'xxx.h'

framework 的文件明明被主工程引用了，但是在編譯的時候依舊拋出上面的警告。

一、什么是 umbrella header?

參考官方文檔《Introduction to Framework Programming Guide》，可以了解到 Framework 區分Standard Framework 和 Umbrella Framework。但是並沒有找到官方文檔有對 Umberlla framework 給出明確的定義。在官方文檔《Anatomy of Framework Bundles》章節中， 找到三段比較合理說明 Umbrella Framework 的話：

Umbrella frameworks add minor refinements to the standard framework structure， such as the ability to encompass other frameworks

The structure of an umbrella framework is similar to that of a standard framework， and applications do not distinguish between umbrella frameworks and standard frameworks when linking to them. However， two factors distinguish umbrella frameworks from other frameworks. The first is the manner in which they include header files. The second is the fact that they encapsulate subframeworks.

Physically， umbrella frameworks have a similar structure to standard frameworks. One significant difference is the addition of a Frameworks directory to contain the subframeworks that make up the umbrella framework.

字面上的意思應該是在標准的 Framework 做了一些改良的工作，使其可以嵌套包含 Framework。在物理結構上，Umbrella Framework 只在包含頭文件的方式以及是否包含子 Framework 和普通的 Framework 存在區別。

那么引用頭文件的地方又有什么區別呢? 還是參考官方文檔引用:

For most frameworks， you can include header files other than the master header file. You can include any specific header file you want as long as it is available in the framework’s Headers directory. However， if you are including an umbrella framework， you must include the master header file. Umbrella frameworks do not allow you to include the headers of their constituent subframeworks directly. See Restrictions on Subframework Linking for more information.

簡單翻譯一下: 普通的 Framework 可以通過引用對應的 heaedr 文件而不是 Master Header File 去引用需要使用的類，只需要對應的 header 頭文件在 Headers 文件夾下暴露，並沒有強制要求引用 Master Header File。Umbrella Framework 要求必須要引用 Master Header File，並且頭文件中不能直接引用子 Framework 的東西。

上述描述已經說了 Umbrella Framework 一定要引用 Master Header File，而 Umbrella Framework 的 Master Header File 就是 Umbrella header 文件。

官方說明中只有強制規定一定要引用 Umbrella Header 文件，但是卻沒有說能不能單獨引用 Umbrella Framework 的其他頭文件呢? 我們可以自己試驗一下:

1. 在 Umbrella Framework 新建一個 testObject 類，分別產生了 testObject.h 和 testObject.m 文件。
2. 打開 Framework 配置文件，在 Build Phases的Headers 里的 Public 目錄下，將 testObject.h 文件添加進去。
3. Build Framework 看是否報錯。
4. 在主工程中調用初始化 testObject 對象，看編譯是否報錯。

執行結果:

• 步驟3: 沒有編譯報錯， 但是報出了 Lexical or Preprocessor Issue - Umbrella header for module 'STDemoUI' does not include header 'testObject.h'的警告。
• 步驟4: 執行正常。

總結一下:

1. Standard Framework 不能包含 Sub Framework；Umbrella Framework 可以包含子 Framework;
2. Standard Framework 可以直接引用需要使用的頭，也可以通過引用 Master Header file 來引用需要使用的類；Umbrella Framework 需要通過引用 Master Header File(Umbrella Header) 來引用需要使用的類;

二、規范的寫法

Umbrella Framework 默認會創建一個同名 .h 文件做為 Umbrella Header 文件。規范的寫法當然是遵從默認的模式，將所有需要暴露的頭文件都寫在 Umbrella Header 文件中。

例如: STDemoUI.framework 工程包含了 STClassOne、STClassTwo 和 STClassThree 三個類。

STDemoUI 會生成一個默認的傘頭文件（直譯 Umbrella Header）STDemoUI.h。假設該 framework 的三個類均需要在外部調用使用，則 STDemoUI.h 需要將三個類的引用均寫入傘頭文件中。

// STDemoUI.h
// ...

#import <STDemoUI/STClassOne.h>
#import <STDemoUI/STClassTwo.h>
#import <STDemoUI/STClassThree.h>

在需要調用的主工程中， 僅僅只要將 Umbrella Header 引用即可調用所有在 Umbrella Header 中包含的類了。

// 在主工程需要應用的類中包含Umbrella Header
#import <STDemoUI/STDemoUI.h>

三、重命名 umbrella header

如果大家都遵從默認的 Umbrella Framework 的寫法，在同名頭文件中寫需要暴露的引用頭文件，那么就不需要考慮怎么重命名 Umbrella header 了。

很多時候，理想和現實是有差距的，程序員寫代碼多數是在二次接手進行開發的。假設公司的前輩已經將 Framework 的同名文件用作了一個邏輯類， 給同名文件創建了 .m 文件， 並已經書寫了邏輯並應用了各個工程里面去了。那么顯然遷移頭文件功能代碼是不可能的，因為很多依賴該 Framework 的業務部門都需要針對庫進行代碼優化。

在這種不能將同名文件作為 Umbrella header 的情況下，我們又不想通過 Public 強制暴露頭文件的情況下（不寫在 Umbrella Header 中會有警告）。我們就需要對 Umbrella Header 進行指定了。

1. 指定 Umbrella Header 入口在哪里呢?

   • 在工程全局搜索 umbrella 關鍵字 - Failed
   • 在Build Settings里搜索umbrella關鍵字 - Failed
   • 在打包好的 STDemoUI.framework 中搜索 umbrella 關鍵字 - Success

   雙擊點開 STDemo.framework，內容如下：

   

   初略看名稱可以推測出每個文件以及文件夾所承擔的作用:

   • _CodeSignature：保存簽名相關文件
   • Headers：framework 暴露的所有頭文件
   • Info.plist：描述了該 framework 所包含的項目配置信息
   • UmbrellaFramework：編譯后的核心庫文件
   • Modules：模塊相關文件夾， 目測只包含了 module.modulemap 文件
   • Frameworks：包含的子 framework

   我們在 module.modulemap 文件中找到了 umbrella 關鍵字。文件內容如下:

   framework module STDemoUI {
     umbrella header "STDemoUI.h"
   
     export *
   
     module * { export * }
   
   }
   

   原來 Framework 的 umbrella header 是在這個位置被指定的，但是這個已經是編譯好的工程， 我們總不能每次編譯好了再進到包里面修改下。既然我們已經找到 umbrella header 是在 module 中去指定，那么我們就用 module 作為關鍵字再去 Build Settings 里重新搜索下。

   這回在 Kernel Module 和 Packaging 中均找到了 Module 關鍵字，在 Packaging 標簽中，有一項 Module Map File 屬性，看名字應該是用來指定 modulemap 文件的。

   

2. 指定 Modulemap 文件

   1. 創建一個新的 .h 文件，如：STHeader.h。將所有需要暴露的頭文件均寫入 STHeader.h
   2. 創建一個新的 modulemap 文件，如：stdemoalt.modulemap

   3. 在新的 modulemap 中指定 umbrella header

      framework module STDemoUI {
          umbrella header "STHeader.h"
      
          export *
      
          module * { export * }
      
      }
      

   4. 在 framework 的 Build Settings 中的 Module Map File 指定新建的 modulemap 文件。

   5. CMD+B 編譯，打開 framework 包中的 Module 文件夾，看是否包含了新指定的 modulemap。

拋出兩個疑問:

1. Module 是什么?
2. 如果 Defines Module 指定為 NO， 那會發生什么事情呢?

四、總結

本文簡單的梳理了官方文章關於 Umbrella Framework 和 Umbrella Header 的介紹說明，產生警告的原因是沒有引用 umbrella header 或者暴露頭沒有寫在 umbrella header 中。在 umbrella header 被已使用的前提下，本文提供了一種通過重命名 Umbrella Header 文件的方式來消除警告的解決方案。

雖然引用警告可以被消除，但是建議大家還是采用規范的做法：盡量不要在同名頭文件中寫業務邏輯代碼， 用同名文件作為 Umbrella 庫的 Master Header File。

五、內容來源

iOS - Umbrella Header在framework中的應用