The future of rules_ios

[jschear]

Square is migrating away from rules_ios in favor of using a thinner layer of custom rules and macros on top of rules_apple and rules_swift. We plan on ceasing to actively contribute to rules_ios.

Background

rules_ios was created to make migration from an xcodebuild-based build to Bazel as simple as possible. As rules_apple and rules_swift have gained functionality and we've leaned further into using Bazel and diverged from the standard xcodebuild toolchain, rules_ios is serving less of a purpose, and adds unnecessary complexity to our build.

Migration path

rules_ios contains a few different features you may be relying on. Here's what we suggest for a migration path:

• Mixed-language libraries
  • rules_swift now has a mixed_language_library macro and rule that works similarly to rules_ios's apple_framework. The biggest difference is that the target created by rules_swift's macro is not a "packaging target" with a transition attached to build the library for a particular platform. If you want to build a mixed-source library in isolation, you'll need to use an ios_build_test target.
  • In the upstream version of rules_swift published by Google, there is initial work on a rule to support mixed-language libraries. We plan on eventually migrating to that.
• Header maps
  • These enable importing headers under a common namespace (#import "Header.h" or #import "Module/Header.h"), instead of using their actual path under Bazel's execroot (#import "some/path/to/Module/some/path/to/header/Header.h").
  • There is a rule for creating header maps in rules_apple, which can be used with mixed_language_library or objc_library. We are still iterating on the best way to use this rule, and may simply migrate towards using fully-qualified imports.
• precompiled_apple_resource_bundle
  • There is an equivalent rule in rules_apple.
• Dynamic frameworks
  • rules_ios used the same macro for frameworks containing static and dynamic libraries, with a link_dynamic parameter to switch between the linking behavior. We recommend migrating to rules_apple's ios_framework for dynamic frameworks, as described in the documentation.
• Xcode build settings (xcconfig)
  • rules_ios takes a best-effort approach to converting Xcode's build settings into equivalent clang/swiftc compiler options or Bazel features when possible. We recommend getting rid of Xcode build settings in favor of using Bazel's configuration options directly.
  • One common use case for xcconfig was to substitute values in Info.plist and entitlements files; we recommend using expand_template as described in this issue or this blog post.

If you have any questions, feel free to ask them here or reach out in the #rules_ios channel in the Bazel Slack workspace.

[iMostfa]

Thanks for sharing,
here are some notes about the migration process that i have taken regarding the migration, specially mixed language ones.

i think we can make a PR with all the learnings here ?

Expand notes

Bazel-Migration of rules_ios

Most of the rules inside rules rules_ios were already implemented in rules_apple or rules_swift.
Notably there's no 1:1 mapping for apple_framework rule in rules_apple which is the most commonly used rule in rules_ios.

To migrate from rules_ios to rules_apple and rules_swift we consider three different scenarios:

1. Third party dependencies compiled using apple_framework rule
2. Swift code compiled using apple_framework rule
3. Mixed language targets (Swift + Objective-C) compiled using apple_framework rule

Third party dependencies compiled using apple_framework rule

A lot of BUILD file generators used to generate apple_framework rules for third party dependencies.
The following options are bailable to migrate these targets:

1. Use rules_swift_packageManger which generates a target for any dependency declared in a Package.swift file.

import PackageDescription

let package = Package(
    name: "ProjectName",
    dependencies: [
        .package(url: "https://github.com/airbnb/lottie-spm.git", exact: "4.5.1"),
])

// $ swift package update
// $ bazel mod tidy
// $ use it in your deps "@swiftpkg_lottie_spm//:Lottie"

Most of the time third party dependencies are already available as Swift Packages so this is the most straightforward way to migrate these targets, if there's any compilation issue a patch mechanism is supported through swift_package_manager rule.

By definition any SPM package will just work, doesn't matter if it's swift only or mixed language package.

2. Use apple_dynamic_xcframework_import/apple_dynamic_framework_import
   If the library is available as a pre_compiled binary. Like vendor libs or Realm Database you can link it directly to your target.

load("@build_bazel_rules_apple//apple:apple.bzl", "apple_dynamic_framework_import")

apple_dynamic_framework_import(
    name = "Realm",
    framework_imports = glob([
      "Realm.xcframework/ios-arm64_x86_64-simulator/NethoneSDK.framework/**",
    ]),
    visibility = [
    "//visibility:public",
    ],
    )

By doing so you should be able to migrate all third party dependencies compiled using apple_framework rule, it's important to migrate third party dependencies first before migrating your own code.

Migrating Swift code compiled using apple_framework rule

To migrate Swift code compiled using apple_framework rule you can use swift_library rule from rules_swift and then wrap the target using
ios_build_test to test that the compilation works

load("@build_bazel_rules_apple//apple:ios.bzl", "ios_build_test")
load("@build_bazel_rules_swift//swift:swift.bzl", "swift_library")

swift_library(
    name = "MySwiftLib",
    srcs = glob([
      "Sources/MySwiftLib/**/*.swift",
    ]),
    module_name = "MySwiftLib",
    visibility = ["//visibility:public"],
    deps = [
    "@swiftpkg_lottie_spm//:Lottie",
    "//path/to/dependency2",
    ],
    )

ios_build_test(
    name = name + ".iOS",
    minimum_os_version = "16.0",
    targets = [":" + name])

NOTE: that any other target like swift_library, ios_application can depend on the swift_library target, ios_build_test is just a wrapper to test that the compilation works.

WARN: You will find a lot of missing imports errors, this is because by default rules_ios used to implicitly include some dependencies like UIKit or Foundation while rules_swift requires you to explicitly import them in your swift files, so expect that you add a lot of import UIKit, import Foundation, import XCTest ..etc

Migrating Mixed language targets (Swift + Objective-C)

This is likely the most complex cases to migrate

if you have a swift_library that's exposing some classes to objective-c targets (mixed_language_library or objc_library)

Make sure to add generates_header = True and generated_header_name = "BazelGenerated/FeatureFlagsService-Swift.h to swift library rule

swift_library(
    name = "FeatureFlagsService",
    srcs = glob([
      "Sources/FeatureFlagsService/**/*.swift",
    ]),
    module_name = "FeatureFlagsService",
    generates_header = True,
    generated_header_name = "BazelGenerated/FeatureFlagsService-Swift.h",
    visibility = ["//visibility:public"],
    deps = [
    "//path/to/dependency2",
    ],
    )

By doing so you can import the generated header in your objective-c code:

#if __has_include("BazelGenerated/FeatureFlagsService-Swift.h")
#include "BazelGenerated/FeatureFlagsService-Swift.h"
#endif

NOTE: If you don't speicify generated_header_name it will be HeaderName-Swift.h by default where HeaderName is the name of the target with camel case conversion. but in some cases you might want to have a custom path for the generated header to avoid conflicts.

objc_library/mixed_language_library that's consuming some swift_library which contains objc code from swift_library

If your swift library is used in a deeper dependency tree you might face issues with generated headers not being found.
To solve it you can add an option in swift_library to propagate the module map for generated module maps

swift_library(
    name = "FeatureFlagsService",
    srcs = glob([
      "Sources/FeatureFlagsService/**/*.swift",
    ]),
    module_name = "FeatureFlagsService",
    generates_header = True,
    generated_header_name = "BazelGenerated/FeatureFlagsService-Swift.h",
    visibility = ["//visibility:public"],
    deps = [
    "//:CommonUISDK", //<- Swift library that contains objc code
    ],

Basically this will solve errors like this one

In file included from <module-includes>:1:
bazel-out/ios_sim_arm64-fastbuild-ios-sim_arm64-min16.0-applebin_ios-ST-5cb69ec9a0ed/bin/ModulaA_modulemap/_/../../../../../bazel-out/ios_sim_arm64-fastbuild-ios-sim_arm64-min16.0-applebin_ios-ST-5cb69ec9a0ed/bin/BazelGenerated/ModuleA-Swift.h:283:9: fatal error: module 'FeatureFlagsService' not found
  283 | @import FeatureFlagsService;
      |  ~~~~~~~^~~~~~~~~~~~~~~~~~~~~~
path/to/some/file.m:15:9: fatal error: could not build module 'CommonUISDK'
   15 | @import CommonUISDK;
      |  ~~~~~~~^~~~~~~~
2 errors generated.
Error in child process '

mixed_language_library

Finally, if you have a target where both swift and objective-c code are mixed together you can use mixed_language_library rule from rules_apple

mixed_language_library(
    name = "MyMixedLib",
    clang_copts = [
        "-w",
        # you might want to add some header search paths here via "-ISearchPath/file"
        "-I",
    clang_srcs = [
        "MixedAnswer.m",
        "MixedAnswerPrivate.m",
        "MixedAnswerPrivate.h",
    ],
    enable_modules = True,
    module_name = "MixedAnswer",
    swift_srcs = [
        "MixedAnswer.swift",
    ],
    module_name = "MyMixedLib",
    visibility = ["//visibility:public"],
    deps = [
    "//path/to/dependency2",
    ],
    )

WARN: mixed_language_library swift types exposed to objc with @objc will need to be public.