mirror of
https://pagure.io/fedora-docs/quick-docs.git
synced 2024-11-28 14:56:35 +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
|
File: anaconda_product_image
|
||||||
- Name: (FIX ME!) AutoUpdates
|
- Name: (FIX ME!) AutoUpdates
|
||||||
File: autoupdates
|
File: autoupdates
|
||||||
- Name: (FIX ME!) Building a custom kernel
|
- Name: (CHECK) Building a custom kernel
|
||||||
File: build-custom-kernel
|
File: build-custom-kernel
|
||||||
- Name: Bumblebee
|
- Name: Bumblebee
|
||||||
File: 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
|
[[sect-why-build-a-custom-kernel]]
|
||||||
* Missing graphics and tables that do not convert well from mediawiki
|
== Why Build a Custom Kernel?
|
||||||
* Out-of-date
|
|
||||||
* In need of other love
|
|
||||||
|
|
||||||
|
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
|
.. Troubleshoot issues
|
||||||
`_topic_map.yml`.
|
|
||||||
|
|
||||||
Once the document is live, go to the original wiki page and replace its text
|
.. Add patches
|
||||||
with the following macro:
|
|
||||||
|
|
||||||
....
|
[[sect-preparing-to-build-a-custom-kernel]]
|
||||||
{{#fedoradocs: https://docs.fedoraproject.org/whatever-the-of-this-new-page}}
|
== 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
|
sudo dnf install fedora-packager
|
||||||
from another source
|
|
||||||
* To reconfigure the existing kernel
|
|
||||||
* To learn more about the kernel and kernel development
|
|
||||||
|
|
||||||
[[dependencies-for-building-kernels]]
|
----
|
||||||
Dependencies for building kernels
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Not all of these will apply to all methods but this provides a good
|
`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’.
|
||||||
dependency list of items to install
|
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
|
[NOTE]
|
||||||
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.
|
|
||||||
|
|
||||||
[[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
|
[[sect-building-the-kernel]]
|
||||||
an Fedora developer account
|
== 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.
|
[source,bash]
|
||||||
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.
|
|
||||||
|
|
||||||
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`
|
`# 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
|
To build the packages enter:
|
||||||
installed:
|
|
||||||
|
|
||||||
`$ 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
|
fedpkg local
|
||||||
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:
|
|
||||||
|
|
||||||
`$ 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]]
|
If you want to create only the kernel and modules packages, you can use the `fast-build.sh` script.
|
||||||
Enabling config options
|
First enter:
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
If there are configuration options that need to be adjusted for your
|
[source,bash]
|
||||||
build, you can add changes in the kernel-local file. These changes will
|
|
||||||
get picked up when you build.
|
|
||||||
|
|
||||||
[[updating]]
|
----
|
||||||
Updating
|
|
||||||
^^^^^^^^
|
|
||||||
|
|
||||||
* `$ cd kernel`
|
fedpkg srpm
|
||||||
* `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
|
|
||||||
|
|
||||||
Now you can run whatever other commands you want (e.g. make release)
|
----
|
||||||
|
|
||||||
[[building-a-kernel-from-the-exploded-git-trees]]
|
The result should look something like this:
|
||||||
Building a kernel from the exploded git trees
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Fedora keeps a git tree containing Fedora patches applied on top of the
|
`Wrote /current/path/kernel-4.15.3-300.my_kernel.fc27.src.rpm`
|
||||||
vanilla sources.
|
|
||||||
|
|
||||||
`$ 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]]
|
./scripts/fast-build.sh x86_64 kernel-4.15.3-300.my_kernel.fc27.src.rpm
|
||||||
Building a Kernel from the source 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]]
|
If you need to add patches use the script `newpatch.sh` like this:
|
||||||
Building Only Kernel Modules (Out Of Tree Modules)
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
This section is for users who are only interested in working on a kernel
|
[source,bash]
|
||||||
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`.
|
|
||||||
|
|
||||||
....
|
----
|
||||||
su -c 'dnf install kernel-devel'
|
|
||||||
....
|
|
||||||
|
|
||||||
You can build against any kernel version, as long as you have `kernel`
|
./scripts/newpatch.sh my-patch.patch
|
||||||
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.
|
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
....
|
(where `my-patch.patch` is the file name of the patch.)
|
||||||
obj-m := foo.o
|
|
||||||
|
|
||||||
KDIR := /lib/modules/$(shell uname -r)/build
|
Once it is complete, you can install/update your system with your custom kernel build.
|
||||||
PWD := $(shell pwd)
|
`cd` into the directory created in the kernel build process (`x86_64`, `x86`, etc.) and type:
|
||||||
|
|
||||||
default:
|
[source,bash]
|
||||||
[TAB]$(MAKE) -C $(KDIR) M=$(PWD) modules
|
|
||||||
....
|
|
||||||
|
|
||||||
[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
|
|
||||||
|
|
||||||
....
|
It will update any kernel packages you currently have installed on your computer.
|
||||||
# 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
|
|
||||||
....
|
|
||||||
|
|
||||||
etc to build those targets.
|
[[sect-additional-resources]]
|
||||||
|
== Additional Resources:
|
||||||
|
|
||||||
[[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].
|
||||||
Building Vanilla upstream kernel
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Sometimes a Fedora developer may ask you to try building and installing
|
[[sect-credit]]
|
||||||
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.
|
|
||||||
|
|
||||||
[[existing-fedora-vanilla-packages]]
|
== Credits:
|
||||||
Existing Fedora Vanilla packages
|
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
There is an effort underway for packaging vanilla kernels.
|
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].
|
||||||
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.
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue