llvm-toolchain/debian

Organization of the repository
==============================

The debian package for each LLVM point release is maintained as a git branch.
For example, the 10 release lives at in the "10" branch.

The current snapshot release is maintained in the "snapshot" branch.

The easiest way to get all branches is probably to have one
clone per version:

for f in 8 9 10 snapshot; do
    git clone git@salsa.debian.org:pkg-llvm-team/llvm-toolchain.git -b $f $f
done

Steps for manually building a snapshot release
==============================================

1) Retrieve the latest snapshot and create original tarballs.

   Run the orig-tar.sh script,

     $ sh snapshot/debian/orig-tar.sh

   which will retrieve the latest version for each LLVM subproject (llvm,
   clang, lldb, etc.) from the main development (upstream github). and repack it
   as a set of tarballs.

2) Unpack the original tarballs and apply quilt debian patches.

   From the branches/ directory run the unpack.sh script,

     $ sh unpack.sh

   which will unpack the source tree inside a new directory such as
   branches/llvm-toolchain-snapshot_3.9~+20191018225217+3b123a2be6d.
   (date+hour+short git hash).
   Depending on the current snapshot version number and git release,
   the directory name will be
   different.

   Quilt patches will then be applied.

3) Build the binary packages using,

     $ fakeroot debian/rules binary

When debugging, successive builds can be recompiled faster by using tools such
as ccache (PATH=/usr/lib/ccache:$PATH fakeroot debian/rules binary).

Retrieving a specific branch or release candidate with orig-tar.sh
==================================================================

When using orig-tar.sh, if you need to retrieve a specific branch, you can pass
the branch name as the first argument. For example, to get the 10 release
branch at
  https://github.com/llvm/llvm-project/branches
you should use,

  $ sh 10/debian/orig-tar.sh release/10.x

To retrieve a specific release candidate, you can pass the branch name as the
first argument, and the tag rc number as the second argument. For example, to
get the 9.0.1 release candidate rc3 at
  https://github.com/llvm/llvm-project/tags
you should use,

  $ sh 10/debian/orig-tar.sh 10.0.1 rc3

For a stable release, the syntax is:

 $ sh 10/debian/orig-tar.sh 10.0.0


Additional maintainer scripts
=============================

The script qualify-clang.sh that is found at the git debian/ directory
should be used to quickly test a newly built package. It runs a short
set of sanity-check tests and regression tests.

The script releases/snapshot/debian/prepare-new-release.sh is used when
preparing a new point release. It automatically replaces version numbers
in various files of the package.

Making a change to all versions
===============================

Sometimes, we want to make a change on all branches.
In that case, start to make the change from the older
version (example: 8), then, change branch (example: 9) and
$ git merge origin/8
to retrieve the changes


Change in major upstream version
================================
TODO update with the git commands

$ svn copy snapshot VERSION
$ svn commit -m "VERSION branched" VERSION
$ cd VERSION
$ sed -i -e '0,/llvm-toolchain-snapshot/s/llvm-toolchain-snapshot/llvm-toolchain-VERSION/' debian/changelog debian/control
$ svn commit -m "snapshot => VERSION"
$ cd ../snapshot
$ emacs debian/prepare-new-release.sh
# Change the version
$ bash debian/prepare-new-release.sh
$ svn commit -m "new snapshot release"

Now, try build build it.