Project structure and Swift Package Manager basics - Deep Dive

Overview - Project structure and Swift Package Manager basics

What is it?

Project structure in Swift organizes your code and resources into folders and files so everything is easy to find and manage. Swift Package Manager (SPM) is a tool that helps you build, test, and share Swift code by managing dependencies and project setup automatically. It creates a standard layout for your project and handles downloading and linking external libraries. This makes working on Swift projects smoother and more consistent.

Why it matters

Without a clear project structure and a tool like Swift Package Manager, managing code becomes confusing and error-prone, especially as projects grow or when using code from others. SPM solves the problem of manually handling dependencies and build settings, saving time and reducing mistakes. This means developers can focus on writing code instead of fixing setup issues, leading to faster and more reliable app development.

Where it fits

Before learning this, you should know basic Swift programming and how to write simple programs. After this, you can learn advanced package management, continuous integration, and how to publish Swift packages for others to use.

Mental Model

Core Idea

Swift Package Manager organizes your Swift code and its dependencies into a clear, standard structure that the tool understands and builds automatically.

Think of it like...

Think of your project like a recipe book. The project structure is how you organize recipes into chapters and pages, and Swift Package Manager is like a kitchen assistant who gathers all the ingredients (code libraries) you need and prepares everything so you can cook without searching for items.

Project Root
├── Sources
│   └── YourCode.swift
├── Tests
│   └── YourCodeTests.swift
├── Package.swift
└── README.md

Package.swift: The recipe card telling SPM what to build and what ingredients (dependencies) to fetch.

Build-Up - 6 Steps

1

Foundation

Understanding basic project folders

Concept: Learn the main folders used in a Swift package project.

A Swift package usually has a 'Sources' folder for your main code and a 'Tests' folder for test code. Each folder contains Swift files grouped by functionality. This simple layout helps keep code organized and easy to find.

Result

You know where to put your code and tests so the project stays neat and understandable.

Knowing the standard folders prevents confusion and helps tools like SPM find your code automatically.

2

Foundation

Role of Package.swift file

Concept: Understand the purpose of the Package.swift file in a Swift package.

Package.swift is a special file written in Swift that describes your package. It lists your package name, the code targets, dependencies on other packages, and supported platforms. SPM reads this file to know how to build your project.

Result

You can see how SPM knows what to build and which external code to include.

Recognizing Package.swift as the project’s blueprint clarifies how SPM automates building and dependency management.

3

Intermediate

Adding dependencies with SPM

🤔Before reading on: do you think adding a dependency requires manual download or SPM handles it automatically? Commit to your answer.

Concept: Learn how to add external libraries to your project using Swift Package Manager.

In Package.swift, you add dependencies by specifying URLs of other Swift packages and version rules. When you build, SPM downloads and links these automatically. This saves you from manually copying code or setting up complex build settings.

Result

Your project can use code from others easily and safely, with SPM managing versions and updates.

Understanding automatic dependency resolution shows how SPM reduces errors and saves time in managing external code.

4

Intermediate

Building and testing with SPM commands

🤔Before reading on: do you think SPM commands only build code or also run tests? Commit to your answer.

Concept: Discover how to use SPM commands to build and test your Swift package.

SPM provides simple commands like 'swift build' to compile your code and 'swift test' to run your tests. These commands work from the terminal and use the project structure and Package.swift to know what to do.

Result

You can quickly compile and verify your code without opening an IDE or writing complex scripts.

Knowing these commands empowers you to automate and control your build and test process efficiently.

5

Advanced

Customizing targets and products

🤔Before reading on: do you think a package can have multiple products or just one? Commit to your answer.

Concept: Learn how to define multiple targets and products in Package.swift for modular code.

Targets are groups of source files compiled together. Products are what your package offers to others, like libraries or executables. You can define multiple targets and products in Package.swift to organize code and control what is exposed outside the package.

Result

Your package can be modular, with clear boundaries and reusable parts.

Understanding targets and products helps you design scalable and maintainable Swift packages.

6

Expert

SPM’s integration with Xcode and CI

🤔Before reading on: do you think SPM projects need manual setup in Xcode or integrate automatically? Commit to your answer.

Concept: Explore how Swift Package Manager works seamlessly with Xcode and continuous integration systems.

Xcode can open Swift packages directly, recognizing Package.swift and project structure without extra setup. Also, CI tools like GitHub Actions can run 'swift build' and 'swift test' commands to automate testing and building. This integration streamlines development and deployment.

Result

You can develop, test, and deliver Swift code efficiently using modern tools and automation.

Knowing SPM’s smooth integration with popular tools unlocks professional workflows and continuous delivery.

Under the Hood

Swift Package Manager reads the Package.swift manifest file to understand the package’s structure, dependencies, and build settings. It then downloads any external packages from their URLs, resolves version conflicts, and compiles all source files in the specified targets. SPM uses Swift’s compiler under the hood and links all code into libraries or executables. It also runs tests by discovering test cases in the Tests folder and executing them.

