mirror of
https://pagure.io/fedora-docs/quick-docs.git
synced 2024-11-24 21:35:17 +00:00
Edited and formatted build-custom-kernel.adoc
This commit is contained in:
Shaun Assam
Brian (bex) Exelbierd
parent
2a36e44a5c
commit
93182a5281
2 changed files with 95 additions and 308 deletions
|
|
@ -69,7 +69,7 @@ Topics:
|
|||
File: anaconda_product_image
|
||||
- Name: (FIX ME!) AutoUpdates
|
||||
File: autoupdates
|
||||
- Name: (FIX ME!) Building a custom kernel
|
||||
- Name: (CHECK) Building a custom kernel
|
||||
File: build-custom-kernel
|
||||
- Name: Bumblebee
|
||||
File: bumblebee
|
||||
|
|
|
|||
|
|
@ -1,383 +1,170 @@
|
|||
= Building a custom kernel
|
||||
[[ch-build-custom-kernel]]
|
||||
= Building a Custom Kernel
|
||||
|
||||
'''
|
||||
[NOTE]
|
||||
|
||||
[IMPORTANT]
|
||||
======
|
||||
====
|
||||
|
||||
This page was automatically converted from https://fedoraproject.org/wiki/Building_a_custom_kernel
|
||||
This document provides instructions for advanced users who want to rebuild the kernel from source.
|
||||
Any issues with a custom kernel build are *not supported* by the Fedora kernel team.
|
||||
|
||||
It is probably
|
||||
====
|
||||
|
||||
* Badly formatted
|
||||
* Missing graphics and tables that do not convert well from mediawiki
|
||||
* Out-of-date
|
||||
* In need of other love
|
||||
[[sect-why-build-a-custom-kernel]]
|
||||
== Why Build a Custom Kernel?
|
||||
|
||||
Some common reasons to build a custom kernel are to:
|
||||
|
||||
Pull requests accepted at https://pagure.io/fedora-docs/quick-docs
|
||||
.. Change configuration options
|
||||
|
||||
Once you've fixed this page, remove this notice, and update
|
||||
`_topic_map.yml`.
|
||||
.. Troubleshoot issues
|
||||
|
||||
Once the document is live, go to the original wiki page and replace its text
|
||||
with the following macro:
|
||||
.. Add patches
|
||||
|
||||
....
|
||||
{{#fedoradocs: https://docs.fedoraproject.org/whatever-the-of-this-new-page}}
|
||||
....
|
||||
[[sect-preparing-to-build-a-custom-kernel]]
|
||||
== Preparing to build a custom kernel
|
||||
|
||||
======
|
||||
The Fedora kernel is just another package in Fedora and can be compiled like any other application.
|
||||
The easiest way to compile the kernel is to use the tools provided by the `fedora-packager` package.
|
||||
This will install basic tools like `fedpkg` which is used to download the kernel source code onto your computer.
|
||||
|
||||
'''
|
||||
To install `fedora-packager` from the command-line, enter:
|
||||
|
||||
[source,bash]
|
||||
|
||||
This document provides instructions for advanced users who want to
|
||||
rebuild the kernel from some source. Note, however, that when building
|
||||
or running any such kernel, one should NOT expect support from the
|
||||
Fedora kernel team; you're pretty much on your own here if something
|
||||
doesn't work as you'd hoped or expected. But hey, you're an advanced
|
||||
user, so you can handle it, right? Anyway, advanced users build custom
|
||||
kernels for a variety of reasons:
|
||||
----
|
||||
|
||||
* To apply patches for testing that they either generated or obtained
|
||||
from another source
|
||||
* To reconfigure the existing kernel
|
||||
* To learn more about the kernel and kernel development
|
||||
sudo dnf install fedora-packager
|
||||
|
||||
[[dependencies-for-building-kernels]]
|
||||
Dependencies for building kernels
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
----
|
||||
|
||||
Not all of these will apply to all methods but this provides a good
|
||||
dependency list of items to install
|
||||
`fedpkg` will make a clone of the Fedora kernel from link:++http://pkgs.fedoraproject.org/cgit/rpms/kernel.git/++[pkg-git] into a directory called ‘kernel’.
|
||||
By default, the source that is "checked out" will be the link:++https://fedoraproject.org/wiki/Releases/Rawhide++[Rawhide] kernel.
|
||||
Each Fedora release has its own branch and you can change branches using `git` commands.
|
||||
For example, to "check out" the source for Fedora 27, we would run the following commands:
|
||||
|
||||
`# sudo dnf install fedpkg fedora-packager rpmdevtools ncurses-devel pesign`
|
||||
[source,bash]
|
||||
|
||||
Give the following command from the top directory of the kernel source
|
||||
tree once you have checked it out
|
||||
----
|
||||
|
||||
`# sudo dnf builddep kernel.spec`
|
||||
fedpkg co -a kernel
|
||||
|
||||
if you plan to run 'make xconfig'
|
||||
cd kernel
|
||||
|
||||
`# sudo dnf install qt3-devel libXi-devel gcc-c++`
|
||||
git checkout -b my_kernel origin/f27
|
||||
|
||||
Also make sure you add the user doing the build to /etc/pesign/users and
|
||||
run the authorize user script:
|
||||
----
|
||||
|
||||
`# sudo /usr/libexec/pesign/pesign-authorize-users`
|
||||
This creates a git branch named 'my_kernel' containing the kernel source for Fedora 27.
|
||||
|
||||
It should be noted that pesign pesign-rh-test-certs gets pulled in
|
||||
automatically for some, but not for everyone, it depends on how you
|
||||
installed pesign. It is best to make sure that you have it installed.
|
||||
[NOTE]
|
||||
|
||||
[[building-a-kernel-from-the-fedora-source-tree]]
|
||||
Building a Kernel from the Fedora source tree
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
====
|
||||
|
||||
Make sure you have installed all dependencies
|
||||
Be sure to change the version number to whatever version of Fedora you are using.
|
||||
|
||||
`$ fedpkg clone kernel`
|
||||
====
|
||||
|
||||
you will likely need to checkout the source anonymously unless you have
|
||||
an Fedora developer account
|
||||
[[sect-building-the-kernel]]
|
||||
== Building the kernel
|
||||
|
||||
`$ fedpkg clone -a kernel`
|
||||
The kernel has a number of build dependencies that can be installed with:
|
||||
|
||||
As of the time of this wiki writing, the kernel is managed using git.
|
||||
Each fedora release is a separate branch. rawhide tracks master. To get
|
||||
the tree for a particular release, you can use git checkout from the top
|
||||
of your newly created source tree.
|
||||
[source,bash]
|
||||
|
||||
e.g. for fedora 23,
|
||||
----
|
||||
|
||||
`$ git checkout origin/f23`
|
||||
sudo dnf builddep kernel.spec
|
||||
|
||||
You can now make whatever changes / customizations you need before
|
||||
generating the rpms and installing them. You may want to consider
|
||||
uncommenting
|
||||
----
|
||||
|
||||
Changes to kernel configuration options can be added to the file `config-local`.
|
||||
|
||||
When building a kernel for testing, it is best to use an identifiable name.
|
||||
This makes it easy to distinguish your custom kernel from the official Fedora kernel builds.
|
||||
Find the line in the `kernel.spec` file that says:
|
||||
|
||||
`# define buildid .local`
|
||||
|
||||
to avoid conflicts, e.g.
|
||||
and change it to:
|
||||
|
||||
`%define buildid .local`
|
||||
`%define buildid .my_kernel`
|
||||
|
||||
When finished, generate the appropriate rpms with
|
||||
This will add _my_kernel_ to the the RPM package file names and will look something like this:
|
||||
|
||||
`$ fedpkg local`
|
||||
`kernel-4.15.3-300.my_kernel.fc27.src.rpm`
|
||||
|
||||
The rpms will be generated in a subdirectory $ARCH which can then be
|
||||
installed:
|
||||
To build the packages enter:
|
||||
|
||||
`$ dnf install --nogpgcheck ./x86_64/kernel-$version.rpm`
|
||||
[source,bash]
|
||||
|
||||
[[building-a-non-debugging-kernel]]
|
||||
Building a non-debugging kernel
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
----
|
||||
|
||||
Branched kernels are built with debugging enabled by default in the
|
||||
early stages of the release to assist developers. To make a kernel with
|
||||
debugging information disabled, you can follow the above instructions to
|
||||
check out and do:
|
||||
fedpkg local
|
||||
|
||||
`$ make release`
|
||||
----
|
||||
|
||||
`$ fedpkg local`
|
||||
This will create all the kernel packages in the `x86_64` directory (or the name of the architecture you are building for).
|
||||
This will take a long time as it is creating all the kernel, module and debug packages.
|
||||
Also, it will require over 12 GB of disk space.
|
||||
|
||||
[[enabling-config-options]]
|
||||
Enabling config options
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
If you want to create only the kernel and modules packages, you can use the `fast-build.sh` script.
|
||||
First enter:
|
||||
|
||||
If there are configuration options that need to be adjusted for your
|
||||
build, you can add changes in the kernel-local file. These changes will
|
||||
get picked up when you build.
|
||||
[source,bash]
|
||||
|
||||
[[updating]]
|
||||
Updating
|
||||
^^^^^^^^
|
||||
----
|
||||
|
||||
* `$ cd kernel`
|
||||
* `kernel $ git status`
|
||||
** your tree will be dirty in the configs and kernel.spec
|
||||
* `kernel $ git stash`
|
||||
** puts aside your changes so your tree will be clean
|
||||
* `kernel $ git pull origin`
|
||||
** update to the latest tree from fedpkg git
|
||||
fedpkg srpm
|
||||
|
||||
Now you can run whatever other commands you want (e.g. make release)
|
||||
----
|
||||
|
||||
[[building-a-kernel-from-the-exploded-git-trees]]
|
||||
Building a kernel from the exploded git trees
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
The result should look something like this:
|
||||
|
||||
Fedora keeps a git tree containing Fedora patches applied on top of the
|
||||
vanilla sources.
|
||||
`Wrote /current/path/kernel-4.15.3-300.my_kernel.fc27.src.rpm`
|
||||
|
||||
`$ git clone `git://git.kernel.org/pub/scm/linux/kernel/git/jwboyer/fedora.git[`git://git.kernel.org/pub/scm/linux/kernel/git/jwboyer/fedora.git`]
|
||||
Now enter:
|
||||
|
||||
`$ git checkout -b my_branch kernel-4.7.4-200.fc24`
|
||||
[source,bash]
|
||||
|
||||
You can now build the kernel following regular kernel instructions. This
|
||||
tree is useful for generating patches that can be applied to the
|
||||
kernel.spec.
|
||||
----
|
||||
|
||||
[[building-a-kernel-from-the-source-rpm]]
|
||||
Building a Kernel from the source RPM
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
./scripts/fast-build.sh x86_64 kernel-4.15.3-300.my_kernel.fc27.src.rpm
|
||||
|
||||
Instructions for this are on a link:Building_a_custom_kernel/Source_RPM[
|
||||
separate page]. In general, you should use one of the other methods for
|
||||
building the kernel which are much easier.
|
||||
----
|
||||
|
||||
[[building-only-kernel-modules-out-of-tree-modules]]
|
||||
Building Only Kernel Modules (Out Of Tree Modules)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
If you need to add patches use the script `newpatch.sh` like this:
|
||||
|
||||
This section is for users who are only interested in working on a kernel
|
||||
module, and who do not wish to build an entire custom kernel. It is not
|
||||
necessary to download and rebuild the entire kernel in order to build a
|
||||
module. To build a module for the currently running kernel, only the
|
||||
matching `kernel-devel` package is required. Run the following command
|
||||
to install the `kernel-devel` package using `dnf`.
|
||||
[source,bash]
|
||||
|
||||
....
|
||||
su -c 'dnf install kernel-devel'
|
||||
....
|
||||
----
|
||||
|
||||
You can build against any kernel version, as long as you have `kernel`
|
||||
and `kernel-devel` packages installed for that version. The rest of this
|
||||
section assumes we're building for the running kernel; if not, replace
|
||||
`\`uname -r\`` with the desired version number.
|
||||
./scripts/newpatch.sh my-patch.patch
|
||||
|
||||
As a simple example, to build the `foo.ko` module from `foo.c`, create
|
||||
the following `Makefile` in the directory containing the `foo.c` file:
|
||||
----
|
||||
|
||||
....
|
||||
obj-m := foo.o
|
||||
(where `my-patch.patch` is the file name of the patch.)
|
||||
|
||||
KDIR := /lib/modules/$(shell uname -r)/build
|
||||
PWD := $(shell pwd)
|
||||
Once it is complete, you can install/update your system with your custom kernel build.
|
||||
`cd` into the directory created in the kernel build process (`x86_64`, `x86`, etc.) and type:
|
||||
|
||||
default:
|
||||
[TAB]$(MAKE) -C $(KDIR) M=$(PWD) modules
|
||||
....
|
||||
[source,bash]
|
||||
|
||||
[TAB] Denotes a tab character which must come first for makefile lines
|
||||
containing commands.
|
||||
----
|
||||
|
||||
Then, issue the `make` command to build the `foo.ko` module.
|
||||
sudo dnf update kernel*.rpm
|
||||
|
||||
The above is a helpful local Makefile wrapper invoking kbuild; in
|
||||
general you can simply do things like
|
||||
----
|
||||
|
||||
....
|
||||
# make -C /lib/modules/`uname -r`/build M=`pwd` modules
|
||||
# make -C /lib/modules/`uname -r`/build M=`pwd` clean
|
||||
# make -C /lib/modules/`uname -r`/build M=`pwd` modules_install
|
||||
....
|
||||
It will update any kernel packages you currently have installed on your computer.
|
||||
|
||||
etc to build those targets.
|
||||
[[sect-additional-resources]]
|
||||
== Additional Resources:
|
||||
|
||||
[[building-vanilla-upstream-kernel]]
|
||||
Building Vanilla upstream kernel
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
For more information on building a custom kernel refer to the link:++https://fedoraproject.org/wiki/Building_a_custom_kernel++[Fedora Wiki: Building a Custom Kernel].
|
||||
|
||||
Sometimes a Fedora developer may ask you to try building and installing
|
||||
an upstream kernel (possibly with a patch added) for testing. If there
|
||||
are multiple iterations, it may be quicker for you to do this than for
|
||||
the developer to turn around several RPMs.
|
||||
[[sect-credit]]
|
||||
|
||||
[[existing-fedora-vanilla-packages]]
|
||||
Existing Fedora Vanilla packages
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
== Credits:
|
||||
|
||||
There is an effort underway for packaging vanilla kernels.
|
||||
link:Kernel_Vanilla_Repositories[ See if this meets your needs first]
|
||||
|
||||
[[getting-the-sources]]
|
||||
Getting the sources
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Clone a kernel tree from kernel.org
|
||||
|
||||
`$ git clone `git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git[`git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git`]
|
||||
This will clone the entire upstream tree. This may take a while
|
||||
depending on your connection speed. (While the tree is syncing, why not
|
||||
take the time to update some steps on this wiki that are inevitably out
|
||||
of date?)
|
||||
|
||||
`$ cd linux`
|
||||
|
||||
Double check what baseline is being used and check out a new one if
|
||||
necessary:
|
||||
|
||||
`$ git checkout v4.5.2`
|
||||
|
||||
[[applying-patches]]
|
||||
Applying patches
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
[[the-patch-method]]
|
||||
The patch method
|
||||
++++++++++++++++
|
||||
|
||||
If you were asked to apply any patches by the developer, this is the
|
||||
stage at which we would do so. These would typically be applied using a
|
||||
command something like..
|
||||
|
||||
`$ cat ~/testpatch.diff | patch -p1`
|
||||
|
||||
If you have to try multiple different patches individually, you can
|
||||
unapply the previous one after testing by adding -R on the end of the
|
||||
above command.
|
||||
|
||||
[[the-git-method]]
|
||||
The git method
|
||||
++++++++++++++
|
||||
|
||||
Most developers these days generate patches using git and you can use
|
||||
git to help apply patches. You can do:
|
||||
|
||||
`$ git am -3 `
|
||||
|
||||
This will create a git commit of a single patch in your tree.
|
||||
|
||||
[[configuring-the-kernel]]
|
||||
Configuring the kernel
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Chances are that the kernel you are running is older than the one you
|
||||
are about to configure. This means there will be new options. There are
|
||||
several possibilities here.
|
||||
|
||||
* If the developer has pointed you at a specific config file to use,
|
||||
save it in the linux directory with the filename .config
|
||||
* You can take your existing .config file by using the command
|
||||
`cp /boot/config-\`uname -r\`* .config`
|
||||
|
||||
When you run the next step, you'll be asked (potentially lots of)
|
||||
questions about all the new options. Just hitting return 'should' always
|
||||
pick the safe decision for each option. However, it's worth taking care
|
||||
and reading each option, as this isn't always the case, and they may
|
||||
introduce new features your distro isn't capable of running, which may
|
||||
result in a non-booting system.
|
||||
|
||||
* FIXME how to grab a rawhide config
|
||||
|
||||
With the config in place, you are now ready to move on to the next step.
|
||||
|
||||
[[building-the-kernel]]
|
||||
Building the kernel
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
`$EDITOR Makefile` Change the EXTRAVERSION line to add something on the
|
||||
end. For example, if it reads "EXTRAVERSION = -rc5" change it to
|
||||
"EXTRAVERSION = -rc5-dave" (what you choose is only relevant for the
|
||||
final part of this procedure)
|
||||
|
||||
`$ make oldconfig`
|
||||
|
||||
`$ make bzImage`
|
||||
|
||||
`$ make modules`
|
||||
|
||||
(become root)
|
||||
|
||||
`# make modules_install`
|
||||
|
||||
`# make install`
|
||||
|
||||
You have now built and installed a kernel. It will show up in the grub
|
||||
menu next time you reboot.
|
||||
|
||||
[[rebuilding]]
|
||||
Rebuilding
|
||||
^^^^^^^^^^
|
||||
|
||||
If you have been asked to try several different things, the procedure
|
||||
once you have already built the tree once is mostly the same. A
|
||||
`make clean` is recommended between builds. This will leave the .config
|
||||
in place, so you can skip that step above and proceed straight to the
|
||||
`make bzImage` part of the steps above. Because we installed ccache in
|
||||
the first step, subsequent builds may go a lot faster as the compiler
|
||||
hits files that haven't changed since the last time it built them.
|
||||
|
||||
[[cleaning-up]]
|
||||
Cleaning up
|
||||
^^^^^^^^^^^
|
||||
|
||||
Once you have tested the kernel, and you've booted back to one of your
|
||||
kernels installed from an RPM, you can clean up the files that the above
|
||||
procedure installed by becoming root, and calling these commands. (Be
|
||||
sure to get the kernel version correct!) Remember above, we changed
|
||||
EXTRAVERSION to add a 'tag' to the kernel ? All the files it installed
|
||||
will have this as part of the filename. So you should be able to use
|
||||
wildcards to delete them safely using commands similar to those below.
|
||||
(Just replace 'dave' with whatever tag you chose)
|
||||
|
||||
....
|
||||
rm -f /boot/config-2.6.*dave* /boot/initrd-2.6.*dave* /boot/vmlinuz-*dave* /boot/System.map-*dave*
|
||||
rm -rf /lib/modules/2.6*dave*
|
||||
....
|
||||
|
||||
Finally, you will need to remove the kernel as an option to your
|
||||
bootloader. This will change from architecture to architecture. For x86,
|
||||
(as root), edit /boot/grub2/grub.cfg or /boot/efi/EFI/fedora/grub.cfg if
|
||||
you have EFI enabled and delete the four lines relating to your kernel
|
||||
(They should be easy to spot, they'll be the ones with your tag).
|
||||
They'll look something like this..
|
||||
|
||||
....
|
||||
title Fedora Core (2.6.22-rc3-dave)
|
||||
root (hd0,0)
|
||||
kernel /vmlinuz-2.6.22-rc3-dave ro root=/dev/md0
|
||||
initrd /initrd-2.6.22-rc3-dave.img
|
||||
....
|
||||
|
||||
Category:Documentation Category:Tutorials
|
||||
'''
|
||||
|
||||
See a typo, something missing or out of date, or anything else which can be
|
||||
improved? Edit this document at https://pagure.io/fedora-docs/quick-docs.
|
||||
This document is an updated and edited version of the article link:++https://fedoramagazine.org/building-fedora-kernel/++[Building the Fedora Kernel] from the link:++https://fedoramagazine.org++[Fedora Magazine].
|
||||
|
|
|
|||
Loading…
Reference in a new issue