[swift-build-dev] [Proposal] Lock file for Swift Package Manager

[Ankit Agarwal]

agreed that .lock extension might be misleading and should be renamed to
Package-resolved.extension

 Do you have specific reason for considering json/json like format or
just want to stay scaleable in case of future requirements in that file?
As of now I am not sure what could be added more to the file except URL and
resolved version...perhaps resolved version range? but idk if that's
important to be written to file.

On Tuesday 5 January 2016, Max Howell <max.howell at apple.com> wrote:

> To some length I have discussed the filename issue with Rick and I think I
> agree with him that `.lock` was a bad choice from the packaging community
> in general.
>
> This is a command line tool and there is a long history of .lock files
> meaning “the file is locked because it is in use, do not edit the file
> without the .lock extension” on UNIX.
>
> Carthage agreed, they chose ‘.resolved’.
>
> NPM creates a “npm-shrinkwrap.json” file (although it will only do this on
> demand). I like the name “shrink-wrap” since it conveys the ‘sealed’ nature
> of the process.
>
> We should consider using a proper format like JSON and using its extension
> too.
>
> On Jan 4, 2016, at 1:17 PM, Ankit Agarwal <ankit at ankit.im
> <javascript:_e(%7B%7D,'cvml','ankit at ankit.im');>> wrote:
>
> Hi
> any updates on this?
>
> On Wednesday 23 December 2015, Ankit Agarwal <ankit at ankit.im
> <javascript:_e(%7B%7D,'cvml','ankit at ankit.im');>> wrote:
>
>> Thank you all for the valuable feedback I have updated the proposal to
>> reflect the changes which are agreed upon by majority. Please go through
>> the updated proposal below and provide more feedback.
>>
>>
>> Lock File for Swift Package ManagerIntroduction
>>
>> A Package.lock file containing list of resolved dependencies generated by
>> swiftpm.
>> Motivation
>>
>> Package.lock 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(including minor and patch) 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 Package.lock file after resolving the
>> dependency graph for that package in some simple format.
>> Detailed DesignPackage.lock aka the lock file
>>
>> Package.lock is a plain text auto-generated file containing list of
>> resolved dependencies: one line per dependency in format
>>
>>  <gitURL> <resolvedVersion>
>>
>> "github.com/foo/bar" "v1.1"
>> "../mygitdir" "v2.3"
>> "github.com/my/forked/dep" "8b3989be184375ae6e84e8a0254e5258789b23e5"
>>
>>
>>    - Package.lock will always contain the exact version of the
>>    dependency resolved by SPM
>>    - 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 SPM so it might make sense to:
>>
>>    - not to use swift syntax in this file.
>>    - keep it seperate from Package.swift to avoid confusion for new
>>    users.
>>
>> Another option could be using very minimal valid swift syntax for eg :
>>
>> [
>>  ("github.com/foo/bar", "v1.1"),
>>  ("../mygitdir","v2.3"),
>>  ("github.com/my/forked/dep","8b3989be184375ae6e84e8a0254e5258789b23e5")
>> ]
>>
>> Workflow$ swift build :
>>
>>    -
>>
>>    Dependencies declared in Package.swift and Package.lock is not
>>    present :
>>
>>    Resolves Package.swift and generates Package.lock; uses the generated
>>    Package.lock to fetch and build the dependencies
>>    -
>>
>>    Package.lock already present :
>>
>>    Uses the generated Package.lock to fetch and build the dependencies.
>>
>>    if Package.swift has been modified SPM generates a warning for user
>>    to consider updating the lock file using $ swift build --update (explained
>>    below)
>>    -
>>
>>    Packages/ is out of sync with lock file :
>>
>>    *Uncommited changes in Packages/* : User is probably trying to modify
>>    the dep so suggest him to use the $ swift build --ignore-lock command
>>    (explained below)
>>
>>    *Commited changes in Packages/* : User is done making changes in the
>>    dependency but forgot to lock them so HEADs don't match, suggest him to use $
>>    swift build --lock command (explained below)
>>
>> $ swift build --update :
>>
>>    - Remove current Package.lock if present and re-resolve Package.swift
>>    to generate a new Package.lock file for all the deps.
>>    - To update only one dependency use $ swift build --update=<dep_name>
>>
>> $ swift build --lock :
>>
>>    - Locks the current HEAD packages in Packages/ and writes them into
>>    the lock file uses tags where available otherwise refs
>>    - To lock only one dependency use $ swift build --lock=<dep_name>
>>
>> $ swift build --ignore-lock :
>>
>>    - Ignores the lock file and use HEAD of Package/ to build the deps
>>    without writing to lock file
>>    - Useful for development
>>
>> Workflow for Pointing a dependency to an untagged commit
>>
>>    - Create Package.swift and declare dependencies
>>    - Run $ swift build to resolve and build the Package
>>    - Modify and play with the checkedout dependencies in Packages/
>>    - Commit and push the changes to the git remote mentioned in
>>    Package.swift
>>    - Once satisfied with the current state of a package lock it using $
>>    swift build --lock=<dep_name>
>>    - Commit the lock file and push for others to use
>>
>> 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.
>>
>>
>>
>>
>>
>
> --
> Ankit
>
>
>
>

-- 
Ankit
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-build-dev/attachments/20160105/d3f9f823/attachment.html>