Divide gRPC-Core in Interface & Impl subspecs

This works around the Cocoapods' linter header_mapping_dir restrictions. Incidentally, it also removes the need to set build settings in the user target.
9 years ago · cc074d9647
parent 0d3f178d4b
commit cc074d9647
3 changed files with 713 additions and 636 deletions
--- a/gRPC-Core.podspec
+++ b/gRPC-Core.podspec
@ -45,6 +45,7 @@ Pod::Spec.new do |s|
  s.source = {
    :git => 'https://github.com/grpc/grpc.git',
    :tag => "release-#{version.gsub(/\./, '_')}-objectivec-#{version}",
+    # TODO(jcanizales): Depend explicitly on the nanopb pod, and disable submodules.
    :submodules => true,
  }

@ -53,54 +54,67 @@ Pod::Spec.new do |s|
  s.requires_arc = false

  name = 'grpc'
+
+  # When creating a dynamic framework, name it grpc.framework instead of gRPC-Core.framework.
+  # This lets users write their includes like `#include <grpc/grpc.h>` as opposed to `#include
+  # <gRPC-Core/grpc.h>`.
  s.module_name = name
-  s.header_dir = name

+  # When creating a dynamic framework, copy the headers under `include/grpc/` into the root of
+  # the `Headers/` directory of the framework (i.e., not under `Headers/include/grpc`).
+  #
+  # TODO(jcanizales): Debug why this doesn't work on macOS.
  s.header_mappings_dir = 'include/grpc'

-  src_root = '$(PODS_ROOT)/gRPC-Core'
-  # This isn't officially supported in Cocoapods. We've asked for an alternative:
-  # https://github.com/CocoaPods/CocoaPods/issues/4386
+  # The above has an undesired effect when creating a static library: It forces users to write
+  # includes like `#include <gRPC-Core/grpc.h>`. `s.header_dir` adds a path prefix to that, and
+  # because Cocoapods lets omit the pod name when including headers of static libraries, the
+  # following lets users write `#include <grpc/grpc.h>`.
+  s.header_dir = name
+
+  # The module map created automatically by Cocoapods doesn't work for C libraries like gRPC-Core.
+  s.module_map = 'include/grpc/module.modulemap'
+
+  # To compile the library, we need the user headers search path (quoted includes) to point to the
+  # root of the repo, and the system headers search path (angled includes) to point to `include/`.
+  # Cocoapods effectively clones the repo under `<Podfile dir>/Pods/gRPC-Core/`, and sets a build
+  # variable called `$(PODS_ROOT)` to `<Podfile dir>/Pods/`, so we use that.
+  #
+  # Relying on the file structure under $(PODS_ROOT) isn't officially supported in Cocoapods, as it
+  # is taken as an implementation detail. We've asked for an alternative, and have been told that
+  # what we're doing should keep working: https://github.com/CocoaPods/CocoaPods/issues/4386
  #
-  # The src_root value of $(PODS_ROOT)/gRPC-Core assumes Cocoapods is installing this pod from its
-  # remote repo. For local development of this library, enabled by using ":path" in the Podfile,
+  # The `src_root` value of `$(PODS_ROOT)/gRPC-Core` assumes Cocoapods is installing this pod from
+  # its remote repo. For local development of this library, enabled by using `:path` in the Podfile,
  # that assumption is wrong. In such case, the following settings need to be reset with the
-  # appropriate value of src_root. This can be accomplished in the pre_install hook of the Podfile;
-  # see src/objective-c/tests/Podfile for an example.
-  public_build_settings = {
+  # appropriate value of `src_root`. This can be accomplished in the `pre_install` hook of the
+  # Podfile; see `src/objective-c/tests/Podfile` for an example.
+  src_root = '$(PODS_ROOT)/gRPC-Core'
+  s.pod_target_xcconfig = {
    'GRPC_SRC_ROOT' => src_root,
    'HEADER_SEARCH_PATHS' => '"$(inherited)" "$(GRPC_SRC_ROOT)/include"',
-  }
-  private_build_settings = public_build_settings.merge({
+    'USER_HEADER_SEARCH_PATHS' => '"$(GRPC_SRC_ROOT)"',
+    # If we don't set these two settings, `include/grpc/support/time.h` and
+    # `src/core/lib/support/string.h` shadow the system `<time.h>` and `<string.h>`, breaking the
+    # build.
    'USE_HEADERMAP' => 'NO',
    'ALWAYS_SEARCH_USER_PATHS' => 'NO',
-    'USER_HEADER_SEARCH_PATHS' => '"$(GRPC_SRC_ROOT)"',
-  })
-  s.user_target_xcconfig = public_build_settings
-  s.pod_target_xcconfig = private_build_settings
-
-  s.libraries = 'z'
-  s.dependency 'BoringSSL', '~> 4.0'
+  }

