Menu

Getting Started

System Requirements

Skip requires a macOS 13 development machine with Xcode 15, Android Studio 2023, and Homebrew installed.

Installation

Install Skip by running the Terminal command:

brew install skiptools/skip/skip

This will download and install the skip tool itself, as well as gradle and JDK dependencies that are necessary for building and testing the Kotlin/Android side of your apps.

Ensure that the development prerequisites are satisfied by running:

skip checkup

If the checkup passes, you’re ready to start developing with Skip!

Creating an App

Create a new app project with the command:

skip init --open-xcode --appid=bundle.id project-name AppName

For example:

skip init --open-xcode --appid=com.xyz.HelloSkip hello-skip HelloSkip

This will create a hello-skip/ folder with a new SwiftPM package containing a single module named HelloSkip, along with a HelloSkip.xcodeproj project with a HelloSkipApp target and an .xcconfig file specifying the app’s name, bundle identifier, and other customizable metadata.

Xcode will open the new project, but before you can build and launch the transpiled app, an Android emulator needs to be running. Launch Android Studio.app and open the Virtual Device Manager from the ellipsis menu of the Welcome dialog. From there, Create Device (e.g., “Pixel 6”) and then Launch the emulator.

Once the Android emulator is running, select and run the HelloSkipApp target in Xcode. The first build will take some time to compile the Skip libraries, and you may be prompted with a dialog to affirm that you trust the Skip plugin. Once the build and run action completes, the SwiftUI app will open in the selected iOS simulator, and at the same time the transpiled app will launch in the currently-running Android emulator.

Browse to the ContentView.swift file and make a small change and re-run the target: the app will be re-built and re-run on both platforms simultaneously with your changes.

See the product documentation for further information developing with Skip. Happy Skipping!

Creating a Multi-Module App

Skip is designed to accommodate and encourage using multi-module projects. The default skip init command creates a single-module app for simplicity, but you can create a modularized project by specifying additional module names at the end of the chain. For example:

skip init --open-xcode --appid=com.xyz.HelloSkip multi-project HelloSkip HelloModel HelloCore

This command will create a SwiftPM project with three modules: HelloSkip, HelloModel, and HelloCore. The heuristics of such module creation is that the modules will all be dependent on their subsequent peer module, with the first module (HelloSkip) having an initial dependency on SkipUI, the second module depending on SkipModel, and the final module in the chain depending on SkipFoundation. The Package.swift file can be manually edited to shuffle around dependencies, or to add new dependencies on external Skip frameworks such as the nascent SkipSQL or SkipXML libraries.

Creating a Dual-Platform Library

Skip library projects are pure SwiftPM packages that encapsulate common functionality. Each of the core Skip compatibility frameworks (skip-lib, skip-unit, skip-foundation, and skip-ui) are Skip library projects. Other commonly-used projects include skip-sql, skip-script, and skip-zip.

A new library can be created and opened with:

skip init --build --test lib-name ModuleName

This will create a new lib-name folder containing a Package.swift with targets of ModuleName and ModuleNameTests.

This project can be opened in Xcode.app, which you can use to build and run the unit tests. Running swift build and swift test from the Terminal can also be used for headless testing as part of a continuous integration process.

Skip Project structure

lib-name
├── Package.resolved
├── Package.swift
├── README.md
├── Sources
│   └── ModuleName
│       ├── ModuleName.swift
│       ├── Resources
│       │   └── Localizable.xcstrings
│       └── Skip
│           └── skip.yml
└── Tests
    └── ModuleNameTests
        ├── ModuleNameTests.swift
        ├── Resources
        │   └── TestData.json
        ├── Skip
        │   └── skip.yml
        └── XCSkipTests.swift

Skip Package.swift structure

// swift-tools-version: 5.8
import PackageDescription

let package = Package(
    name: "lib-name",
    defaultLocalization: "en",
    platforms: [.iOS(.v16), .macOS(.v13), .tvOS(.v16), .watchOS(.v9), .macCatalyst(.v16)],
    products: [
        .library(name: "ModuleName", targets: ["ModuleName"]),
    ],
    dependencies: [
        .package(url: "https://source.skip.tools/skip.git", from: "0.7.1"),
        .package(url: "https://source.skip.tools/skip-foundation.git", from: "0.0.0"),
    ],
    targets: [
        .target(name: "ModuleName", plugins: [.plugin(name: "skipstone", package: "skip")]),
        .testTarget(name: "ModuleNameTests", dependencies: ["ModuleName"], plugins: [.plugin(name: "skipstone", package: "skip")]),
    ]
)

Troubleshooting

Skip’s architecture relies on recent advances in the plugin system used by Xcode 15 and Swift Package Manager 5.9. When unexpected issues arise, often the best first step is to clean your Xcode build (Product → Clean Build Folder) and reset packages (File → Packages → Reset Package Caches). Restarting Xcode is sometimes warranted, and trashing the local DerivedData/ folder might even be needed.

Specific known error conditions are listed below. Search the documentation, issues, and discussions for more information and to report problems.

Join our Mailing List

Sign up to be notified about Skip news, releases, and special offers.