I would like to provide an update to the post from last month (LLVM monorepo transition), where I announced that Apple is working on the LLVM project monorepo transition plan for Swift.
Since then, Duncan (@dexonsmith), Mishal (@mishal_shah) and I have been working on creating the prototype monorepo that can be used by Swift. As a result of that work, the following four repositories have been created on github.com/apple:
- llvm-monorepo-root, a downstream fork of https://git.llvm.org/git/monorepo-root.git, which puts content at the “root” of the monorepo;
- llvm-project-v1, a WIP downstream fork of https://github.com/llvm/llvm-project, which has a number of branches that interleave the histories of swift-clang, swift-llvm, swift-compiler-rt, swift-clang-tools-extra, swift-libcxx, and llvm-monorepo-root;
apple-llvm-infrastructure-tools, a suite of tools called
git apple-llvmto help work with monorepos downstream of llvm.org (
git apple-llvm mt generatewas used to generate llvm-project-v1); and
- llvm-project-v1-split, which has some metadata related to generating llvm-project-v1.
More details follow on these repositories and how to work them them.
Prototype of the llvm-project monorepo
General Branch organization
There are three main branch prefixes:
- The prefix
llvm.org/is used to republish branches from github.com/llvm/llvm-project. They are exact replicas of upstream and are read-only.
- The prefix
apple/is used for branches that do not depend on the swift repository. These currently exclude all LLDB changes changes from upstream.
- The prefix
swift/is used for branches that do depend on the swift repository. For example, the branch swift/master depends on swift’s master branch.
There are no historical tags (yet), but we’d likely want them to have naming hierarchies within that to facilitate custom
Branches downstream of master
There are two branches downstream of llvm.org/master:
apple/master interleaves commits from each non-LLDB split repo’s
upstream-with-swiftbranch on top of llvm.org/master.
swift/master-next depends on swift’s master-next branch, and interleaves commits from LLDB’s upstream-with-swift branch with generated merges from
There are three (active) stable branches:
apple/stable/20190104 interleaves commits from each non-LLDB split repo’s
swift-5.1-branchbranch, and is named by the date of the branch point.
swift/swift-5.1-branch depends on swift’s swift-5.1-branch, and interleaves commits from LLDB’s swift-5.1-branch with generated merges from
swift/master depends on swift’s master branch, and interleaves commits from each split repo’s
stablebranch. This is downstream of swift/swift-5.1-branch.
There is also a suite of stable branches going back to swift/swift-5.1-branch.
Making the history canonical
It's unlikely the histories in llvm-project-v1 will become canonical since v1 will have problems that should be addressed before the monorepo is canonical. The idea is to regenerate it, fixed, as llvm-project-v2. Once all the blocking issues are resolved, the specific llvm-project-vX will be renamed to llvm-project. The old split repos will be archived past that point.
Using the prototype for development
Even though llvm-project-v1 is read-only, it can be used for development. Changes can be pushed back to the split repos using
git apple-llvm push .
Development workflows are still a work in progress. If you decide to try them out, be aware they could be full of bugs and that the branches in llvm-project-v1 may be overwritten with force pushes.
There’s also some documentation for using the monorepo with Swift’s
You can generate the HTML pages for the documentation by running the
make html target in the
We'll send another update when the blocking issues are resolved, and we think the monorepo is ready for everyone to switch over.
In the meantime, early adopters are encouraged to test it out, give feedback, and/or contribute to the tools.