diff --git a/doc/user_documentation.rst b/doc/user_documentation.rst index aca8217b5..cf82150a7 100644 --- a/doc/user_documentation.rst +++ b/doc/user_documentation.rst @@ -631,6 +631,13 @@ though they are recommended to do so. In particular, kernel modules may be built in Copr, as long as they don't violate the license requirements in point 2. above. +.. _`Can you lend me powerful/faster Copr builders?`: + +.. rubric:: Can you lend me powerful/faster Copr builders? :ref:`¶ ` + +Yes, but you don't always want this, see — :ref:`powerful_builders`.` + + .. _`Is it safe to use Copr?`: .. rubric:: Is it safe to use Copr? :ref:`¶ ` @@ -776,6 +783,7 @@ Community projects (formerly Cool Other Package Repositories) .. rubric:: How can I tell yum to prefer Copr packages? :ref:`¶ ` Building a package with the same version-release number in Copr as the package distributed in the official Fedora repos is discouraged. You should instead bump the release number. Should you build with the same version-release number, you can tell yum to prefer the Copr packages over the distribution provided packages by adding cost=900 to the .repo file. +TODO: ^^m priority .. _`Can Copr build directly from git?`: diff --git a/doc/user_documentation/powerful_builders.rst b/doc/user_documentation/powerful_builders.rst new file mode 100644 index 000000000..41392f1ef --- /dev/null +++ b/doc/user_documentation/powerful_builders.rst @@ -0,0 +1,48 @@ +:orphan: + +.. _powerful_builders: + +Default builders in Copr are too slow! +====================================== + +The default Fedora Copr workers are typically fast enough for the vast majority +of package builds. However, some package builds are extremely +resource-intensive, and our default workers struggle with them. A notable +example is Blink_-based browsers, which can take even more than 24 hours to +build. + +From a build system perspective, this isn't a problem. You can simply specify +``--timeout 180000`` (in seconds) and be prepared to wait for the build to +finish. But if you want to expedite your builds, you do have the option to +request "powerful" builders. + +Pros & Cons +----------- + +The "powerful" builders will handle your builds much faster (according to the +configuration as of October 2023, they are approximately 8 times faster than the +default builders). The downside is that they are in limited supply. We can +only start a few of them, and if multiple users request them and compete with +each other, they may spend more time in the queue, resulting in longer wait +times. Additionally, because these machines are costly, we don't pre-allocate +them (as we do with the normal builders). We only start these powerful ones +when "enabled builds" request them (which may itself take several minutes). + +As a consequence, when you configure your project, chroot or package to use +powerful builders, there's no "magical fallback to normal builders" implemented. +You'll simply have to wait for the powerful builder. + +The rule of thumb is to avoid using high-performance workers for builds that are +expected to complete in less than two hours on normal builders. + +How to request powerful builders +-------------------------------- + +As of October 2023, we only support powerful builders for ``x86`` and +``aarch64`` architectures. Please think carefully (ensure you understand the +previous section, especially the cons) and submit an issue_. Specify your +project, chroot, and the packages you want to configure to use powerful +builders. + +.. _Blink: https://en.wikipedia.org/wiki/Blink_(browser_engine) +.. _issue: https://github.com/fedora-copr/copr/issues