Updating to a new version of LLVM and Clang

This document should outline the process for developers to update SeeC to work with a new release of LLVM and Clang. Users do not need to worry about this.

Simplistically there are two things that we need to do: patch the new Clang release with the changes for SeeC-Clang, and then update SeeC's source code to work correctly (if any changes in LLVM and Clang affect SeeC's code - usually these are fairly minor). However, there is a little more work involved to ensure that the Travis CI builds work correctly.

(1) Update LLVM for Travis CI, Appveyor

1. On repository seec-team/llvm-with-seec-clang, pull from LLVM's git (http://llvm.org/git/llvm.git)
2. Checkout the new release e.g. git checkout release_NN
3. Create a new branch that will build and deploy binaries from Travis CI, e.g. git checkout -b release_NN_travis
4. Add the .travis.yml file (it will be in the previous release's branch release_PP_travis).
   The _travis branch commits can be cherry-picked in using [first commit hash]^..[final commit hash]
5. Update versions in .travis.yml (e.g. change deploy branch to release_NN_travis). Similarly for Appveyor's configuration files.
6. Draft a new release for the branch release_NN_travis. Check this release for an example. Travis CI should build from the release tag and attach results for each platform to the release.
7. Repeat steps 2-5 for Appveyor, where the branch is release_PP_appveyor.

(2) Patch SeeC-Clang

1. Create a patch series between the current SeeC-Clang release and the commit that it was based on, e.g. git format-patch -o /directory/for/patches release_OO..sc_release_OO
2. Checkout the branch for the new Clang release, e.g. git checkout release_NN
3. From this branch, create a new branch for the new SeeC-Clang release, e.g. git checkout -b sc_release_NN
4. Attempt to apply the patch series, e.g. git am --3 /directory/for/patches/*. Correct any conflicts as they arise.
5. Attempt to build and install your new SeeC-Clang.

(3) Update SeeC

1. Make seec work with your newly-built LLVM and Seec-Clang. The following files should be updated from the Clang files that they are based on (listed in each file's opening comments):
   • seec/tools/seec-cc/main.cpp
   • seec/tools/seec-cc/cc1_main.cpp
   • seec/tools/seec-cc/SeeCExecuteCompilerInvocation.cpp
2. Bump SeeC's trace format version number.

(4) Update SeeC-Clang for Travis CI, Appveyor

1. Make sure that the LLVM release has built and deployed correctly before pushing anything to seec-team, because Travis CI will use the results when building seec-clang.
2. Update seec-clang's .travis.yml so that the value of SEEC_LLVM_RELEASE_TAG matches that tag on the new LLVM release (created in (1).6).
3. Push the changes to seec-team and ensure that all Travis CI builds pass.
4. Draft a new release for the branch sc_release_NN. Check this release for an example. Travis CI should build from the release tag and attach results for each platform to the release.

(5) Pushing updated SeeC

1. Clear Travis CI's cache for seec builds.
2. Update seec's .travis.yml file so that the value of SEEC_LLVM_RELEASE_TAG matches that tag on the new LLVM release (created in (1).6), and the value of SEEC_CLANG_RELEASE_TAG matches that tag on the new SeeC-Clang release (created in (4).4).

(6) Finally

1. Update llvm-with-seec-clang's default branch here.
2. Update seec-clang's default branch here.
3. Update the build instructions.

Notes

• Appveyor cache can be cleared using a JavaScript console on the Appveyor site: $.ajax({ url: 'https://ci.appveyor.com/api/projects/<username>/<project>/buildcache', type: 'DELETE'});