Lock file proposal

Lockfile.md

Lock File for Swift Package Manager

Introduction

A Lockfile file locking the state of resolved dependencies generated by swiftpm.

Motivation

Lockfile file can be helpful in situations like :

Reproduce exact versions of dependencies on different machine

• Multiple developers working on a package would want to use the exact versions of the dependencies declared in the manifest file
• When a build is being performed on a remote machine eg CI

Pointing a dependency to an untagged commit

Sometimes it might be helpful to lock a dependency to a particular commit ref for which a tagged version is unavailable in cases such as :

• Forking a 3rd party library and making it swiftpm compatible for temporary use until officially supported by the author
• Package is in active development and not ready for a release tag

Proposed Solution

swiftpm generates a simple Packages/Lockfile file after resolving the dependency graph for that package in some simple format.

Detailed Design

Git Submodules

• Use git submodules to manage the locks for the dependencies
• This will allow developers more power over this feature and enables greater understanding over what happens
• User can navigate to the package directories and checkout any ref needed
• Once the modifications are made the lock file can be generated by executing command $ swift build --lock
• It shouldn't be possible to build with modifications without generating a new lock file or perhaps with $ swift build --ignore-lock

###Lockfile

• Rationale for the name and location of the lockfile: it no longer seems to be a UNIX-style lockfile for the Package.swift file and it more clearly shows what precisely is being locked while continuing the perhaps unwise tradition of naming the file a lockfile

• Contains the diff of any local changes made in Packages/ not pinned to a commit. This ensures that we:

  1. Encourage users to edit, fix and improve their packages

  2. Their changes get checked in and thus other people using the Package absolutely will get these changes without them having to explicitly publish their changes somewhere accessible to their whole team.

• The format to be used for Lockfile is TBD

• User is expected to commit the lock file into the git repo for others to reproduce the exact versions of dependencies on their system

• lock file of dependencies are ignored and only their Package.swift is taken into consideration for resolving all the dependencies

• User is not expected to interact with this file as it'll always be generated by SwiftPM.

##Workflow

$ swift build :

• Errors out if lock file not present
• If lock file is present and no modifications are detected in current state of Packages then proceed with the build
• If modifications are detected, suggest user to update the lock file

$ swift build --lock :

• Locks the current HEAD packages in Packages/ and add/update them as submodules
• If there a modifications and uncommited changes, store the diff inside lockfile

$ swift build --ignore-lock :

• Ignores the lock file and use current state of Package/ to build the deps without writing to lock file
• Useful for development

If a dependency(foo) is using a dependency(bar) with an untagged commit

• Author of foo mentions in their readme that they're using bar on an untagged commit
• Package(baz) wanting to use foo and bar both will need to lock his bar package to same untagged commit

Impact on existing code

None on the code but old users will not be able to run $ swift build with changes in their Packages/ which is possible right now, they'll need to use $ swift build --ignore-lock instead which will be communicated using warnings as stated above.

##Alternatives Considered

One alternative is to allow mentioning refs in manifest file while declaring a dependency but as discussed in this thread it might not be the best idea.