LLVM Packaging Guidelines: Difference between revisions

Latest revision as of 00:34, 15 July 2021

Overview

This guide is intended for packagers working with any of the llvm sub-projects, which include:

clang
compiler-rt
flang
libclc
libcxx
libcxxabi
libomp
lld
lldb
llvm
llvm-test-suite
mlir
polly
python-lit

General Development

Please submit pull requests for major changes. This will allow the CI tests to run and give other developers a chance to review.

CI Tests

The goal of the CI tests should be to test integration of llvm packages into the system. Tests for specific upstream bugs are not necessary, but any Fedora bugs that are caused by interactions with another package should have a CI test added when they are fixed.

Rebases

A rebase is an upgrade that changes the major version of LLVM (e.g. upgrading from X.0.1 to (X+1).0.0). For each upstream release we would like to start the upgrade process when the first release candidate is released. Packaging the first release candidate gives us a chance to test and fix issues in Fedora so we can get fixes back upstream before the final release.

Step 1: File a System Wide Change Proposal

A Change Proposal should be filed to notify Fedora users and developers that LLVM will be rebased in the next Fedora release. Make sure to follow the Fedora release schedule and file the change proposal before the Change Checkpoint.

Step 2: Request a side tag

File a ticket with releng to request a side tag for the initial package builds. Example

Alternatively use fedpkg request-side-tag and record the generated side-tag.

Step 3: Request dist-git repos for compatibility packages

Create a compatibility packages for clang and llvm for the current release in rawhide Using the fedpkg request-repo command. The packages should be called clangX and llvmX, where X.Y.z is the current version of LLVM in rawhide. Compatibility packages do not need a full package review, so you can use the --exception flag when creating them.

Step 4: Create the compatibility packages

You can re-use the existing spec files from the clang and llvm dist-git when creating the compatibility packages. You just need to change the compat_build option to enabled by default:

 %bcond_with compat_build -> %bcond_without compat_build

Step 5: Do initial builds in the side tag

Do local or scratch builds of each llvm sub-project to make sure they build successfully in rawhide. Once you have confirmed that everything works, you can start submitting your builds to Koji. To do a scratch build in a side tag, use fedpkg scratch-build --target=<side-tag-name> --srpm=<srpm-path>

Additional Packages
The following packages also need to be rebuilt in the side-tag:

pocl
annobin

The goal at this stage is to get builds into rawhide. It is OK to disable tests and ignore minor failures at this stage.

Step 6: Merge side tag into rawhide

Comment on the releng ticket in Step 2 and ask for the side tag to be merged into rawhide.

It's very important to try to get the initial builds into rawhide before a new release is branched. This will give us the maximum possible time to integrate the new builds with other packages in Fedora.

If you requested the side tag through fedpkg you can login to bohdi and use the new update button then import the side tag into the update.

Step 7: Stabilize the packages

Continue to stabilize the packages in rawhide and any branched releases until all CI tests are passing and major bugs resolved.

Do not forget to port the changes in the compat packages back to the original ones, to make next release easier.

@@ Line 1: / Line 1: @@
 == Overview ==
 This guide is intended for packagers working with any of the llvm sub-projects, which include:
-* llvm
 * clang
+* compiler-rt
+* flang
+* libclc
+* libcxx
+* libcxxabi
+* libomp
 * lld
 * lldb
+* llvm
+* llvm-test-suite
+* mlir
+* polly
 * python-lit
-* libomp
-* libcxx
-* libcxxabi
 == General Development ==
@@ Line 19: / Line 25: @@
 A rebase is an upgrade that changes the major version of LLVM (e.g. upgrading from X.0.1 to (X+1).0.0).  For each upstream release we would like to start the upgrade process when the first release candidate is released.  Packaging the first release candidate gives us a chance to test and fix issues in Fedora so we can get fixes back upstream before the final release.
-=== Step 1: Creating Compatibility Packages ===
+=== Step 1: File a System Wide Change Proposal ===
-Create a compatibility packages for clang and llvm for the current release in rawhide.  The packages should be called clangX.Y and llvmX.Y, where X.Y.z is the current version of LLVM in rawhide.
+A [[Changes/Policy|Change Proposal]] should be filed to notify Fedora users and developers that LLVM will be rebased in the next Fedora release.  Make sure to follow the Fedora release schedule and file the change proposal before the Change Checkpoint.
+=== Step 2: Request a side tag ===
+File a [https://pagure.io/releng/new_issue ticket] with releng to request a side tag for the initial package builds.
+[https://pagure.io/releng/issue/8569 Example]
+Alternatively use `fedpkg request-side-tag` and record the generated side-tag.
+=== Step 3: Request dist-git repos for compatibility packages ===
+Create a compatibility packages for clang and llvm for the current release in rawhide  Using the `fedpkg request-repo` command.  The packages should be called clangX and llvmX, where X.Y.z is the current version of LLVM in rawhide.
+Compatibility packages [[Packaging:ReviewGuidelines#Package_Review_Process|do not need a full package review]], so you can use the --exception flag when creating them.
+=== Step 4: Create the compatibility packages ===
+You can re-use the existing spec files from the clang and llvm dist-git when creating the compatibility packages.  You just need to change the compat_build option to enabled by default:
+  %bcond_with compat_build -> %bcond_without compat_build
+=== Step 5: Do initial builds in the side tag ===
+Do local or scratch builds of each llvm sub-project to make sure they build successfully in rawhide.  Once you have confirmed that everything works, you can start submitting your builds to Koji. To do a scratch build in a side tag, use `fedpkg scratch-build --target=<side-tag-name> --srpm=<srpm-path>`
+{{admon/warning|Additional Packages| The following packages also need to be rebuilt in the side-tag:
+* pocl
+* annobin}}
+The goal at this stage is to get builds into rawhide.  It is OK to disable tests and ignore minor failures at this stage.
+=== Step 6: Merge side tag into rawhide ===
+Comment on the releng ticket in Step 2 and ask for the side tag to be merged into rawhide.
+{{admon/note|It's very important to try to get the initial builds into rawhide before a new release is branched.  This will give us the maximum possible time to integrate the new builds with other packages in Fedora.}}
+If you requested the side tag through `fedpkg` you can login to bohdi and use the `new update` button then import the side tag into the update.
-You can re-use the existing spec files from the clang and llvm dist-git when creating the compatibility packages.  You just need to change the value of the compat_build macro from 0 to 1:
+=== Step 7: Stabilize the packages ===
-  %global compat_build 1
+Continue to stabilize the packages in rawhide and any branched releases until all CI tests are passing and major bugs resolved.
-=== Step 2: Updating Rawhide ===
+Do not forget to port the changes in the compat packages back to the original ones, to make next release easier.
-Do local or scratch builds of each llvm sub-project to make sure they build successfully in rawhide.  Once you have confirmed that everything works, you can start submitting your builds to Koji.  Please make sure to submit builds for all sub-projects as soon as possible to minimize disruptions.  If  this is not possible, then you will need to request a side-tag from [https://pagure.io/releng/new_issue releng] so you can stage your builds before adding them to rawhide.
-{{admon/warning|Pocl|Pocl has a runtime dependency on clang, so it needs to be rebuilt during the rebase process.}}

Search