Skip to content

Support Objective-C in docc_archive - #3101

Open
louwers wants to merge 4 commits into
bazelbuild:mainfrom
louwers:docc-objc-support
Open

louwers wants to merge 4 commits into
bazelbuild:mainfrom
louwers:docc-objc-support

Conversation

@louwers

@louwers louwers commented Oct 8, 2026

Copy link
Copy Markdown
Contributor

Fixes #2241

docc_archive only supported Swift. This adds Objective-C support by extracting symbol graphs from the public headers (hdrs) of objc_library targets with clang -extract-api, the same tool Xcode uses for Objective-C DocC.

  • The extraction uses the target's propagated compilation context (includes, defines, framework search paths). The -target triple comes from the C++ toolchain and the SDK from the target platform. -fmodules is passed when enable_modules is set or -fmodules is in copts.
  • A DocC archive documents a single module. Unlike Swift symbol graphs, which are still transitive as before, Objective-C symbol graphs of transitive dependencies are not included: including them produces MultipleRootPages warnings and unresolved links from the .docc bundle. Targets that don't define a module themselves forward the Objective-C symbol graphs of their direct deps: bundling rules like ios_framework, or objc_library targets without public headers. The latter can be used to attach a .docc bundle to an existing library without it ending up as a resource in the app bundle.
  • emit_extension_block_symbols = "1" also adds --emit-extension-symbol-graphs for Objective-C, which includes members of categories on types from other modules.
  • New source_service and source_service_base_url attributes (mapping to docc convert --source-service / --source-service-base-url) link symbols to their source files. Symbol graphs reference files relative to the execution root, so the symbol graph collection step anchors those paths at a fixed checkout path that is passed as --checkout-path. That keeps outputs deterministic. Generated (bazel-out/) and external/ files are not linked.

Tested with new Starlark tests covering:

  • an Objective-C library
  • an Objective-C library with a .docc bundle
  • an ios_framework with Objective-C deps
  • a header-less objc_library wrapper with a .docc bundle
  • source_service

I also used it to replace the bespoke DocC script in MapLibre Native (maplibre/maplibre-native#4738). The output matches the script's, with source links added for headers the script couldn't link.

🤖 Generated with Claude Code

@google-cla

google-cla Bot commented Oct 8, 2026

Copy link
Copy Markdown

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

Extract symbol graphs from the public headers of `objc_library` targets
with `clang -extract-api` so that `docc_archive` can document
Objective-C (and mixed Swift/Objective-C) code. Symbol graphs are now
collected uniformly through `deps` for both languages.

Fixes bazelbuild#2241

Assisted-by: Claude <noreply@anthropic.com>
A DocC archive documents a single module, so including the symbol graphs
of transitive Objective-C dependencies results in multiple root modules
and unresolved symbol links in the .docc bundle. Only extract the
Objective-C module of the dep itself. Targets that don't define a module
themselves (bundling rules or objc_library targets without public
headers) forward the Objective-C symbol graphs of their direct deps,
which also allows attaching a .docc bundle to an existing library.

Also add the `source_service` and `source_service_base_url` attributes
to link symbols to their source files.

Assisted-by: Claude <noreply@anthropic.com>
@louwers
louwers force-pushed the docc-objc-support branch from 9fd2499 to 5f16986 Compare October 8, 2026 19:52
Comment thread doc/rules-docc.md Outdated
Assisted-by: Claude <noreply@anthropic.com>
Assisted-by: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support objective-c in new docc_archive rule

1 participant