This guide demonstrates how to use Gradle’s Build Init plugin to produce a Swift application 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-applications
$ cd building-swift-applications

Run the init task

From inside the new project directory, run the init task and select the application 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] 2

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

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

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

> 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)
    │       └── main.swift
    └── test
        └── swift    (3)
            ├── GreeterTests.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)
    │       └── main.swift
    └── test
        └── swift    (3)
            ├── GreeterTests.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-applications'
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-applications"

This sets the name of the root project to "building-swift-applications", 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-application plugin to add support for building Swift executables
    id 'swift-application'

    // 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 application
application {
    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-application plugin to add support for building Swift executables
    `swift-application`

    // 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 application
application {
    targetMachines.add(machines.macOS.x86_64)
}

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

  • The swift-application plugin automatically generates an application component configurable via the application extension DSL.

  • The xctest plugin automatically generates a bundle (on macOS) or an executable (on Linux) component that depends on the application. 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 :relocateMainForTest
> Task :linkDebug
> Task :installDebug
> Task :assemble
> Task :compileTestSwift
> Task :linkTest
> Task :installTest
> Task :xcTest
> Task :test
> Task :check
> Task :build

BUILD SUCCESSFUL
8 actionable tasks: 8 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, and runs the tests.

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.
To learn more about Gradle’s Xcode integration and how to configure it, see the Gradle user guide.

Application package

As part of the the build process, Gradle packages the main and test applications for distribution on other systems. The installDebug and installTest task copies the executable and generates a shell script for executing the application. The following shows the content of the build/install folder:

├── main
│   └── debug
│       ├── BuildingSwiftApplications         (1)
│       └── lib
│           └── BuildingSwiftApplications     (2)
└── test
    ├── BuildingSwiftApplicationsTest         (1)
    └── BuildingSwiftApplicationsTest.xctest  (3)
1 The script for executing the application variant
2 The main executable binary (debug variant)
3 The test bundle on macOS or test executable on Linux
When a build has dependencies, the dependent libraries are also copied into the installation folder. The shell scripts properly configure the library path so the package can be relocated. Have a look at the transitive dependency sample for a demonstration.

Run the application

Look at the build folder and you will notice the appearance of an exe folder. By convention, Gradle will place all executables in subfolders named according to the component name. In this case, you will find your assembled executable in build/exe/main/debug and it will be called BuildingSwiftApplications.

Now run your newly built executable.

$ ./build/exe/main/debug/BuildingSwiftApplications
Hello, World!

Summary

You have created an Swift application with XCTest. In doing so, you saw:

  • How to generate a Swift application

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

  • How to run the build with it’s tests

  • How to execute the application from the command line

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-applications and we’ll get back to you.