• Drew's avatar
    Umbrella headers v2 · 587894a9
    Drew authored
    We now include the synthesized module map in our build products.  To
    support this, a new `:modulemap "synthesized"` directive is available
    (and must be used if `umbrella-header` is used.)  We could potentially
    have other modulemap modes besides synthesized (explicit, for example).
    
    We use one modulemap privately as part of the build process (to store
    the umbrella header) and a different one publicly (which doesn't have
    the umbrella header).
    
    This is (surprisingly!) totally legal under the Clang module map
    specification.
    http://clang.llvm.org/docs/Modules.html#private-module-map-files
    
    > However, in some cases, the presence or absence of particular headers is used to distinguish between the “public” and “private” APIs of a particular library. For example, a library may contain the headers Foo.h and Foo_Private.h, providing public and private APIs, respectively. Additionally, Foo_Private.h may only be available on some versions of library, and absent in others. One cannot easily express this with a single module map file in the library:
    
    ```
    module Foo {
      header "Foo.h"
    
      explicit module Private {
        header "Foo_Private.h"
      }
    }
    ```
    
    > because the header Foo_Private.h won’t always be available. The module
    > map file could be customized based on whether Foo_Private.h is
    > available or not, but doing so requires custom build machinery.
    
    We are the custom build machinery of which the clattner foretold.
    
    Note that (some) Swift engineers claim this is dangerous, but it works,
    is compliant with the Clang specification, and the tests pass.
    
    I should probably also document one other thing that I found diagnosing
    why the previous approach didn't work.  A "swiftmodule" (which nobody
    seems to understand) actually (sometimes) functions as an overlay for a
    Clang module.  See e.g.
    https://github.com/apple/swift/blob/1b2288fa96e4d531956bc690e64616afc2fb3333/include/swift/Serialization/Validation.h#L41
    
    What happen is that if you compile with -import-underlying-module (which
    we do in the umbrella case) the swift module that gets built is a
    "overlay" that points to some underlying clang module, see here:
    https://twitter.com/drewcrawford/status/694995772148846592.  Then at
    import time somebody goes looking for that underlying module (e.g.
    modulemap) in addition to the .swiftmodule.
    
    However there is no reason (as far as Clang is concerned) why the
    modulemap it finds at runtime may not be totally different than the
    modulemap we used at compile time, so that's what we do.
    587894a9
atllbuild.swift 19.1 KB