Skip to content

Annecyh/cranky tutorial suggested edits #55

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
benjamin051000 merged 8 commits into from
Jan 23, 2025
Merged

Annecyh/cranky tutorial suggested edits #55

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
9950530
WIP: suggested edits for tutorial
AnneCYH Jan 17, 2025
8f315cb
WIP: suggested edits for tutorial
AnneCYH Jan 20, 2025
4c6016f
WIP
AnneCYH Jan 21, 2025
95a5b3e
WIP
AnneCYH Jan 21, 2025
73ec74a
WIP
AnneCYH Jan 22, 2025
e3edf3d
Merge branch 'bwheeler/cranky-tutorial' into annecyh/cranky-tutorial-…
benjamin051000 Jan 22, 2025
763103c
WIP
AnneCYH Jan 23, 2025
69807db
Merge branch 'bwheeler/cranky-tutorial' into annecyh/cranky-tutorial-…
benjamin051000 Jan 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 54 additions & 25 deletions docs/tutorial/crank-your-first-kernel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

<!-- TODO specify the SRU cycle -->
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 </how-to/cranking/set-up-cranky-environment>`
- Set up your [VPN connection]
- Get access to [Kernel team build resources]

## Set up and update build environment

<!-- TODO add cranky setup how-to -->
You will need to complete the setup according to the {doc}`cranky environment setup </how-to/cranking/set-up-cranky-environment>` 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.

<!-- FEEDBACK: it isn't obvious which part is specific to the "first time setup". Meaning if this is NOT the first time you're working on it, does it mean you skip this particular create-base step or skip the whole section? Maybe add "if not, skip create-base step", along those lines. -->
Creating the chroot jail is done in two steps. First, create the chroot base:

```bash
Expand All @@ -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.
```

Expand All @@ -48,22 +59,25 @@ 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

You're now ready to clone the `linux-gke` kernel in its current state.

<!-- TODO this probably needs SRU cycles specified so it's more reproducible. -->


```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

Expand All @@ -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

Expand All @@ -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
```

<!-- TODO what should this section be called? -->
## 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
Expand Down Expand Up @@ -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 <commit-hash>` to view the changes.

This command will output any outstanding changes in a list with their commit hashes and descriptions.
Use `git show <commit-hash>` to view the changes.

```{terminal}
:input: cranky review-master-changes
Expand Down Expand Up @@ -186,19 +204,20 @@ 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
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.
Expand All @@ -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
Expand All @@ -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
```

<!-- FEEDBACK: The explanation can be simplified for the tutorial but I agree it would be helpful for those cranking regularly in case something pops up unexpectedly -->
```{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.
```
Expand All @@ -263,6 +282,7 @@ This command is a shortcut that does the following:
<!-- FEEDBACK: https://canonical-kteam-docs.readthedocs-hosted.com/en/latest/tutorial/cranky_tutorial.html#close-the-changelog-cranky-close it's mentioned here but it isn't obvious -->

If successful, you should see a new commit when you run `git show`:

```diff
commit 6c9a5055b22f4c30aa3ba0c9df306762edb29197 (HEAD -> cranky/master-next)
Author: Benjamin Wheeler <[email protected]>
Expand Down Expand Up @@ -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.

<!-- TODO verify above statement! -->

### Cloud Builder
<!-- TODO WARNING: cbd is internal only (?) What should we put here instead? -->

Expand Down Expand Up @@ -395,4 +418,10 @@ cranky push-review -s 2024.10.08 kathleen
```

## Related topics

Learn more about Ubuntu releases and derivative kernels [here].

<!-- LINKS -->

[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
Loading