This guide demonstrates how to use Gradle’s Build Init plugin to produce a Swift library that follows Gradle conventions.

What you’ll need

Check the user manual

Gradle ships with the Build Init plugin, which provides an easy way to generate projects of various types using the the init task. This task will also execute the wrapper task to create a Gradle wrapper script, gradlew.

Setup

The first step is to create a folder for the new project and change directory into it.

$ mkdir building-swift-libraries
$ cd building-swift-libraries

Run the init task

From inside the new project directory, run the init task and select the library project type and the Swift language when prompted. For the other questions, press enter to use the default values.

$ gradle init

Select type of project to generate:
  1: basic
  2: application
  3: library
  4: Gradle plugin
Enter selection (default: basic) [1..4] 3

Select implementation language:
  1: C++
  2: Groovy
  3: Java
  4: Kotlin
  5: Scala
  6: Swift
Enter selection (default: Java) [1..6] 6

Select build script DSL:
  1: Groovy
  2: Kotlin
Enter selection (default: Groovy) [1..2] 1

Project name (default: building-swift-libraries):

> Task :init
Get more help with your project: https://docs.gradle.org/{gradle-version}/userguide/building_swift_projects.html

BUILD SUCCESSFUL
2 actionable tasks: 2 executed

If you prefer the Kotlin DSL, you can select kotlin for the build script DSL.

The init task runs the wrapper task first, which generates the gradlew and gradlew.bat wrapper scripts. Then it creates the new project with the following structure:

├── build.gradle
├── gradle          (1)
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
├── settings.gradle
└── src
    ├── main
    │   └── swift   (2)
    │       └── Hello.swift
    └── test
        └── swift   (3)
            ├── HelloTests.swift
            └── LinuxMain.swift
├── build.gradle.kts
├── gradle          (1)
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
├── settings.gradle.kts
└── src
    ├── main
    │   └── swift   (2)
    │       └── Hello.swift
    └── test
        └── swift   (3)
            ├── HelloTests.swift
            └── LinuxMain.swift
1 Generated folder for wrapper files
2 Default Swift source folder
3 Default Swift test folder
The Gradle source layout convention can be customized to fit any source layout. See the customizing Swift source section of the User Manual as well as the custom source layout sample for a demonstration.

Review the generated project files

The settings.gradle file is heavily commented, but has only one active line:

settings.gradle
/*
 * This file was generated by the Gradle 'init' task.
 *
 * The settings file is used to specify which projects to include in your build.
 *
 * Detailed information about configuring a multi-project build in Gradle can be found
 * in the user manual at https://docs.gradle.org/5.6-20190718104724+0000/userguide/multi_project_builds.html
 */

rootProject.name = 'building-swift-libraries'
settings.gradle.kts
/*
 * This file was generated by the Gradle 'init' task.
 *
 * The settings file is used to specify which projects to include in your build.
 *
 * Detailed information about configuring a multi-project build in Gradle can be found
 * in the user manual at https://docs.gradle.org/5.6-20190718104724+0000/userguide/multi_project_builds.html
 */

rootProject.name = "building-swift-libraries"

This sets the name of the root project to "building-swift-libraries", which overrides the default behavior of naming the project after the directory it’s in.

The generated build.gradle file also has many comments. The active portion is reproduced here:

build.gradle
/*
 * This file was generated by the Gradle 'init' task.
 *
 * This generated file contains a sample Swift project to get you started.
 * For more details take a look at the Building Swift applications and libraries chapter in the Gradle
 * User Manual available at https://docs.gradle.org/5.6-20190718104724+0000/userguide/building_swift_projects.html
 */

plugins {
    // Apply the swift-library plugin to add support for building Swift libraries
    id 'swift-library'

    // Apply the xctest plugin to add support for building and running Swift test executables (Linux) or bundles (macOS)
    id 'xctest'
}

// Set the target operating system and architecture for this library
library {
    targetMachines.add(machines.macOS.x86_64)
}
build.gradle.kts
/*
 * This file was generated by the Gradle 'init' task.
 *
 * This generated file contains a sample Swift project to get you started.
 * For more details take a look at the Building Swift applications and libraries chapter in the Gradle
 * User Manual available at https://docs.gradle.org/5.6-20190718104724+0000/userguide/building_swift_projects.html
 */

plugins {
    // Apply the swift-library plugin to add support for building Swift libraries
    `swift-library`

    // Apply the xctest plugin to add support for building and running Swift test executables (Linux) or bundles (macOS)
    xctest
}

// Set the target operating system and architecture for this library
library {
    targetMachines.add(machines.macOS.x86_64)
}

The build file adds the swift-library and xctest plugins:

  • The swift-library plugin automatically generates a library component configurable via the library extension DSL.

  • The xctest plugin automatically generates a bundle (on macOS) or an executable (on Linux) component that depends on the library. It also adds a new verification task that assembles and tests the binary. The XCTest component is configurable via the xctest extension DSL.

The xctest requires an executable entry point only on Linux. Gradle supports the LinuxMain.swift pattern out-of-the-box.

Execute the build

$ ./gradlew build
> Task :compileDebugSwift
> Task :linkDebug
> Task :assemble
> Task :compileTestSwift
> Task :linkTest
> Task :installTest
> Task :xcTest
> Task :test
> Task :check
> Task :build

BUILD SUCCESSFUL
6 actionable tasks: 6 executed
The first time you run the wrapper script, gradlew, there may be a delay while that version of gradle is downloaded and stored locally in your ~/.gradle/wrapper/dists folder.

The build task compiles the Swift sources, links the object files into a shared library, and runs the tests. To build a static library, please refer to the static library sample.

Dependencies on other projects isn’t covered in this guide. To learn more about this subject, have a look at the transitive dependency sample for a demonstration.
Publishing libraries to Maven repositories is outside the scope of this guide. To learn more about this subject, have a look at the simple library sample for a demonstration.
To learn more about Gradle’s Xcode integration and how to configure it, see the Gradle user guide.

Summary

You have created a Swift library with XCTest. In doing so, you saw:

  • How to generate a Swift libraries

  • How the generate build file and sample Swift files are structured

  • How to run the build with it’s tests

Next Steps

Help improve this guide

Have feedback or a question? Found a typo? Like all Gradle guides, help is just a GitHub issue away. Please add an issue or pull request to gradle-guides/building-swift-libraries and we’ll get back to you.