-  # A module map is necessary for a dynamic framework to be correctly created by Cocoapods.
-  s.module_map = 'include/grpc/module.modulemap'
+  # Like many other C libraries, gRPC-Core has its public headers under `include/<libname>/` and its
+  # sources and private headers in other directories outside `include/`. Cocoapods' linter doesn't
+  # allow any header to be listed outside the `header_mappings_dir` (even though doing so works in
+  # practice). Because we need our `header_mappings_dir` to be `include/grpc/` for the reason
+  # mentioned above, we work around the linter limitation by dividing the pod into two subspecs, one
+  # for public headers and the other for implementation. Each gets its own `header_mappings_dir`,
+  # making the linter happy.
+  #
+  # The list of source files is generated by a template: `templates/gRPC-Core.podspec.template`. It
+  # can be regenerated from the template by running `tools/buildgen/generate_projects.sh`.
+  s.subspec 'Interface' do |ss|
+    ss.header_mappings_dir = 'include/grpc'

-  # List of source files generated by a template: `templates/gRPC-Core.podspec.template`. It can be
-  # regenerated from the template by running `tools/buildgen/generate_projects.sh`.
-  # To save you from scrolling, this is the last part of the podspec.
-  s.source_files = 'src/core/lib/profiling/timers.h',
-                   'src/core/lib/support/backoff.h',
-                   'src/core/lib/support/block_annotate.h',
-                   'src/core/lib/support/env.h',
-                   'src/core/lib/support/load_file.h',
-                   'src/core/lib/support/murmur_hash.h',
-                   'src/core/lib/support/stack_lockfree.h',
-                   'src/core/lib/support/string.h',
-                   'src/core/lib/support/string_win32.h',
-                   'src/core/lib/support/thd_internal.h',
-                   'src/core/lib/support/time_precise.h',
-                   'src/core/lib/support/tmpfile.h',
-                   'include/grpc/support/alloc.h',
+    ss.source_files = 'include/grpc/support/alloc.h',
                      'include/grpc/support/atm.h',
                      'include/grpc/support/atm_gcc_atomic.h',
                      'include/grpc/support/atm_gcc_sync.h',
@ -142,6 +156,55 @@ Pod::Spec.new do |s|
                      'include/grpc/impl/codegen/sync_posix.h',
                      'include/grpc/impl/codegen/sync_win32.h',
                      'include/grpc/impl/codegen/time.h',
+                      'include/grpc/byte_buffer.h',
+                      'include/grpc/byte_buffer_reader.h',
+                      'include/grpc/compression.h',
+                      'include/grpc/grpc.h',
+                      'include/grpc/status.h',
+                      'include/grpc/impl/codegen/byte_buffer.h',
+                      'include/grpc/impl/codegen/byte_buffer_reader.h',
+                      'include/grpc/impl/codegen/compression_types.h',
+                      'include/grpc/impl/codegen/connectivity_state.h',
+                      'include/grpc/impl/codegen/grpc_types.h',
+                      'include/grpc/impl/codegen/propagation_bits.h',
+                      'include/grpc/impl/codegen/status.h',
+                      'include/grpc/impl/codegen/alloc.h',
+                      'include/grpc/impl/codegen/atm.h',
+                      'include/grpc/impl/codegen/atm_gcc_atomic.h',
+                      'include/grpc/impl/codegen/atm_gcc_sync.h',
+                      'include/grpc/impl/codegen/atm_win32.h',
+                      'include/grpc/impl/codegen/log.h',
+                      'include/grpc/impl/codegen/port_platform.h',
+                      'include/grpc/impl/codegen/slice.h',
+                      'include/grpc/impl/codegen/slice_buffer.h',
+                      'include/grpc/impl/codegen/sync.h',
+                      'include/grpc/impl/codegen/sync_generic.h',
+                      'include/grpc/impl/codegen/sync_posix.h',
+                      'include/grpc/impl/codegen/sync_win32.h',
+                      'include/grpc/impl/codegen/time.h',
+                      'include/grpc/grpc_security.h',
+                      'include/grpc/grpc_security_constants.h',
+                      'include/grpc/census.h'
+  end
+  s.subspec 'Implementation' do |ss|
+    ss.header_mappings_dir = '.'
+    ss.libraries = 'z'
+    ss.dependency "#{s.name}/Interface", version
+    ss.dependency 'BoringSSL', '~> 4.0'
+
+    # To save you from scrolling, this is the last part of the podspec.
+    ss.source_files = 'src/core/lib/profiling/timers.h',
+                      'src/core/lib/support/backoff.h',
+                      'src/core/lib/support/block_annotate.h',
+                      'src/core/lib/support/env.h',
+                      'src/core/lib/support/load_file.h',
+                      'src/core/lib/support/murmur_hash.h',
+                      'src/core/lib/support/stack_lockfree.h',
+                      'src/core/lib/support/string.h',
+                      'src/core/lib/support/string_win32.h',
+                      'src/core/lib/support/thd_internal.h',
+                      'src/core/lib/support/time_precise.h',
+                      'src/core/lib/support/tmpfile.h',
                      'src/core/lib/profiling/basic_timers.c',
                      'src/core/lib/profiling/stap_timers.c',
                      'src/core/lib/support/alloc.c',