Why designed this way?

SPM was created to replace manual dependency management and inconsistent project setups in Swift. It uses a declarative manifest (Package.swift) so developers can describe their project in code, making it flexible and easy to maintain. The standard folder layout and integration with Swift’s compiler simplify tooling and reduce errors. Alternatives like CocoaPods or Carthage existed but were less integrated and more complex.

Package.swift (manifest)
       ↓
┌───────────────────────────┐
│ Swift Package Manager (SPM)│
└─────────────┬─────────────┘
              ↓
  ┌───────────┴───────────┐
  │ Dependency Resolver   │
  └───────────┬───────────┘
              ↓
  ┌───────────┴───────────┐
  │ Source Compiler & Linker│
  └───────────┬───────────┘
              ↓
      Build Artifacts (libs, executables)
              ↓
         Test Runner
              ↓
          Test Results

Myth Busters - 4 Common Misconceptions

Quick: Does SPM automatically update dependencies to the latest version every build? Commit yes or no.

Common Belief: SPM always fetches the newest version of dependencies every time you build.

Reality: SPM respects version rules in Package.swift and caches downloaded packages, so it only updates when you explicitly ask or when version constraints change.

Why it matters: Assuming automatic updates can cause unexpected bugs or break builds if dependencies change without control.

Quick: Can you put any folder name for source code in a Swift package? Commit yes or no.

Common Belief: You can name your source code folders anything you want in a Swift package.

Reality: SPM expects source code in a folder named 'Sources' and tests in 'Tests' by default; using other names requires extra configuration.

Why it matters: Wrong folder names cause build failures or missing code, confusing beginners.

Quick: Does SPM only work for libraries, not executable apps? Commit yes or no.

Common Belief: Swift Package Manager is only for building libraries, not apps you can run.

Reality: SPM can build both libraries and executable programs by defining appropriate products in Package.swift.

Why it matters: Limiting SPM to libraries prevents learners from using it for full app development.

Quick: Is Package.swift a static configuration file like JSON or YAML? Commit yes or no.

Common Belief: Package.swift is a static config file that you just edit like JSON or YAML.

Reality: Package.swift is a Swift source file that runs code to define the package, allowing dynamic logic if needed.

Why it matters: Thinking it’s static limits understanding of its flexibility and power.

Expert Zone

1

SPM’s manifest file is executable Swift code, so you can use variables and logic to customize package setup dynamically.

2

Dependency resolution uses semantic versioning rules, but understanding how version ranges interact can prevent subtle conflicts in large projects.

3

SPM caches dependencies globally, so multiple projects share downloaded packages, saving disk space and speeding up builds.

When NOT to use

SPM is not ideal for projects that require complex UI resources or non-Swift assets, where Xcode projects or other tools like CocoaPods might be better. Also, for legacy Objective-C projects, SPM support is limited.

Production Patterns

In production, teams use SPM to modularize large codebases into reusable packages, automate builds and tests in CI pipelines, and publish packages to public or private repositories for sharing across projects.

Connections

Dependency Injection

Builds-on

Understanding how SPM manages dependencies helps grasp dependency injection, where code dependencies are supplied externally to improve modularity and testing.

Makefile and Build Automation

Similar pattern

SPM automates building like Makefiles do for C projects, showing how build automation tools simplify compiling and linking code.

Supply Chain Management (Logistics)

Analogous process

SPM’s role in fetching and managing code dependencies is like supply chain management ensuring parts arrive on time for assembly, highlighting the importance of reliable sourcing.

Common Pitfalls

#1 Placing source files outside the 'Sources' folder

Wrong approach:

ProjectRoot/
MyCode.swift
Package.swift

Correct approach:

ProjectRoot/
Sources/
MyCode.swift
Package.swift

Root cause:

Misunderstanding SPM’s expected folder layout causes build errors because SPM cannot find source files.

#2 Forgetting to add a dependency in Package.swift but using its code

Wrong approach:

Using code from an external package without listing it in dependencies in Package.swift

Correct approach:

Adding the external package URL and version in dependencies array in Package.swift

Root cause:

Not declaring dependencies means SPM doesn’t download or link needed code, causing compile errors.

#3 Editing Package.swift with syntax errors

Wrong approach:

Package.swift with missing commas or wrong Swift syntax

Correct approach:

Carefully editing Package.swift using valid Swift syntax and testing with 'swift package describe'

Root cause:

Treating Package.swift like a plain config file instead of Swift code leads to syntax mistakes and build failures.

Key Takeaways

Swift Package Manager uses a standard project structure with 'Sources' and 'Tests' folders to organize code clearly.

The Package.swift file is a Swift script that defines your package’s name, targets, dependencies, and products.

SPM automatically downloads and manages external code libraries, saving you from manual setup and version conflicts.

You can build and test your Swift package easily using simple terminal commands like 'swift build' and 'swift test'.

SPM integrates smoothly with Xcode and continuous integration tools, enabling professional workflows and automation.