You can open this sample in an IDE that supports Gradle.

This guide demonstrates how to create a Swift library with Gradle using gradle init. You can follow the guide step-by-step to create a new project from scratch or download the complete sample project using the links above.

What you’ll build

You’ll generate a Swift library that follows Gradle’s conventions.

What you’ll need

Create a project folder

Gradle comes with a built-in task, called init, that initializes a new Gradle project in an empty folder. The init task uses the (also built-in) wrapper task to create a Gradle wrapper script, gradlew.

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

$ mkdir demo
$ cd demo

Run the init task

From inside the new project directory, run the init task using the following command in a terminal: gradle init. When prompted, select the 2: library project type and 6: Swift as the implementation language. Next you can choose the DSL for writing buildscripts - 1 : Kotlin or 2: Groovy. For the other questions, press enter to use the default values.

The output will look like this:

$ gradle init

Select type of build to generate:
  1: Application
  2: Library
  3: Gradle plugin
  4: Basic (build structure only)
Enter selection (default: Application) [1..4] 2

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

Project name (default: demo):

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

Generate build using new APIs and behavior (some features may change in the next minor release)? (default: no) [yes, no]

BUILD SUCCESSFUL
1 actionable task: 1 executed

The init task generates the new project with the following structure:

├── gradle (1)
│   ├── libs.versions.toml (2)
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew (3)
├── gradlew.bat (3)
├── settings.gradle.kts (4)
└── lib
    ├── build.gradle.kts (5)
    └── src
        ├── main
        │   └── swift (6)
        │       └── Hello.swift
        └── test
            └── swift (7)
                └── HelloTests.swift
                └── LinuxMain.swift
├── gradle (1)
│   ├── libs.versions.toml (2)
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew (3)
├── gradlew.bat (3)
├── settings.gradle (4)
└── lib
    ├── build.gradle (5)
    └── src
        ├── main
        │   └── swift (6)
        │       └── Hello.swift
        └── test
            └── swift (7)
                └── HelloTests.swift
                └── LinuxMain.swift
1 Generated folder for wrapper files
2 Generated version catalog
3 Gradle wrapper start scripts
4 Settings file to define build name and subprojects
5 Build script of lib project
6 Default Swift source folder
7 Default Swift test source folder

You now have the project setup to build a Swift library.

Review the project files

The settings.gradle(.kts) file has two interesting lines:

settings.gradle.kts
rootProject.name = "demo"
include("lib")
settings.gradle
rootProject.name = 'demo'
include('lib')

  • rootProject.name assigns a name to the build, which overrides the default behavior of naming the build after the directory it’s in. It’s recommended to set a fixed name as the folder might change if the project is shared - e.g. as root of a Git repository.

  • include("lib") defines that the build consists of one subproject called lib that contains the actual code and build logic. More subprojects can be added by additional include(…​) statements.

Our build contains one subproject called lib that represents the Swift library we are building. It is configured in the lib/build.gradle(.kts) file:

lib/build.gradle.kts
plugins {
    `swift-library` (1)
    xctest (2)
}

library {
    targetMachines.add(machines.linux.x86_64) (3)
}
lib/build.gradle
plugins {
    id 'swift-library' (1)
    id 'xctest' (2)
}

library {
    targetMachines.add(machines.linux.x86_64) (3)
}
1 Apply the swift-library plugin to add support for building Swift libraries
2 Apply the xctest plugin to add support for building and running Swift test executables (Linux) or bundles (macOS)
3 Set the target operating system and architecture for this library

The file src/main/swift/Hello.swift is shown here:

Generated src/main/swift/Hello.swift
/*
 * This source file was generated by the Gradle 'init' task
 */

class Hello {
    public func greeting() -> String {
        return "Hello, World!"
    }
}

The generated test, src/test/swift/Hello.swift is shown next:

Generated src/test/swift/HelloTests.swift
/*
 * This source file was generated by the Gradle 'init' task
 */

import XCTest
@testable import Lib

class HelloTests: XCTestCase {
    public static let allTests = [
        ("testGreeting", testGreeting),
    ]

    func testGreeting() {
        XCTAssertEqual("Hello, World!", Hello().greeting())
    }
}

The generated test class has a single XCTest test. The test instantiates the Hello class, invokes a method on it, and checks that it returns the expected value.

Build the library

$ ./gradlew build

BUILD SUCCESSFUL in 0s
4 actionable tasks: 4 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.
Gradle integrates with several IDEs: Visual Studio, Xcode and Clion. To learn more, have a look at their respective linked documentation to configure those IDE integration in your project.

Publish a Build Scan

The best way to learn more about what your build is doing behind the scenes, is to publish a build scan. To do so, just run Gradle with the --scan flag.

$ ./gradlew build --scan

BUILD SUCCESSFUL in 0s
4 actionable tasks: 4 executed

Publishing a build scan to scans.gradle.com requires accepting the Gradle Terms of Service defined at https://gradle.com/terms-of-service.
Do you accept these terms? [yes, no] yes

Gradle Terms of Service accepted.

Publishing build scan...
https://gradle.com/s/5u4w3gxeurtd2

Click the link and explore which tasks where executed, which dependencies where downloaded and many more details!

Summary

That’s it! You’ve now successfully configured and built a Swift library project with Gradle. You’ve learned how to:

  • Initialize a project that produces a Swift library

  • Build the library, which includes running its tests

Next Steps