@ -324,35 +387,6 @@ Pod::Spec.new do |s|
                      'src/core/ext/census/grpc_filter.h',
                      'src/core/ext/census/mlog.h',
                      'src/core/ext/census/rpc_metric_id.h',
-                   'include/grpc/byte_buffer.h',
-                   'include/grpc/byte_buffer_reader.h',
-                   'include/grpc/compression.h',
-                   'include/grpc/grpc.h',
-                   'include/grpc/status.h',
-                   'include/grpc/impl/codegen/byte_buffer.h',
-                   'include/grpc/impl/codegen/byte_buffer_reader.h',
-                   'include/grpc/impl/codegen/compression_types.h',
-                   'include/grpc/impl/codegen/connectivity_state.h',
-                   'include/grpc/impl/codegen/grpc_types.h',
-                   'include/grpc/impl/codegen/propagation_bits.h',
-                   'include/grpc/impl/codegen/status.h',
-                   'include/grpc/impl/codegen/alloc.h',
-                   'include/grpc/impl/codegen/atm.h',
-                   'include/grpc/impl/codegen/atm_gcc_atomic.h',
-                   'include/grpc/impl/codegen/atm_gcc_sync.h',
-                   'include/grpc/impl/codegen/atm_win32.h',
-                   'include/grpc/impl/codegen/log.h',
-                   'include/grpc/impl/codegen/port_platform.h',
-                   'include/grpc/impl/codegen/slice.h',
-                   'include/grpc/impl/codegen/slice_buffer.h',
-                   'include/grpc/impl/codegen/sync.h',
-                   'include/grpc/impl/codegen/sync_generic.h',
-                   'include/grpc/impl/codegen/sync_posix.h',
-                   'include/grpc/impl/codegen/sync_win32.h',
-                   'include/grpc/impl/codegen/time.h',
-                   'include/grpc/grpc_security.h',
-                   'include/grpc/grpc_security_constants.h',
-                   'include/grpc/census.h',
                      'src/core/lib/surface/init.c',
                      'src/core/lib/channel/channel_args.c',
                      'src/core/lib/channel/channel_stack.c',
@ -519,7 +553,7 @@ Pod::Spec.new do |s|
                      'src/core/ext/census/tracing.c',
                      'src/core/plugin_registry/grpc_plugin_registry.c'

-  s.private_header_files = 'src/core/lib/profiling/timers.h',
+    ss.private_header_files = 'src/core/lib/profiling/timers.h',
                              'src/core/lib/support/backoff.h',
                              'src/core/lib/support/block_annotate.h',
                              'src/core/lib/support/env.h',
@ -668,3 +702,4 @@ Pod::Spec.new do |s|
                              'src/core/ext/census/mlog.h',
                              'src/core/ext/census/rpc_metric_id.h'
  end
+end
--- a/src/objective-c/tests/Podfile
+++ b/src/objective-c/tests/Podfile
@ -44,18 +44,15 @@ pre_install do |installer|
  grpc_core_spec = installer.pod_targets.find{|t| t.name == 'gRPC-Core'}.root_spec

  # Copied from gRPC-Core.podspec, except for the adjusted src_root:
