Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/MobileNativeFoundation/rules_xcodeproj/llms.txt

Use this file to discover all available pages before exploring further.

xcodeproj_extra_files is an aspect hint rule that associates extra files with a specific Bazel target in the generated Xcode project. Unlike the xcodeproj.extra_files attribute — which adds files at the project root level — this hint attaches files to a particular target’s group in the Xcode project navigator, keeping related files organized alongside the target that owns them.

​
Load

load("@rules_xcodeproj//xcodeproj:xcodeproj_extra_files.bzl", "xcodeproj_extra_files")

​
When to use it

Use xcodeproj_extra_files when you want non-compiled files such as a README.md, documentation, or configuration files to appear inside a specific library or target group in Xcode rather than floating at the root of the project. Common use cases include:
  • Displaying a README.md or CHANGELOG.md inside a library’s group
  • Surfacing a MODULE.bazel or .bazelrc snippet next to its related target
  • Including a code generation script or template file alongside the target that uses it

​
Example

load("@rules_xcodeproj//xcodeproj:xcodeproj_extra_files.bzl", "xcodeproj_extra_files")

swift_library(
    name = "Lib",
    srcs = glob(["Sources/**/*.swift"]),
    aspect_hints = [":lib_extra_files"],
)

# Display the README.md file located alongside the Swift library in Xcode
xcodeproj_extra_files(
    name = "lib_extra_files",
    files = ["README.md"],
)
The aspect_hints attribute is a standard Bazel attribute supported by many rules including swift_library, cc_library, objc_library, and others. Consult the documentation for the rule you are using to confirm it supports aspect_hints.

​
Attributes

​
name
Name
required
A unique name for this target.
​
files
List of labels
required
The list of extra files to surface in the Xcode project navigator. These files are displayed under the group of the target that references this hint via aspect_hints, but they are not compiled or otherwise processed as build inputs.

​
Comparison with xcodeproj.extra_files

xcodeproj_extra_files (aspect hint)xcodeproj.extra_files (rule attribute)
ScopeAttached to a specific target’s groupAdded at the project root level
Where configuredOn any target via aspect_hintsOn the xcodeproj rule itself
Best forPer-library or per-target filesProject-wide files (e.g. .bazelrc, workspace docs)

Build docs developers (and LLMs) love

Get started for freeTalk to us