diff --git a/docs/tutorial/crank-your-first-kernel.md b/docs/tutorial/crank-your-first-kernel.md index 4679db7..4d69f49 100644 --- a/docs/tutorial/crank-your-first-kernel.md +++ b/docs/tutorial/crank-your-first-kernel.md @@ -1,20 +1,32 @@ # Tutorial: Crank your first kernel -Cranking an Ubuntu kernel is the process of applying patches and updates to an existing Ubuntu kernel, packaging it, and preparing it for testing. All this done using the [cranky](https://kernel.ubuntu.com/gitea/kernel/kteam-tools/src/branch/master/cranky) toolchain. +Cranking an Ubuntu kernel is the process of applying patches and updates to an existing Ubuntu kernel, packaging it, and preparing it for testing. +All this is done using the [cranky](https://kernel.ubuntu.com/gitea/kernel/kteam-tools/src/branch/master/cranky) toolchain. -In this tutorial, we will crank a 24.04 LTS (Noble Numbat) (codename `noble`) Google cloud kernel (codename `linux-gke`). Keep these codenames in mind for future commands. +In this tutorial, we will crank a 24.04 LTS (Noble Numbat) (codename `noble`) Google cloud kernel (codename `linux-gke`). + +```{tip} + Keep these codenames handy for future commands. +``` + +## Prerequisites + +You will need to complete the prerequisite setup below before proceeding with the tutorial: + +- {doc}`Set up your cranky environment ` +- Set up your [VPN connection] +- Get access to [Kernel team build resources] ## Set up and update build environment - -You will need to complete the setup according to the {doc}`cranky environment setup ` guide before continuing. +First, we will prepare our build environment and tooling needed for cranking a kernel. ### Update chroot environment -We use [chroot](https://en.wikipedia.org/wiki/Chroot) environments to isolate different sets of tools when doing kernel cranking. `cranky` helps us set up and manage these chroot jails. +We use [chroot](https://en.wikipedia.org/wiki/Chroot) environments to isolate different sets of tools when doing kernel cranking. +`cranky` helps us set up and manage these chroot jails. - Creating the chroot jail is done in two steps. First, create the chroot base: ```bash @@ -37,8 +49,7 @@ This step uses APT to install various packages needed for the crank and may take Update your local clone of `kteam-tools` to the latest commit on the `master` branch: ```{warning} -If your kteam-tools tree isn't clean, be sure to save your work before running the commands. -They will modify the repository! +If your `kteam-tools` tree isn't clean, be sure to save your work before running the commands as this step will modify the repository. Git should warn you if any destructive actions might occur. ``` @@ -48,7 +59,7 @@ git switch master git pull ``` -If the command completes successfully, you've got the latest version of cranky. +Once the command completes successfully, you've got the latest version of cranky. ## Download current version of kernel @@ -56,14 +67,17 @@ You're now ready to clone the `linux-gke` kernel in its current state. - ```bash cranky checkout noble:linux-gke ``` -If the command completes successfully, you should see the following new directory: `~/canonical/kernel/ubuntu/noble/linux-gke/`. Inside, there should be git repositories cloned: `linux-main/`, `linux-meta`, and `linux-signed`. This command can take several minutes to complete. +This command can take several minutes to complete. + +If the command completes successfully, you should see the following new directory: `~/canonical/kernel/ubuntu/noble/linux-gke/`. + +Inside, there should be three git repositories cloned: `linux-main/`, `linux-meta`, and `linux-signed`. -For more information about these, see {term}`linux-meta`, {term}`linux-signed` in the glossary. +For more information, see {term}`linux-meta` and {term}`linux-signed` in the glossary. ## Apply updates from upstream kernel @@ -77,8 +91,8 @@ Update the local (in-tree) helper scripts cranky uses to the latest version: cd ~/canonical/kernel/ubuntu/noble/linux-gke/linux-main/ cranky fix ``` -You should see some output showing that cranky executed several scripts. -You see observe cranky going through the updating process for various scripts in the output terminal. + +You should see that cranky executed several scripts and go through the updating process for various scripts in the output terminal. ### Rebase on top of updated parent @@ -94,20 +108,21 @@ For non-derivative kernels (e.g., `noble:linux`), this step is not required. ### Fix helper scripts (again) -Sometimes after a `cranky rebase`, the helper scripts get updated. It's good practice to always re-run: +Sometimes after a `cranky rebase`, the helper scripts get updated. +It's good practice to always re-run: ```bash cranky fix ``` - ## Commit and review updates Now that we've pulled in all the upstream changes, we are ready to review and apply the commits to the `linux-gke` kernel. ### Add starting commit -Create a commit that signifies the start of a new release. This new commit will contain {term}`ABI` changes and any customization required by backport kernels. +Create a commit that signifies the start of a new release. +This new commit will contain {term}`ABI` changes and any customization required by backport kernels. ```bash cranky open @@ -153,12 +168,15 @@ diff --git a/debian.gke/changelog b/debian.gke/changelog ### Review rebased changes -Sometimes the rebase doesn't get all the changes. So we need to run this command to manually review any outstanding changes: +Sometimes the rebase doesn't get all the changes. +So we need to run this command to manually review any outstanding changes: ```bash cranky review-master-changes ``` -This command will output any outstanding changes in a list with their commit hashes and descriptions. Use `git show ` to view the changes. + +This command will output any outstanding changes in a list with their commit hashes and descriptions. +Use `git show ` to view the changes. ```{terminal} :input: cranky review-master-changes @@ -186,11 +204,11 @@ For the purposes of this tutorial, no additional commits need to be added. ### Link to Launchpad bug tracker -Run the following command to update the corresponding Launchpad tracking bug to this new kernel -version being created. +Run the following command to update the corresponding Launchpad tracking bug to this new kernel version being created. ```{warning} -Use `--dry-run` unless you are actually cranking a kernel. Otherwise, this will overwrite Launchpad and might make destructive changes! +Use `--dry-run` unless you are actually cranking a kernel. +Otherwise, this will overwrite Launchpad and might make destructive changes! ``` ```bash @@ -198,7 +216,8 @@ cranky link-tb --dry-run ``` ```{tip} -If you are running `cranky link-tb` for the first time, you will be directed to the "Authorize application to access Launchpad on your behalf" page. Choose your preferred option before continuing. +If you are running `cranky link-tb` for the first time, you will be directed to the "Authorize application to access Launchpad on your behalf" page. +Choose your preferred option before continuing. ``` This step should update the Launchpad tracking bug -- which, among other things, will be used as an input for subsequent steps -- and create a git commit. @@ -218,7 +237,8 @@ Dry Run -- no changes made ### Update DKMS packages -The `debian.master/dkms-versions` file specifies dkms modules to be packaged with its kernel. This command updates the package versions in `debian.gke/dkms-versions` to match the ones expected for the SRU cycle. +The `debian.master/dkms-versions` file specifies dkms modules to be packaged with its kernel. +This command updates the package versions in `debian.gke/dkms-versions` to match the ones expected for the SRU cycle. ```bash cranky update-dkms-versions @@ -237,7 +257,6 @@ Since no changes are needed at this time, you should observe the following outpu debian.gke/dkms-versions: No changes from kernel-versions ``` - ```{tip} In most cases, no changes are expected as the up-to-date DKMS versions should have been committed on the generic kernel and picked up by the derivative or backport on rebase. ``` @@ -263,6 +282,7 @@ This command is a shortcut that does the following: If successful, you should see a new commit when you run `git show`: + ```diff commit 6c9a5055b22f4c30aa3ba0c9df306762edb29197 (HEAD -> cranky/master-next) Author: Benjamin Wheeler @@ -302,8 +322,11 @@ index ba1191ce3bc2..a9ccd0b375a6 100644 ``` ## Verify the kernel builds successfully + At this point, the kernel is built and packaged. We should test that it builds successfully. + + ### Cloud Builder @@ -395,4 +418,10 @@ cranky push-review -s 2024.10.08 kathleen ``` ## Related topics + Learn more about Ubuntu releases and derivative kernels [here]. + + + +[VPN connection]: https://canonical-kteam-docs.readthedocs-hosted.com/en/latest/how-to/new_starter/newstarter.html#setup-vpn +[Kernel team build resources]: https://canonical-kteam-docs.readthedocs-hosted.com/en/latest/how-to/new_starter/newstarter.html#build-resources