File README.packaging of Package llvm
========
OVERVIEW
This package is a dummy package that always depends on the
version of corresponding LLVM packages that openSUSE
currently supports. This file documents the procedure for
updating the various LLVM components.
There are three major update scenarios that will be addressed
here, patch-level updates to the current LLVM version,
patch-level updates to older LLVM versions, and major/minor
version updates.
LLVM version numbers come in three levels. For version
X.1.Z, changes to the X level are major updates, changes to
the Y level are minor updates, and changes to the Z level
are patch-level updates. Since LLVM 4, the minor version
is always expected to be 0. [1] Library .so numbers are
based on the major version, for example libLLVM.so.X.
Patch-level updates do not update the version number of
libraries. For this reason, only changes to the major
version number get a new llvm package.
There are up to three packages that need to be handled in a
given update. This package, the base "llvm" package, the
current "llvmX" package (X is the major version numbers),
and the next "llvmX" package if the major version has changed.
NOTE: This package should always have the same "License"
tag as the currently-supported version of the llvmX package.
[1] http://blog.llvm.org/2016/12/llvms-new-versioning-scheme.html
===================
PATCH-LEVEL UPDATES
For patch level updates, the corresponding llvmX package needs
to be updated.
1. llvmX package:
1. Add the new sources to the package and delete the old
ones. This will not include clang-docs-X.1.Z.src.tar.xz
or llvm-docs-X.1.Z.src.tar.xz (see next item).
2. Build clang-docs-X.1.Z.src.tar.xz and
llvm-docs-X.1.Z.src.tar.xz. The instructions are in
the %install section of llvmX.spec. The instructions
need RPM substitutions, for example via rpmspec -P.
Add those sources as well and delete the old ones.
3. Update the "_relver" tag in llvmX.spec to match the
new sources.
4. Update the version number in the patches to match the
new sources.
5. Update the "_uaver" tag in llvmX.spec to match
the "_relver" tag.
6. Confirm everything builds successfully and there are
no new rpmlint issues.
7. Update the llvmX.changes file.
=====================
MAJOR VERSION UPDATES
For updates that change the major version number, this
package (llvm) needs to be updated and a new llvmX package
needs to be created.
1. New llvmX package:
1. Copy (do not link) the old llvmX to the new
major/minor version number.
2. Add the new sources to the package and delete the old
ones. This will not include clang-docs-X.1.Z.src.tar.xz
or llvm-docs-X.1.Z.src.tar.xz (see next item).
3. Build clang-docs-X.1.Z.src.tar.xz and
llvm-docs-X.1.Z.src.tar.xz. The instructions are in
the %install section of llvmX.spec. The instructions
need RPM substitutions, for example via rpmspec -P.
Add those sources as well and delete the old ones.
4. Rename the .spec, .changes, and rpmlintrc files in the
new llvmX package to the new major/minor version
number
5. Rename the packages in llvmX.spec files to match the
new package name.
6. Change the "_sonum" tag in llvmX.spec to match the
new major/minor versions. It should be of the form "X".
Change the "_itsme" definition to "%define _itsmeX 1".
7. Change the "_minor" tag in llvmX.spec to match
the new major/minor versions. It should be of the
form "X.0".
8. Change the "_uaver" tag in llvmX.spec to match the
new major/minor versions. It should be of the form "X0Z".
9. Update the "_relver" tag and the version numbers in
the patches as described in PATCH-LEVEL UPDATES above.
10. Confirm llvmX.spec builds successfully and there are
no new rpmlint issues.
11. Check whether the .so numbers of "libc++.so.W.V" or
"libclang.so.X" have changed. If so, change the
"_socxx" or "_soclang" tag to match.
It should be of the form "W" if the "V" value is 0
or "W_V" if the "V" value is greater than 0.
12. Confirm everything builds successfully and there are
no new rpmlint issues. Some patches may need to be
removed or rebased.
13. Update the llvmX.changes file.
2. llvm package:
1. Change the "_sonum" tag to match the one in the
new "llvmX.spec" file.
2. Update the llvm.changes file.
3. Project config:
1. Change %product_libs_llvm_ver to X.
2. If one of the .so version numbers for libclang, libc++
or libc++abi changed, add a corresponding
Prefer: libcxxW
Prefer: libcxxabiW
Prefer: libclangW
for the new .so version and a corresponding definition
%product_libs_llvm_ver_libcxxW X
%product_libs_llvm_ver_libcxxabiW X
%product_libs_llvm_ver_libclangW X
with W the old .so version and X the old LLVM version.