-
  src_root = "$(PODS_ROOT)/../#{GRPC_LOCAL_SRC}"
-
-  public_build_settings = {
+  grpc_core_spec.pod_target_xcconfig = {
    'GRPC_SRC_ROOT' => src_root,
    'HEADER_SEARCH_PATHS' => '"$(inherited)" "$(GRPC_SRC_ROOT)/include"',
-  }
-  private_build_settings = public_build_settings.merge({
+    'USER_HEADER_SEARCH_PATHS' => '"$(GRPC_SRC_ROOT)"',
+    # If we don't set these two settings, `include/grpc/support/time.h` and
+    # `src/core/lib/support/string.h` shadow the system `<time.h>` and `<string.h>`, breaking the
+    # build.
    'USE_HEADERMAP' => 'NO',
    'ALWAYS_SEARCH_USER_PATHS' => 'NO',
-    'USER_HEADER_SEARCH_PATHS' => '"$(GRPC_SRC_ROOT)"',
-  })
-  grpc_core_spec.user_target_xcconfig = public_build_settings
-  grpc_core_spec.pod_target_xcconfig = private_build_settings
+  }
 end
--- a/templates/gRPC-Core.podspec.template
+++ b/templates/gRPC-Core.podspec.template
@ -35,21 +35,30 @@
  # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

  <%!
-  def grpc_files(libs):
+  def grpc_private_files(libs):
    out = []
    for lib in libs:
      if lib.name in ("grpc", "gpr"):
        out += lib.get('headers', [])
-        out += lib.get('public_headers', [])
        out += lib.get('src', [])
    return out;

+  def grpc_public_headers(libs):
+    out = []
+    for lib in libs:
+      if lib.name in ("grpc", "gpr"):
+        out += lib.get('public_headers', [])
+    return out
+
  def grpc_private_headers(libs):
    out = []
    for lib in libs:
      if lib.name in ("grpc", "gpr"):
        out += lib.get('headers', [])
    return out
+
+  def ruby_multiline_list(files, indent):
+    return (',\n' + indent*' ').join('\'%s\'' % f for f in files)
  %>
  Pod::Spec.new do |s|
    s.name     = 'gRPC-Core'
@ -63,6 +72,7 @@
    s.source = {
      :git => 'https://github.com/grpc/grpc.git',
      :tag => "release-#{version.gsub(/\./, '_')}-objectivec-#{version}",
+      # TODO(jcanizales): Depend explicitly on the nanopb pod, and disable submodules.
      :submodules => true,
    }

@ -71,42 +81,77 @@
    s.requires_arc = false

    name = 'grpc'
+
+    # When creating a dynamic framework, name it grpc.framework instead of gRPC-Core.framework.
+    # This lets users write their includes like `#include <grpc/grpc.h>` as opposed to `#include
+    # <gRPC-Core/grpc.h>`.
    s.module_name = name
-    s.header_dir = name

+    # When creating a dynamic framework, copy the headers under `include/grpc/` into the root of
+    # the `Headers/` directory of the framework (i.e., not under `Headers/include/grpc`).
+    #
+    # TODO(jcanizales): Debug why this doesn't work on macOS.
    s.header_mappings_dir = 'include/grpc'

-    src_root = '$(PODS_ROOT)/gRPC-Core'
-    # This isn't officially supported in Cocoapods. We've asked for an alternative:
-    # https://github.com/CocoaPods/CocoaPods/issues/4386
+    # The above has an undesired effect when creating a static library: It forces users to write
+    # includes like `#include <gRPC-Core/grpc.h>`. `s.header_dir` adds a path prefix to that, and
+    # because Cocoapods lets omit the pod name when including headers of static libraries, the
+    # following lets users write `#include <grpc/grpc.h>`.
+    s.header_dir = name
+
+    # The module map created automatically by Cocoapods doesn't work for C libraries like gRPC-Core.
+    s.module_map = 'include/grpc/module.modulemap'
+
+    # To compile the library, we need the user headers search path (quoted includes) to point to the
+    # root of the repo, and the system headers search path (angled includes) to point to `include/`.
+    # Cocoapods effectively clones the repo under `<Podfile dir>/Pods/gRPC-Core/`, and sets a build
+    # variable called `$(PODS_ROOT)` to `<Podfile dir>/Pods/`, so we use that.
+    #
+    # Relying on the file structure under $(PODS_ROOT) isn't officially supported in Cocoapods, as it
+    # is taken as an implementation detail. We've asked for an alternative, and have been told that
+    # what we're doing should keep working: https://github.com/CocoaPods/CocoaPods/issues/4386
    #
