Skip to main content

​
Prerequisites

Before building List from source, ensure you have the following installed:

Swift 6.2+

Required Swift version for building the project

macOS 13+

Minimum platform version for macOS builds

Git

For cloning the repository

Xcode (macOS)

Recommended for macOS development
List supports both macOS and Linux platforms. On Linux, you’ll need to install Swift 6.2+ using Swiftly or your distribution’s package manager.

​
Quick Start

1

Clone the Repository

Clone the List repository from GitHub:
git clone https://github.com/mac9sb/list.git
cd list
2

Build the Project

Build List using Swift Package Manager:
swift build
This creates a debug build in .build/debug/sls.
3

Run Tests

Verify your build by running the test suite:
swift test
4

Install (Optional)

Install the built binary to your system:
cp .build/debug/sls /usr/local/bin/
Or for a release build:
swift build -c release
cp .build/release/sls /usr/local/bin/

​
Build Configurations

​
Debug Build

The debug build includes debugging symbols and is not optimized: 
swift build
The executable is located at .build/debug/sls.

​
Release Build

The release build is optimized for production use: 
swift build -c release
The executable is located at .build/release/sls.
Release builds are significantly faster and have a smaller binary size. Use release builds for production deployments.

​
Architecture-Specific Builds

On macOS, you can build for specific architectures: 
# Build for x86_64 (Intel)
swift build -c release --arch x86_64

# Build for arm64 (Apple Silicon)
swift build -c release --arch arm64

​
Platform-Specific Instructions

​
macOS Build

  1. Ensure you have Xcode Command Line Tools installed: 
    xcode-select --install
  2. Verify Swift version: 
    swift --version
# Should be 6.2 or later
  3. Build the project: 
    swift build -c release
  4. The binary will be at .build/release/sls

​
Advanced Build Tasks

​
Generating Documentation

List uses Swift-DocC for documentation generation: 
swift package generate-documentation
This generates DocC documentation for the project’s API.
The project uses the swift-docc-plugin (version 1.4.3+) for documentation generation.

​
Running Specific Tests

Run the entire test suite: 
swift test
Run tests with verbose output: 
swift test --verbose

​
Clean Build Artifacts

Remove build artifacts to start fresh: 
swift package clean
Or manually remove the build directory: 
rm -rf .build

​
Troubleshooting

Problem: Error about Swift version compatibility.Solution: Ensure you’re using Swift 6.2 or later:
swift --version
Update Swift using Xcode (macOS) or Swiftly (Linux).
Problem: Build fails with missing package dependencies.Solution: Resolve and update dependencies:
swift package resolve
swift package update
Problem: Build errors on Linux systems.Solution: Ensure you have the required system libraries:
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install libsqlite3-dev libncurses5-dev

# Fedora/RHEL
sudo dnf install sqlite-devel ncurses-devel
Problem: Cannot copy binary to /usr/local/bin/.Solution: Use sudo or choose a user-writable location:
# With sudo
sudo cp .build/release/sls /usr/local/bin/

# Or install to user directory
mkdir -p ~/.local/bin
cp .build/release/sls ~/.local/bin/
# Add ~/.local/bin to your PATH
Problem: Test suite fails during build verification.Solution: Ensure you’re in the project root and have a clean build:
swift package clean
swift build
swift test
Check that file permissions are correct in the Tests directory.

​
Dependencies

List relies on the following Swift packages:
PackageVersionPurpose
swift-argument-parser1.0.0+Command-line argument parsing
swift-docc-plugin1.4.3+Documentation generation
swift-testing0.11.0+Modern Swift testing framework
These dependencies are automatically fetched during the build process.

​
Next Steps

Architecture

Learn about the project structure and design

Contributing

Start contributing to the project

Build docs developers (and LLMs) love

Get started for freeTalk to us