## Initial setup Check https://github.com/rust-lang/rust stable branch for the release merge, example: https://github.com/rust-lang/rust/pull/131695 - `git remote add upstream https://github.com/rust-lang/rust` - `git fetch upstream stable` - `git checkout upstream/stable` - `git submodule update --init` to get everything in order ## Rebase From the stable branch, checkout the new release branch `git checkout -b esp-1.82.0.0` ### LLVM Xtensa Cherry picking the LLVM submodule commit often doesn't work as expected, git submodules are somewhat buggy. Instead I manually create that commit by running the following commands: - `git submodule set-url src/llvm-project https://github.com/espressif/llvm-project` - `git submodule set-branch -b xtensa_release_12.0.1 src/llvm-project`, this branch will change over time, be sure check the default branch. - `git add .` (but don't commit yet) - `git submodule update --init --remote src/llvm-project` - `git add .` - `git commit -m "Use llvm submodule with Xtensa arch support."` ## Cherry picking Go to latest esp release branch, e.g https://github.com/esp-rs/rust/commits/esp-1.81.0.0/ and cherry-pick the relevant commits in order **NOTE** some patches may not be required depending on what has been upstreamed. It's advised to cherry pick instead of a rebase due to the way rustc upstream branches ## Building locally The next step once patches are a applied and fixed up if there are conflicts is to build locally `./configure --experimental-targets=Xtensa --release-channel=nightly --enable-extended --tools=clippy,cargo,rustfmt,rust-analyzer-proc-macro-srv,src --enable-lld --prefix $(pwd)/build/esp --sysconfdir $(pwd)/build/esp-etc` and then to build `./x.py build && ./x.py install` Ensure that once LLVM starts building you see some output that looks like ``` -- Found Git: /usr/bin/git (found version "2.45.2") -- LLVMHello ignored -- Loadable modules not supported on this platform. -- Targeting AArch64 -- Targeting ARM -- Targeting BPF -- Targeting Hexagon -- Targeting LoongArch -- Targeting MSP430 -- Targeting Mips -- Targeting NVPTX -- Targeting PowerPC -- Targeting RISCV -- Targeting Sparc -- Targeting SystemZ -- Targeting WebAssembly -- Targeting X86 -- Targeting Xtensa ``` where the list includes Xtensa. ## Testing the toolchain To run compiler tests: Some of the ui tests might fail as they will have there output changed by the existance of Xtensa ```rust ./x.py test --skip src/tools/tidy ``` The specific tests we currently maintain are under the assembly subdir ```rust ./x.py test --skip src/tools/tidy tests/assembly-llvm ``` Beyond that, building some projects and esp-wifi examples is a pretty good test of the toolchain ## Deploying the toolchain The rebase is complete and you're happy with the state of the compiler. We're ready to prepare builds on all platforms 1) Push your branch `esp-1.x.x.x` to esp-rs/rust, and make it the default branch 2) Go to esp-rs/rust-build open a release PR like https://github.com/esp-rs/rust-build/pull/276 3) Run the prepare release action on your PR branch 4) Go to the actions tab and launch the target actions individually choosing your PR branch as the action base 5) Once they've all completed, its worth running esp-hal CI against the new compiler like so https://github.com/esp-rs/esp-hal/pull/2414 6) If everything builds and we are happy, we can promote it to the latest release