Infrastructure/BuildBot

= BuildBot =

Overview
BuildBot automatically builds and tests Blender and its documentation on all supported platforms.

This page provides an overview of how to use the BuildBot for Blender developers. Further information:
 * Installing Builds
 * Changelog

Daily Builds
Buildbot automatically builds the master branch and any release branch under active development.
 * Nightly builds are packaged and made available on download page.
 * Builds are code signed for Windows and macOS.
 * On individual commits: only compiles and runs the tests.
 * A range of commits is collected once the branch is stable for at least 15 minutes

Pull Request Builds
Pull requests on projects.blender.org can be built using blender-bot commands, to test for build issues or to make a package available for download. It is highly recommended to test any non-trivial changes on the buildbot before merging.

Pull request must generally must be up to date with the latest `main` branch to build successfully. For security reasons, only developers with commit access can start such builds.

Branch Builds
Branches can also be built using blender-bot commands. For this put the comment in an issue relevant to the branch.

Branch builds remain available for 30 days, or until a newer revision of the branch is built.

Manual Triggers
Only a few developers have accounts on build.blender.org to trigger and cancel builds there. It is recommended to use blender-bot instead when possible. Anonymous users cannot start any builds, this is restricted for security reasons.

Developers with an account can click on the "Anonymous" button in the top right to log in.

Branch Builds
To build a branch:
 * Go the builders page and click the vexp-code-experimental-coordinator builder.
 * Click Trigger Experimental Build.
 * Fill in the name of the branch in the Blender repository.
 * If the build must be made available for download, enable Package delivery.
 * Click Start Build.
 * Follow progress of the submitted jobs, logs can be inspected for each platform.
 * Successful builds will appear on builder.blender.org/download/experimental and builder.blender.org/download/experimental/ /

There is a mechanism to automatically build and deliver specific branches every night, for specific temporary projects like `cycles-x` and `studio-spright-fright`.

Pull Request Builds
To build a pull requests:
 * Go the builders page and click the vexp-code-patch-coordinator builder.
 * Click Trigger Patch Build.
 * Fill in the pull request ID (e.g. #1234).
 * If the build must be made available for download, enable Needs package delivery.
 * Click Start Build.
 * Follow progress of the submitted jobs, logs can be inspected for each platform.
 * Successful builds will appear on builder.blender.org/download/patch.

Eventually, the plan is to support automatic builds for code review.

Release
Builds from the buildbot are used for official releases.

Once the release cycle in `BKE_blender_version.h` is set to `release` (or `rc` for release candidates), all the necessary packages, installers and hashes will be generated.

Store Delivery
There are automatic builders for delivering builds to various app stores.


 * Steam
 * Builds are automatically uploaded every night
 * `daily` (master), `daily-3.3` and `daily-2.93` Steam branches are automatically associated with the latest builds
 * `default`, `3.3`, `2.93` and similar branches are manually associated with automatically uploaded builds in Steamworks on release
 * Snap:
 * Builds are automatically uploaded every night
 * `latest/edge/master`, `3.x/candidate` or `3.x/beta`, `3.3lts/candidate` and `2.93lts/candidate` tracks are automatically associated with the latest builds
 * `XXX/stable` tracks are manually associated with automatically uploaded builds in the Snapcraft store on release
 * Windows Store:
 * Builds are not automatically uploaded, however a `.msix` package is made every night

Library Builds
This is intended to build library dependencies from source. However it is incomplete and currently disabled.

Filtering Jobs
To filter the long list of builders on the builders page, there are two methods:
 * Enter text in the "Search for Builder" box.
 * Click on tags in the Tags column to show only builders of that type.