-    # The src_root value of $(PODS_ROOT)/gRPC-Core assumes Cocoapods is installing this pod from its
-    # remote repo. For local development of this library, enabled by using ":path" in the Podfile,
+    # The `src_root` value of `$(PODS_ROOT)/gRPC-Core` assumes Cocoapods is installing this pod from
+    # its remote repo. For local development of this library, enabled by using `:path` in the Podfile,
    # that assumption is wrong. In such case, the following settings need to be reset with the
-    # appropriate value of src_root. This can be accomplished in the pre_install hook of the Podfile;
-    # see src/objective-c/tests/Podfile for an example.
-    public_build_settings = {
+    # appropriate value of `src_root`. This can be accomplished in the `pre_install` hook of the
+    # Podfile; see `src/objective-c/tests/Podfile` for an example.
+    src_root = '$(PODS_ROOT)/gRPC-Core'
+    s.pod_target_xcconfig = {
      'GRPC_SRC_ROOT' => src_root,
      'HEADER_SEARCH_PATHS' => '"$(inherited)" "$(GRPC_SRC_ROOT)/include"',
-    }
-    private_build_settings = public_build_settings.merge({
+      'USER_HEADER_SEARCH_PATHS' => '"$(GRPC_SRC_ROOT)"',
+      # If we don't set these two settings, `include/grpc/support/time.h` and
+      # `src/core/lib/support/string.h` shadow the system `<time.h>` and `<string.h>`, breaking the
+      # build.
      'USE_HEADERMAP' => 'NO',
      'ALWAYS_SEARCH_USER_PATHS' => 'NO',
-      'USER_HEADER_SEARCH_PATHS' => '"$(GRPC_SRC_ROOT)"',
-    })
-    s.user_target_xcconfig = public_build_settings
-    s.pod_target_xcconfig = private_build_settings
+    }

-    s.libraries = 'z'
-    s.dependency 'BoringSSL', '~> 4.0'
+    # Like many other C libraries, gRPC-Core has its public headers under `include/<libname>/` and its
+    # sources and private headers in other directories outside `include/`. Cocoapods' linter doesn't
+    # allow any header to be listed outside the `header_mappings_dir` (even though doing so works in
+    # practice). Because we need our `header_mappings_dir` to be `include/grpc/` for the reason
+    # mentioned above, we work around the linter limitation by dividing the pod into two subspecs, one
+    # for public headers and the other for implementation. Each gets its own `header_mappings_dir`,
+    # making the linter happy.
+    #
+    # The list of source files is generated by a template: `templates/gRPC-Core.podspec.template`. It
+    # can be regenerated from the template by running `tools/buildgen/generate_projects.sh`.
+    s.subspec 'Interface' do |ss|
+      ss.header_mappings_dir = 'include/grpc'

-    # A module map is necessary for a dynamic framework to be correctly created by Cocoapods.
-    s.module_map = 'include/grpc/module.modulemap'
+      ss.source_files = ${ruby_multiline_list(grpc_public_headers(libs), 22)}
+    end
+    s.subspec 'Implementation' do |ss|
+      ss.header_mappings_dir = '.'
+      ss.libraries = 'z'
+      ss.dependency "#{s.name}/Interface", version
+      ss.dependency 'BoringSSL', '~> 4.0'

-    # List of source files generated by a template: `templates/gRPC-Core.podspec.template`. It can be
-    # regenerated from the template by running `tools/buildgen/generate_projects.sh`.
      # To save you from scrolling, this is the last part of the podspec.
-    s.source_files = ${(',\n' + 19*' ').join('\'%s\'' % f for f in grpc_files(libs))}
+      ss.source_files = ${ruby_multiline_list(grpc_private_files(libs), 22)}

-    s.private_header_files = ${(',\n' + 27*' ').join('\'%s\'' % f for f in grpc_private_headers(libs))}
+      ss.private_header_files = ${ruby_multiline_list(grpc_private_headers(libs), 30)}
+    end
  end