From 064a327a7c941a8eebd932f15a14e6b3513fa96d Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Thu, 31 Jan 2019 13:22:28 -0800 Subject: [PATCH 01/35] Initial commit of kernel-development.rst Add a document explaining a kernel development workflow --- .../guides/maintenance/autospec.rst | 8 +- .../guides/maintenance/kernel-development.rst | 324 ++++++++++++++++++ 2 files changed, 330 insertions(+), 2 deletions(-) create mode 100644 source/clear-linux/guides/maintenance/kernel-development.rst diff --git a/source/clear-linux/guides/maintenance/autospec.rst b/source/clear-linux/guides/maintenance/autospec.rst index 257f8e2c..b5b083a6 100644 --- a/source/clear-linux/guides/maintenance/autospec.rst +++ b/source/clear-linux/guides/maintenance/autospec.rst @@ -23,8 +23,10 @@ This guide requires that you: .. _install-tooling: -Install the |CL| tooling framework -================================== +Install the |CL| development tooling framework +============================================== + +.. _install-tooling-after-header: #. Install the `os-clr-on-clr` developer bundle on your host system. @@ -60,6 +62,8 @@ Install the |CL| tooling framework The :file:`projects` folder contains the main tools, `autospec` and `common`, used for making packages in |CL|. +.. _install-tooling-end: + Create a RPM with autospec ************************** diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst new file mode 100644 index 00000000..8197eeb7 --- /dev/null +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -0,0 +1,324 @@ +.. _kernel-development: + +Kernel development on Clear Linux +################################# + +The kernel is the heart of an operating system with many things relying on it +to provide access to hardware and software functionality. +The Linux kernel is very customizable and extensible. + +The |CL| kernels aim to be performant and practical. In some cases, it may be +necessary modify the kernel to suit your specific needs or test new kernel +code as a developer. + +In cases where drivers beyond those enabled by default in |CL-ATTR| are +needed it may be necessary to: + +.. contents:: :local: + :depth: 2 + :backlinks: top + + +Request the change be added to |CL| kernel +========================================== + +If the kernel modification you need is already open source +(e.g. in the Linux upstream) and likely to be useful to others, +consider submitting a request to add or enable in the |CL| kernel. + +If your change request is accepted, you do not need to maintain your own modified kernel. + +Make enhancement requests to the |CL| distribution `on GitHub`_ . + + +Customize the Linux kernel source +================================= + +In some cases, it may be necessary modify the kernel to suit your specific +needs or test new kernel code as a developer. + +You can build and install a custom kernel, however you must: + + * disable secure boot + * maintain any updates to the kernel going forward + +This approach works well for individual development or testing. +For a more scalable and customizable approach, consider using the +`mixer tool`_ to provide a custom kernel and updates. + + + +Install the |CL| development tooling framework +---------------------------------------------- + +.. include:: autospec.rst + :start-after: install-tooling-after-header: + :end-before: install-tooling-end: + + + +Clone the Linux kernel package +------------------------------ +clone the existing kernel package repository from |CL| as a starting point. + +#. Clone the Linux kernel package from Clear Linux + + .. code-block:: bash + + cd ~/clearlinux + make clone_linux + +#. Navigate into the cloned package directory + + .. code-block:: bash + + cd ~/clearlinux/packages/linux + +.. note:: + The "linux" package is the kernel that comes with |CL| in the kernel-native bundle. + You can alternatively use a different kernel variant as the base for modification. + For a list of kernel package names which you can clone instead, see the `clearlinux-pkgs GitHub`. + + +Change the kernel version +------------------------- + +|CL| tends to use the latest kernel available from kernel.org, the Linux +upstream. The kernel version that will be built can be changed in the +RPM SPEC file. + +.. note:: + While most packages in Clear Linux are typically packaged using + :ref:`autospec`, the kernel is not. This means control files provided + by autospec are not available and changes must be made directly. + +#. Open the Linux kernel package RPM SPEC file in an editor + + .. code-block:: bash + + $EDITOR linux.spec + +#. Modify the Version, Release, and Source0 URL entries at the top of the file + + .. code-block:: bash + :emphasize-lines: 2,3,8 + + Name: linux + Version: 4.20.5 + Release: 690 + License: GPL-2.0 + Summary: The Linux kernel + Url: http://www.kernel.org/ + Group: kernel + Source0: https://cdn.kernel.org/pub/linux/kernel/v4.x/linux-4.20.5.tar.xz + Source1: config + Source2: cmdline + + .. note:: + TIP: Consider changing the Name in the RPM spec file to easily identify a modified kernel. + +#. Commit and save the changes to the file + + +Modify kernel configuration +--------------------------- + +Existing kernel features and in-tree kernel modules can be enabled or +disabled in the kernel configuration file, :file:`.config` , at compile time. + +To manage unique changes that have been made to the kernel config file, +|CL| uses a kernel config fragment file named :file:`config-fragment`. +Managing kernel configuration changes with a configuration fragment file +instead of directly editing the :file:`.config` file helps identify the +unique configuration changes that have been made and makes applying any +future default configuration values easier. + +The :file:`config-fragment` is the only file that is modified and is +eventually merged or overlaid with the main :file:`.config`. + + + +#. Open the kernel :file:`config-fragment` file in an editor. + + .. code-block:: bash + + $EDITOR config-fragment + + .. note:: + Due to how |CL| packaging tools make use of :command:`mock` environments + psuedo-GUI tools that abstract kernel configuration such as menuconfig do not work. + +#. Find the configuration values you are looking for. + If a particular setting does not already exist , it can be added manually. + + For example, BTRFS support configuration is below indicating it is + enabled in-tree. + + .. code-block:: bash + + CONFIG_BTRFS_FS=y + CONFIG_BTRFS_FS_POSIX_ACL=y + + +#. Modify the configuration values as desired. + For example, to disable BTRFS support change the configuration to be + commented out. + + .. code-block:: bash + + # CONFIG_BTRFS_FS is not set + # CONFIG_BTRFS_FS_POSIX_ACL is not set + +#. Commit and save the changes to the :file:`config-fragment` file. + + +#. Run the :command:`make config` command to apply the changes made in the + :file:`config-fragment` file and regenerate the :file:`config` file. + + .. code-block:: bash + + make config + + +.. note:: + If you hae a large number of patches or a more complex workflow, + consider using a patch management tool in addition to Git such as `Quilt`_. + +Modify kernel source code +------------------------- + +Changes to kernel code are applied with patch files. Patch files are formatted git commits that can be applied to the main source code. + +#. Clone the linux kernel source code into a new working directory + + .. code-block:: bash + + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + +#. Make any code changes to the Linux source files + +#. Track and commit your changes to the local git repo. + .. code-block:: bash + + git commit -m "My patch for driver A" + +#. Generate a patch file based on your git commits. + represents the number of local commits to create patch file. + See the `git-format-patch Documentation`_ for detailed information + on using :command:`git format-patch` + + .. code-block:: bash + + git format-patch - + +#. Copy the patch files from the patches directory in the linux + source tree to the RPM build directory + + .. code-block:: bash + + cp patches/*.patch ~/clearlinux/packages/linux/ + +#. Navigate back to the RPM build directory + + .. code-block:: bash + + cd ~/clearlinux/packages/linux/ + +#. Open the Linux kernel package RPM SPEC file in an editor + + .. code-block:: bash + + $EDITOR linux.spec + + +#. Locate the section of the SPEC file that contains existing patch + variable definitions and append your patch file name. Ensure the + patch number does not collide with an existing patch. + + .. code-block:: bash + :emphasize-lines: 13 + + # + # Small Clear Linux Tweaks + # + Patch0501: 0501-zero-extra-registers.patch + Patch0502: 0502-locking-rwsem-spin-faster.patch + + #Serie1.name WireGuard + #Serie1.git https://git.zx2c4.com/WireGuard + #Serie1.tag 00bf4f8c8c0ec006633a48fd9ee746b30bb9df17 + Patch1001: 1001-WireGuard-fast-modern-secure-kernel-VPN-tunnel.patch + #Serie1.end + + Patch2001: 2001-my-patch-for-driver-A.patch + + +#. Locate the section of the SPEC file further down that contains + patch application and append your patch file number used in the step above. + + .. code-block:: bash + :emphasize-lines: 11 + + # + # Small tweaks + # + %patch0501 -p1 + %patch0502 -p1 + + #Serie1.patch.start + %patch1001 -p1 + #Serie1.patch.end + + %patch2001 -p1 + + +#. Commit and save the changes to the RPM SPEC file. + + +Build and install a kernel +========================== +After changes have been made to the kernel SPEC file and config file, +the kernel is ready to be compiled and packaged into a RPM. + +#. Start the compilation process by issuing the :command:`make build` command. + This process is typically resource intensive and will take a while. + + .. code-block:: bash + + make build + +#. The result there will be :file:`.rpm` files in the :file:`results` + directory + + .. code-block:: bash + + ls results/ + + +#. The kernel RPM file can be input to the `mixer tool`_ to create a custom + bundle and mix of |CL|. + + Alternatively, the kernel RPM bundle can be installed locally for testing + with the :command:`rpm` command. + + .. code-block:: bash + + rpm -ivh linux-custom...x86_64.rpm + +#. Update the |CL| boot manager using :command:`clr-boot-manager` + sudo clr-boot-manager list-kernels + + .. code-block:: bash + + sudo clr-boot-manager list-kernels + + clr-boot-manager set-kernel + + + +.. _`on GitHub`: https://github.com/clearlinux/distribution +.. _`mixer tool`: https://clearlinux.org/features/mixer-tool +.. _user-setup script: https://github.com/clearlinux/common/blob/master/user-setup.sh +.. _`Quilt`: http://savannah.nongnu.org/projects/quilt +.. _`clearlinux-pkgs GitHub`: https://github.com/clearlinux-pkgs?&q=linux +.. _`git-format-patch Documentation`: https://git-scm.com/docs/git-format-patch From 6db71c1cca5e2a92ea84544f3eb4871fa7e50c60 Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Thu, 31 Jan 2019 14:56:00 -0800 Subject: [PATCH 02/35] Remove emphasize lines and minor edits Remove emphasize lines for now and minor edits --- .../guides/maintenance/kernel-development.rst | 23 +++++++++++-------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index 8197eeb7..088ecc2f 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -101,7 +101,6 @@ RPM SPEC file. #. Modify the Version, Release, and Source0 URL entries at the top of the file .. code-block:: bash - :emphasize-lines: 2,3,8 Name: linux Version: 4.20.5 @@ -236,7 +235,6 @@ Changes to kernel code are applied with patch files. Patch files are formatted g patch number does not collide with an existing patch. .. code-block:: bash - :emphasize-lines: 13 # # Small Clear Linux Tweaks @@ -257,7 +255,6 @@ Changes to kernel code are applied with patch files. Patch files are formatted g patch application and append your patch file number used in the step above. .. code-block:: bash - :emphasize-lines: 11 # # Small tweaks @@ -287,23 +284,29 @@ the kernel is ready to be compiled and packaged into a RPM. make build -#. The result there will be :file:`.rpm` files in the :file:`results` - directory +#. The result there will be multiple :file:`.rpm` files in the :file:`rpms` + directory as output. .. code-block:: bash - ls results/ + ls rpms/ + + The kernel RPM will be named :file:`linux-.x86_64.rpm` + + #. The kernel RPM file can be input to the `mixer tool`_ to create a custom bundle and mix of |CL|. - Alternatively, the kernel RPM bundle can be installed locally for testing - with the :command:`rpm` command. + +Alternatively, the kernel RPM bundle can be installed locally for testing +with the :command:`rpm` command. +1. Install with the rpm command .. code-block:: bash - rpm -ivh linux-custom...x86_64.rpm + sudo rpm -ivh linux-custom...x86_64.rpm #. Update the |CL| boot manager using :command:`clr-boot-manager` sudo clr-boot-manager list-kernels @@ -312,7 +315,7 @@ the kernel is ready to be compiled and packaged into a RPM. sudo clr-boot-manager list-kernels - clr-boot-manager set-kernel + sudo clr-boot-manager set-kernel From 02b064e757abfb5054298a64e16000b208c60549 Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Thu, 31 Jan 2019 15:54:54 -0800 Subject: [PATCH 03/35] Misc formatting fixes --- .../guides/maintenance/kernel-development.rst | 71 +++++++++++-------- 1 file changed, 43 insertions(+), 28 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index 088ecc2f..e2c1ca5c 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -19,12 +19,12 @@ needed it may be necessary to: :backlinks: top -Request the change be added to |CL| kernel -========================================== +Request the change be included with the |CL| kernel +=================================================== -If the kernel modification you need is already open source -(e.g. in the Linux upstream) and likely to be useful to others, -consider submitting a request to add or enable in the |CL| kernel. +If the kernel modification you need is already open source and likely to be +useful to others, consider submitting a request to add or enable in the +|CL| kernel. If your change request is accepted, you do not need to maintain your own modified kernel. @@ -39,13 +39,11 @@ needs or test new kernel code as a developer. You can build and install a custom kernel, however you must: - * disable secure boot - * maintain any updates to the kernel going forward - -This approach works well for individual development or testing. -For a more scalable and customizable approach, consider using the -`mixer tool`_ to provide a custom kernel and updates. +* Disable secure boot +* Maintain any updates to the kernel going forward +To customize the kernel you will need a |CL| development evnironment, +make changes to the kernel, build the kernel, and install it. Install the |CL| development tooling framework @@ -61,14 +59,14 @@ Clone the Linux kernel package ------------------------------ clone the existing kernel package repository from |CL| as a starting point. -#. Clone the Linux kernel package from Clear Linux +#. Clone the Linux kernel package from |CL|. .. code-block:: bash cd ~/clearlinux make clone_linux -#. Navigate into the cloned package directory +#. Navigate into the cloned package directory. .. code-block:: bash @@ -77,7 +75,7 @@ clone the existing kernel package repository from |CL| as a starting point. .. note:: The "linux" package is the kernel that comes with |CL| in the kernel-native bundle. You can alternatively use a different kernel variant as the base for modification. - For a list of kernel package names which you can clone instead, see the `clearlinux-pkgs GitHub`. + For a list of kernel package names which you can clone instead, see the `clearlinux-pkgs GitHub`_. Change the kernel version @@ -92,13 +90,13 @@ RPM SPEC file. :ref:`autospec`, the kernel is not. This means control files provided by autospec are not available and changes must be made directly. -#. Open the Linux kernel package RPM SPEC file in an editor +#. Open the Linux kernel package RPM SPEC file in an editor. .. code-block:: bash $EDITOR linux.spec -#. Modify the Version, Release, and Source0 URL entries at the top of the file +#. Modify the Version, Release, and Source0 URL entries at the top of the file. .. code-block:: bash @@ -133,7 +131,7 @@ unique configuration changes that have been made and makes applying any future default configuration values easier. The :file:`config-fragment` is the only file that is modified and is -eventually merged or overlaid with the main :file:`.config`. +eventually merged with the main :file:`.config`. @@ -180,7 +178,7 @@ eventually merged or overlaid with the main :file:`.config`. .. note:: - If you hae a large number of patches or a more complex workflow, + If you have a large number of patches or a more complex workflow, consider using a patch management tool in addition to Git such as `Quilt`_. Modify kernel source code @@ -197,6 +195,7 @@ Changes to kernel code are applied with patch files. Patch files are formatted g #. Make any code changes to the Linux source files #. Track and commit your changes to the local git repo. + .. code-block:: bash git commit -m "My patch for driver A" @@ -211,19 +210,19 @@ Changes to kernel code are applied with patch files. Patch files are formatted g git format-patch - #. Copy the patch files from the patches directory in the linux - source tree to the RPM build directory + source tree to the RPM build directory. .. code-block:: bash cp patches/*.patch ~/clearlinux/packages/linux/ -#. Navigate back to the RPM build directory +#. Navigate back to the RPM build directory. .. code-block:: bash cd ~/clearlinux/packages/linux/ -#. Open the Linux kernel package RPM SPEC file in an editor +#. Open the Linux kernel package RPM SPEC file in an editor. .. code-block:: bash @@ -272,8 +271,8 @@ Changes to kernel code are applied with patch files. Patch files are formatted g #. Commit and save the changes to the RPM SPEC file. -Build and install a kernel -========================== +Build and install the kernel +============================ After changes have been made to the kernel SPEC file and config file, the kernel is ready to be compiled and packaged into a RPM. @@ -300,22 +299,38 @@ the kernel is ready to be compiled and packaged into a RPM. bundle and mix of |CL|. -Alternatively, the kernel RPM bundle can be installed locally for testing -with the :command:`rpm` command. +Alternatively, the kernel RPM bundle can be installed manually on a local +machine for testing. This approach works well for individual development or +testing. For a more scalable and customizable approach, consider using the +`mixer tool`_ to provide a custom kernel with updates. + +1. Install the os-core-dev bundle which contains install dependencies, + such as systemd binaries. + + .. code-block:: bash + + swupd bundle-add os-core-dev + +#. Install with the rpm command. -1. Install with the rpm command .. code-block:: bash sudo rpm -ivh linux-custom...x86_64.rpm -#. Update the |CL| boot manager using :command:`clr-boot-manager` - sudo clr-boot-manager list-kernels +#. Update the |CL| boot manager using :command:`clr-boot-manager` and reboot. .. code-block:: bash sudo clr-boot-manager list-kernels sudo clr-boot-manager set-kernel + sudo reboot + +#. After a reboot, verify the customized kernel is running. + + .. code-block:: bash + + uname -a From 1ad731f4cc64d9fe9fffe270238586ca0475c6a7 Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Thu, 31 Jan 2019 15:58:59 -0800 Subject: [PATCH 04/35] Remove os-core-dev requirement --- .../guides/maintenance/kernel-development.rst | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index e2c1ca5c..88e32c31 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -304,14 +304,7 @@ machine for testing. This approach works well for individual development or testing. For a more scalable and customizable approach, consider using the `mixer tool`_ to provide a custom kernel with updates. -1. Install the os-core-dev bundle which contains install dependencies, - such as systemd binaries. - - .. code-block:: bash - - swupd bundle-add os-core-dev - -#. Install with the rpm command. +1. Install the kernel RPM onto the local system with the :command:`rpm` command. .. code-block:: bash From b24e78c61a60e86f1f06662ed6f091b5bc4685ad Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Fri, 1 Feb 2019 21:24:21 -0800 Subject: [PATCH 05/35] Add note about SRPM and formatting fixes --- .../guides/maintenance/kernel-development.rst | 54 ++++++++++++++----- 1 file changed, 42 insertions(+), 12 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index 88e32c31..bfb99d72 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -11,7 +11,7 @@ The |CL| kernels aim to be performant and practical. In some cases, it may be necessary modify the kernel to suit your specific needs or test new kernel code as a developer. -In cases where drivers beyond those enabled by default in |CL-ATTR| are +In cases where features beyond those enabled by default in |CL-ATTR| are needed it may be necessary to: .. contents:: :local: @@ -26,7 +26,8 @@ If the kernel modification you need is already open source and likely to be useful to others, consider submitting a request to add or enable in the |CL| kernel. -If your change request is accepted, you do not need to maintain your own modified kernel. +If your change request is accepted, you do not need to maintain your own +modified kernel. Make enhancement requests to the |CL| distribution `on GitHub`_ . @@ -39,12 +40,20 @@ needs or test new kernel code as a developer. You can build and install a custom kernel, however you must: -* Disable secure boot +* Disable Secure Boot * Maintain any updates to the kernel going forward -To customize the kernel you will need a |CL| development evnironment, +To customize the kernel you will need a |CL| development environment, make changes to the kernel, build the kernel, and install it. +.. note:: + + This document shows how to obtain and compile a Linux kernel source + using the |CL| development tooling. + + Source RPM files (SRPM) are available for all |CL| kernels, and can be used for development instead. + The latest source RPM files are available at: `https://download.clearlinux.org/current/source/SRPMS/`_ + Install the |CL| development tooling framework ---------------------------------------------- @@ -57,7 +66,7 @@ Install the |CL| development tooling framework Clone the Linux kernel package ------------------------------ -clone the existing kernel package repository from |CL| as a starting point. +Clone the existing kernel package re-pository from |CL| as a starting point. #. Clone the Linux kernel package from |CL|. @@ -66,6 +75,7 @@ clone the existing kernel package repository from |CL| as a starting point. cd ~/clearlinux make clone_linux + #. Navigate into the cloned package directory. .. code-block:: bash @@ -81,7 +91,7 @@ clone the existing kernel package repository from |CL| as a starting point. Change the kernel version ------------------------- -|CL| tends to use the latest kernel available from kernel.org, the Linux +|CL| tends to use the latest kernel available from `kernel.org`_, the Linux upstream. The kernel version that will be built can be changed in the RPM SPEC file. @@ -96,7 +106,9 @@ RPM SPEC file. $EDITOR linux.spec -#. Modify the Version, Release, and Source0 URL entries at the top of the file. + +#. Modify the Version, Release, and Source0 URL entries at the top of the + file. .. code-block:: bash @@ -143,7 +155,9 @@ eventually merged with the main :file:`.config`. .. note:: Due to how |CL| packaging tools make use of :command:`mock` environments - psuedo-GUI tools that abstract kernel configuration such as menuconfig do not work. + psuedo-GUI tools that abstract kernel configuration such as menuconfig + do not work. + #. Find the configuration values you are looking for. If a particular setting does not already exist , it can be added manually. @@ -179,12 +193,14 @@ eventually merged with the main :file:`.config`. .. note:: If you have a large number of patches or a more complex workflow, - consider using a patch management tool in addition to Git such as `Quilt`_. + consider using a patch management tool in addition to Git such as + `Quilt`_. Modify kernel source code ------------------------- -Changes to kernel code are applied with patch files. Patch files are formatted git commits that can be applied to the main source code. +Changes to kernel code are applied with patch files. Patch files are +formatted git commits that can be applied to the main source code. #. Clone the linux kernel source code into a new working directory @@ -192,14 +208,17 @@ Changes to kernel code are applied with patch files. Patch files are formatted g git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + #. Make any code changes to the Linux source files + #. Track and commit your changes to the local git repo. .. code-block:: bash git commit -m "My patch for driver A" + #. Generate a patch file based on your git commits. represents the number of local commits to create patch file. See the `git-format-patch Documentation`_ for detailed information @@ -209,6 +228,7 @@ Changes to kernel code are applied with patch files. Patch files are formatted g git format-patch - + #. Copy the patch files from the patches directory in the linux source tree to the RPM build directory. @@ -216,12 +236,14 @@ Changes to kernel code are applied with patch files. Patch files are formatted g cp patches/*.patch ~/clearlinux/packages/linux/ + #. Navigate back to the RPM build directory. .. code-block:: bash cd ~/clearlinux/packages/linux/ + #. Open the Linux kernel package RPM SPEC file in an editor. .. code-block:: bash @@ -271,6 +293,7 @@ Changes to kernel code are applied with patch files. Patch files are formatted g #. Commit and save the changes to the RPM SPEC file. + Build and install the kernel ============================ After changes have been made to the kernel SPEC file and config file, @@ -283,6 +306,7 @@ the kernel is ready to be compiled and packaged into a RPM. make build + #. The result there will be multiple :file:`.rpm` files in the :file:`rpms` directory as output. @@ -293,12 +317,11 @@ the kernel is ready to be compiled and packaged into a RPM. The kernel RPM will be named :file:`linux-.x86_64.rpm` - - #. The kernel RPM file can be input to the `mixer tool`_ to create a custom bundle and mix of |CL|. + Alternatively, the kernel RPM bundle can be installed manually on a local machine for testing. This approach works well for individual development or testing. For a more scalable and customizable approach, consider using the @@ -327,9 +350,16 @@ testing. For a more scalable and customizable approach, consider using the +Related topics: + + * :ref:`kernel-modules` + * :ref:`mixer` + .. _`on GitHub`: https://github.com/clearlinux/distribution +.. _`https://download.clearlinux.org/current/source/SRPMS/`: https://download.clearlinux.org/current/source/SRPMS/ .. _`mixer tool`: https://clearlinux.org/features/mixer-tool .. _user-setup script: https://github.com/clearlinux/common/blob/master/user-setup.sh .. _`Quilt`: http://savannah.nongnu.org/projects/quilt .. _`clearlinux-pkgs GitHub`: https://github.com/clearlinux-pkgs?&q=linux +.. _`kernel.org`: https://www.kernel.org/ .. _`git-format-patch Documentation`: https://git-scm.com/docs/git-format-patch From 38b0e9772f264e444becf754594690785a87d4b5 Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Mon, 4 Feb 2019 13:29:16 -0800 Subject: [PATCH 06/35] Implement suggestioned by @bktan1 --- .../guides/maintenance/kernel-development.rst | 34 +++++++++---------- 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index bfb99d72..a5bea372 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -11,13 +11,18 @@ The |CL| kernels aim to be performant and practical. In some cases, it may be necessary modify the kernel to suit your specific needs or test new kernel code as a developer. -In cases where features beyond those enabled by default in |CL-ATTR| are -needed it may be necessary to: +This document shows how to obtain and compile a Linux kernel source +using the |CL-ATTR| development tooling. + .. contents:: :local: :depth: 2 :backlinks: top +Source RPM files (SRPM) are also available for all |CL| kernels, and can be +used for development instead. The latest source RPM files are available at: +`https://download.clearlinux.org/current/source/SRPMS/`_ + Request the change be included with the |CL| kernel =================================================== @@ -35,7 +40,7 @@ Make enhancement requests to the |CL| distribution `on GitHub`_ . Customize the Linux kernel source ================================= -In some cases, it may be necessary modify the kernel to suit your specific +In some cases, it may be necessary to modify the kernel to suit your specific needs or test new kernel code as a developer. You can build and install a custom kernel, however you must: @@ -46,13 +51,6 @@ You can build and install a custom kernel, however you must: To customize the kernel you will need a |CL| development environment, make changes to the kernel, build the kernel, and install it. -.. note:: - - This document shows how to obtain and compile a Linux kernel source - using the |CL| development tooling. - - Source RPM files (SRPM) are available for all |CL| kernels, and can be used for development instead. - The latest source RPM files are available at: `https://download.clearlinux.org/current/source/SRPMS/`_ Install the |CL| development tooling framework @@ -66,7 +64,7 @@ Install the |CL| development tooling framework Clone the Linux kernel package ------------------------------ -Clone the existing kernel package re-pository from |CL| as a starting point. +Clone the existing kernel package repository from |CL| as a starting point. #. Clone the Linux kernel package from |CL|. @@ -98,7 +96,7 @@ RPM SPEC file. .. note:: While most packages in Clear Linux are typically packaged using :ref:`autospec`, the kernel is not. This means control files provided - by autospec are not available and changes must be made directly. + by autospec are not available and changes must be made manually. #. Open the Linux kernel package RPM SPEC file in an editor. @@ -142,7 +140,7 @@ instead of directly editing the :file:`.config` file helps identify the unique configuration changes that have been made and makes applying any future default configuration values easier. -The :file:`config-fragment` is the only file that is modified and is +The :file:`config-fragment` is the **only** file that is modified and is eventually merged with the main :file:`.config`. @@ -160,10 +158,10 @@ eventually merged with the main :file:`.config`. #. Find the configuration values you are looking for. - If a particular setting does not already exist , it can be added manually. + If a particular setting does not already exist, it can be added manually. - For example, BTRFS support configuration is below indicating it is - enabled in-tree. + For example, the snippet below shows BTRFS support configuration indicating + it is enabled in-tree. .. code-block:: bash @@ -172,8 +170,8 @@ eventually merged with the main :file:`.config`. #. Modify the configuration values as desired. - For example, to disable BTRFS support change the configuration to be - commented out. + For example, the snippet below shows BTRFS support configuration changed + change to be disabled and commented out. .. code-block:: bash From b49e9089e95ccc472bfcb3bc6f0f3a92d8b6339f Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Mon, 4 Feb 2019 13:31:45 -0800 Subject: [PATCH 07/35] Add link to CL kernels reference page --- source/clear-linux/guides/maintenance/kernel-development.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index a5bea372..83b1c182 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -7,7 +7,7 @@ The kernel is the heart of an operating system with many things relying on it to provide access to hardware and software functionality. The Linux kernel is very customizable and extensible. -The |CL| kernels aim to be performant and practical. In some cases, it may be +The `Clear Linux kernels`_ aim to be performant and practical. In some cases, it may be necessary modify the kernel to suit your specific needs or test new kernel code as a developer. @@ -353,6 +353,7 @@ Related topics: * :ref:`kernel-modules` * :ref:`mixer` +.. _`Clear Linux kernels`: https://clearlinux.org/documentation/clear-linux/reference/compatible-kernels .. _`on GitHub`: https://github.com/clearlinux/distribution .. _`https://download.clearlinux.org/current/source/SRPMS/`: https://download.clearlinux.org/current/source/SRPMS/ .. _`mixer tool`: https://clearlinux.org/features/mixer-tool From c9fcd7f298e773a3ff202e0e60322af875517cd1 Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Mon, 4 Feb 2019 14:02:01 -0800 Subject: [PATCH 08/35] Reduce usage of notes and fix code-blocks --- .../guides/maintenance/kernel-development.rst | 118 +++++++++--------- 1 file changed, 62 insertions(+), 56 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index 83b1c182..a10ad67c 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -7,9 +7,9 @@ The kernel is the heart of an operating system with many things relying on it to provide access to hardware and software functionality. The Linux kernel is very customizable and extensible. -The `Clear Linux kernels`_ aim to be performant and practical. In some cases, it may be -necessary modify the kernel to suit your specific needs or test new kernel -code as a developer. +The `kernels available in Clear Linux`_ aim to be performant and practical. +In some cases, it may be necessary modify the kernel to suit your specific +needs or test new kernel code as a developer. This document shows how to obtain and compile a Linux kernel source using the |CL-ATTR| development tooling. @@ -28,8 +28,8 @@ Request the change be included with the |CL| kernel =================================================== If the kernel modification you need is already open source and likely to be -useful to others, consider submitting a request to add or enable in the -|CL| kernel. +useful to others, consider submitting a request to include it in the +|CL| kernels. If your change request is accepted, you do not need to maintain your own modified kernel. @@ -86,6 +86,7 @@ Clone the existing kernel package repository from |CL| as a starting point. For a list of kernel package names which you can clone instead, see the `clearlinux-pkgs GitHub`_. + Change the kernel version ------------------------- @@ -93,10 +94,10 @@ Change the kernel version upstream. The kernel version that will be built can be changed in the RPM SPEC file. -.. note:: - While most packages in Clear Linux are typically packaged using - :ref:`autospec`, the kernel is not. This means control files provided - by autospec are not available and changes must be made manually. +While most packages in Clear Linux are typically packaged using +`autospec`_, the kernel is not. This means control files provided +by autospec are not available and changes must be made manually. + #. Open the Linux kernel package RPM SPEC file in an editor. @@ -106,9 +107,9 @@ RPM SPEC file. #. Modify the Version, Release, and Source0 URL entries at the top of the - file. + file to change the version of Linux kernel to be compiled. - .. code-block:: bash + .. code-block:: bash Name: linux Version: 4.20.5 @@ -122,11 +123,12 @@ RPM SPEC file. Source2: cmdline .. note:: - TIP: Consider changing the Name in the RPM spec file to easily identify a modified kernel. + Consider changing the Name in the RPM spec file to easily identify a modified kernel. #. Commit and save the changes to the file + Modify kernel configuration --------------------------- @@ -146,16 +148,15 @@ eventually merged with the main :file:`.config`. #. Open the kernel :file:`config-fragment` file in an editor. + + Due to how |CL| packaging tools make use of :command:`mock` environments + psuedo-GUI tools that abstract kernel configuration such as menuconfig do + not work. .. code-block:: bash $EDITOR config-fragment - .. note:: - Due to how |CL| packaging tools make use of :command:`mock` environments - psuedo-GUI tools that abstract kernel configuration such as menuconfig - do not work. - #. Find the configuration values you are looking for. If a particular setting does not already exist, it can be added manually. @@ -163,20 +164,21 @@ eventually merged with the main :file:`.config`. For example, the snippet below shows BTRFS support configuration indicating it is enabled in-tree. - .. code-block:: bash - - CONFIG_BTRFS_FS=y - CONFIG_BTRFS_FS_POSIX_ACL=y + .. code-block:: bash + + CONFIG_BTRFS_FS=y + CONFIG_BTRFS_FS_POSIX_ACL=y #. Modify the configuration values as desired. + For example, the snippet below shows BTRFS support configuration changed change to be disabled and commented out. - .. code-block:: bash + .. code-block:: bash - # CONFIG_BTRFS_FS is not set - # CONFIG_BTRFS_FS_POSIX_ACL is not set + # CONFIG_BTRFS_FS is not set + # CONFIG_BTRFS_FS_POSIX_ACL is not set #. Commit and save the changes to the :file:`config-fragment` file. @@ -184,15 +186,16 @@ eventually merged with the main :file:`.config`. #. Run the :command:`make config` command to apply the changes made in the :file:`config-fragment` file and regenerate the :file:`config` file. - .. code-block:: bash - - make config + .. code-block:: bash + + make config + + +If you have a large number of patches or a more complex workflow, +consider using a patch management tool in addition to Git such as +`Quilt`_. -.. note:: - If you have a large number of patches or a more complex workflow, - consider using a patch management tool in addition to Git such as - `Quilt`_. Modify kernel source code ------------------------- @@ -202,9 +205,9 @@ formatted git commits that can be applied to the main source code. #. Clone the linux kernel source code into a new working directory - .. code-block:: bash - - git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + .. code-block:: bash + + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git #. Make any code changes to the Linux source files @@ -212,9 +215,9 @@ formatted git commits that can be applied to the main source code. #. Track and commit your changes to the local git repo. - .. code-block:: bash - - git commit -m "My patch for driver A" + .. code-block:: bash + + git commit -m "My patch for driver A" #. Generate a patch file based on your git commits. @@ -222,24 +225,24 @@ formatted git commits that can be applied to the main source code. See the `git-format-patch Documentation`_ for detailed information on using :command:`git format-patch` - .. code-block:: bash + .. code-block:: bash - git format-patch - + git format-patch - #. Copy the patch files from the patches directory in the linux source tree to the RPM build directory. - .. code-block:: bash + .. code-block:: bash - cp patches/*.patch ~/clearlinux/packages/linux/ + cp patches/*.patch ~/clearlinux/packages/linux/ #. Navigate back to the RPM build directory. - .. code-block:: bash + .. code-block:: bash - cd ~/clearlinux/packages/linux/ + cd ~/clearlinux/packages/linux/ #. Open the Linux kernel package RPM SPEC file in an editor. @@ -300,17 +303,17 @@ the kernel is ready to be compiled and packaged into a RPM. #. Start the compilation process by issuing the :command:`make build` command. This process is typically resource intensive and will take a while. - .. code-block:: bash + .. code-block:: bash - make build + make build #. The result there will be multiple :file:`.rpm` files in the :file:`rpms` directory as output. - .. code-block:: bash + .. code-block:: bash - ls rpms/ + ls rpms/ The kernel RPM will be named :file:`linux-.x86_64.rpm` @@ -327,24 +330,26 @@ testing. For a more scalable and customizable approach, consider using the 1. Install the kernel RPM onto the local system with the :command:`rpm` command. - .. code-block:: bash + .. code-block:: bash - sudo rpm -ivh linux-custom...x86_64.rpm + sudo rpm -ivh linux-custom...x86_64.rpm #. Update the |CL| boot manager using :command:`clr-boot-manager` and reboot. - .. code-block:: bash + .. code-block:: bash - sudo clr-boot-manager list-kernels + sudo clr-boot-manager update - sudo clr-boot-manager set-kernel - sudo reboot + sudo clr-boot-manager list-kernels + sudo clr-boot-manager set-kernel + + sudo reboot #. After a reboot, verify the customized kernel is running. - .. code-block:: bash + .. code-block:: bash - uname -a + uname -a @@ -353,7 +358,7 @@ Related topics: * :ref:`kernel-modules` * :ref:`mixer` -.. _`Clear Linux kernels`: https://clearlinux.org/documentation/clear-linux/reference/compatible-kernels +.. _`kernels available in Clear Linux`: https://clearlinux.org/documentation/clear-linux/reference/compatible-kernels .. _`on GitHub`: https://github.com/clearlinux/distribution .. _`https://download.clearlinux.org/current/source/SRPMS/`: https://download.clearlinux.org/current/source/SRPMS/ .. _`mixer tool`: https://clearlinux.org/features/mixer-tool @@ -361,4 +366,5 @@ Related topics: .. _`Quilt`: http://savannah.nongnu.org/projects/quilt .. _`clearlinux-pkgs GitHub`: https://github.com/clearlinux-pkgs?&q=linux .. _`kernel.org`: https://www.kernel.org/ +.. _`autospec`: https://clearlinux.org/documentation/clear-linux/concepts/autospec-about .. _`git-format-patch Documentation`: https://git-scm.com/docs/git-format-patch From 28d4bed8810c94c0297e6eb2073e4e879e50e8f7 Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Mon, 4 Feb 2019 14:23:19 -0800 Subject: [PATCH 09/35] Implement changes requested by @mvincerx --- .../guides/maintenance/kernel-development.rst | 37 ++++++++----------- .../guides/maintenance/maintenance.rst | 1 + 2 files changed, 17 insertions(+), 21 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index a10ad67c..93d1d3d4 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -3,17 +3,12 @@ Kernel development on Clear Linux ################################# -The kernel is the heart of an operating system with many things relying on it -to provide access to hardware and software functionality. -The Linux kernel is very customizable and extensible. - -The `kernels available in Clear Linux`_ aim to be performant and practical. -In some cases, it may be necessary modify the kernel to suit your specific -needs or test new kernel code as a developer. - This document shows how to obtain and compile a Linux kernel source using the |CL-ATTR| development tooling. +The `kernels available in Clear Linux`_ aim to be performant and practical. +In some cases, it may be necessary modify the kernel to suit your specific +needs or test new kernel code as a developer. .. contents:: :local: :depth: 2 @@ -48,8 +43,8 @@ You can build and install a custom kernel, however you must: * Disable Secure Boot * Maintain any updates to the kernel going forward -To customize the kernel you will need a |CL| development environment, -make changes to the kernel, build the kernel, and install it. +To create a custom kernel, start with the |CL| development environment. +Then make changes to the kernel, build it, and install it. @@ -111,16 +106,16 @@ by autospec are not available and changes must be made manually. .. code-block:: bash - Name: linux - Version: 4.20.5 - Release: 690 - License: GPL-2.0 - Summary: The Linux kernel - Url: http://www.kernel.org/ - Group: kernel - Source0: https://cdn.kernel.org/pub/linux/kernel/v4.x/linux-4.20.5.tar.xz - Source1: config - Source2: cmdline + Name: linux + Version: 4.20.5 + Release: 690 + License: GPL-2.0 + Summary: The Linux kernel + Url: http://www.kernel.org/ + Group: kernel + Source0: https://cdn.kernel.org/pub/linux/kernel/v4.x/linux-4.20.5.tar.xz + Source1: config + Source2: cmdline .. note:: Consider changing the Name in the RPM spec file to easily identify a modified kernel. @@ -342,7 +337,7 @@ testing. For a more scalable and customizable approach, consider using the sudo clr-boot-manager list-kernels sudo clr-boot-manager set-kernel - + sudo reboot #. After a reboot, verify the customized kernel is running. diff --git a/source/clear-linux/guides/maintenance/maintenance.rst b/source/clear-linux/guides/maintenance/maintenance.rst index 3d89fa54..69683316 100644 --- a/source/clear-linux/guides/maintenance/maintenance.rst +++ b/source/clear-linux/guides/maintenance/maintenance.rst @@ -16,6 +16,7 @@ completed. enable-user-space swupd-guide bulk-provision + kernel-development kernel-modules mixer mixin From b7d6154805ed77df56e32487f37580866425dd17 Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Tue, 5 Feb 2019 14:03:59 -0800 Subject: [PATCH 10/35] Fix headers --- .../guides/maintenance/kernel-development.rst | 21 ++++++++++--------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index 93d1d3d4..293628d3 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -20,7 +20,7 @@ used for development instead. The latest source RPM files are available at: Request the change be included with the |CL| kernel -=================================================== +*************************************************** If the kernel modification you need is already open source and likely to be useful to others, consider submitting a request to include it in the @@ -33,7 +33,7 @@ Make enhancement requests to the |CL| distribution `on GitHub`_ . Customize the Linux kernel source -================================= +********************************* In some cases, it may be necessary to modify the kernel to suit your specific needs or test new kernel code as a developer. @@ -49,7 +49,7 @@ Then make changes to the kernel, build it, and install it. Install the |CL| development tooling framework ----------------------------------------------- +============================================== .. include:: autospec.rst :start-after: install-tooling-after-header: @@ -58,7 +58,7 @@ Install the |CL| development tooling framework Clone the Linux kernel package ------------------------------- +============================== Clone the existing kernel package repository from |CL| as a starting point. #. Clone the Linux kernel package from |CL|. @@ -83,7 +83,7 @@ Clone the existing kernel package repository from |CL| as a starting point. Change the kernel version -------------------------- +========================= |CL| tends to use the latest kernel available from `kernel.org`_, the Linux upstream. The kernel version that will be built can be changed in the @@ -125,7 +125,7 @@ by autospec are not available and changes must be made manually. Modify kernel configuration ---------------------------- +=========================== Existing kernel features and in-tree kernel modules can be enabled or disabled in the kernel configuration file, :file:`.config` , at compile time. @@ -193,7 +193,7 @@ consider using a patch management tool in addition to Git such as Modify kernel source code -------------------------- +========================= Changes to kernel code are applied with patch files. Patch files are formatted git commits that can be applied to the main source code. @@ -348,10 +348,11 @@ testing. For a more scalable and customizable approach, consider using the -Related topics: +Related topics +************** - * :ref:`kernel-modules` - * :ref:`mixer` +* :ref:`kernel-modules` +* :ref:`mixer` .. _`kernels available in Clear Linux`: https://clearlinux.org/documentation/clear-linux/reference/compatible-kernels .. _`on GitHub`: https://github.com/clearlinux/distribution From 76166d83e966d9ec834bd30424045c44438fbe9b Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Tue, 5 Feb 2019 14:18:40 -0800 Subject: [PATCH 11/35] Move patch management suggestion --- .../guides/maintenance/kernel-development.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index 293628d3..3816a5eb 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -186,11 +186,6 @@ eventually merged with the main :file:`.config`. make config -If you have a large number of patches or a more complex workflow, -consider using a patch management tool in addition to Git such as -`Quilt`_. - - Modify kernel source code ========================= @@ -198,6 +193,11 @@ Modify kernel source code Changes to kernel code are applied with patch files. Patch files are formatted git commits that can be applied to the main source code. +If you have a large number of patches or a more complex workflow, +consider using a patch management tool in addition to Git such as +`Quilt`_. + + #. Clone the linux kernel source code into a new working directory .. code-block:: bash @@ -291,7 +291,7 @@ formatted git commits that can be applied to the main source code. Build and install the kernel -============================ +**************************** After changes have been made to the kernel SPEC file and config file, the kernel is ready to be compiled and packaged into a RPM. From e3e2ce46cc5237d74976efc25dd088403b512e5c Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Wed, 6 Feb 2019 10:54:42 -0800 Subject: [PATCH 12/35] Add comment about where to find kernel releases --- source/clear-linux/guides/maintenance/kernel-development.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index 3816a5eb..715f1883 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -102,7 +102,10 @@ by autospec are not available and changes must be made manually. #. Modify the Version, Release, and Source0 URL entries at the top of the - file to change the version of Linux kernel to be compiled. + file to change the version of Linux kernel that will be compiled. + + A list of current and available kernel release can be found on + `kernel.org`_. .. code-block:: bash From 63244c3cdcfc6b6fd33c9089659f86638dae737f Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Wed, 6 Feb 2019 10:59:32 -0800 Subject: [PATCH 13/35] Fix missing periods at end of list items --- .../clear-linux/guides/maintenance/kernel-development.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index 715f1883..df1c95bc 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -123,7 +123,7 @@ by autospec are not available and changes must be made manually. .. note:: Consider changing the Name in the RPM spec file to easily identify a modified kernel. -#. Commit and save the changes to the file +#. Commit and save the changes to the file. @@ -201,14 +201,14 @@ consider using a patch management tool in addition to Git such as `Quilt`_. -#. Clone the linux kernel source code into a new working directory +#. Clone the linux kernel source code into a new working directory. .. code-block:: bash git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git -#. Make any code changes to the Linux source files +#. Make any code changes to the Linux source files. #. Track and commit your changes to the local git repo. From 4a6dcbdd0ecfa339bb9b45b50fb66373f72ffda0 Mon Sep 17 00:00:00 2001 From: "Brett T. Warden" <4c0e8e88@tm.wgz.org> Date: Fri, 8 Feb 2019 18:46:14 +0000 Subject: [PATCH 14/35] Fix missing word by @bwarden Co-Authored-By: puneetse <22071208+puneetse@users.noreply.github.com> --- source/clear-linux/guides/maintenance/kernel-development.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index df1c95bc..4c157781 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -7,7 +7,7 @@ This document shows how to obtain and compile a Linux kernel source using the |CL-ATTR| development tooling. The `kernels available in Clear Linux`_ aim to be performant and practical. -In some cases, it may be necessary modify the kernel to suit your specific +In some cases, it may be necessary to modify the kernel to suit your specific needs or test new kernel code as a developer. .. contents:: :local: From d4533e5f2316996a53b5161f7129767c3b812a90 Mon Sep 17 00:00:00 2001 From: "Brett T. Warden" <4c0e8e88@tm.wgz.org> Date: Fri, 8 Feb 2019 19:15:21 +0000 Subject: [PATCH 15/35] Fix a to an by @bwarden Co-Authored-By: puneetse <22071208+puneetse@users.noreply.github.com> --- source/clear-linux/guides/maintenance/kernel-development.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index 4c157781..4be4080f 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -296,7 +296,7 @@ consider using a patch management tool in addition to Git such as Build and install the kernel **************************** After changes have been made to the kernel SPEC file and config file, -the kernel is ready to be compiled and packaged into a RPM. +the kernel is ready to be compiled and packaged into an RPM. #. Start the compilation process by issuing the :command:`make build` command. This process is typically resource intensive and will take a while. From 37acf6fe5fa96bb7af3168f6a7afd0979d19d606 Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Wed, 13 Feb 2019 10:47:42 -0800 Subject: [PATCH 16/35] Fix typo --- source/clear-linux/guides/maintenance/kernel-development.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index df1c95bc..305ed6f2 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -306,7 +306,7 @@ the kernel is ready to be compiled and packaged into a RPM. make build -#. The result there will be multiple :file:`.rpm` files in the :file:`rpms` +#. The result will be multiple :file:`.rpm` files in the :file:`rpms` directory as output. .. code-block:: bash From dd81d28fc0a687204c8c1be140ed0fb40fae29d8 Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Wed, 13 Feb 2019 16:46:46 -0800 Subject: [PATCH 17/35] Reword note about menuconfig --- .../guides/maintenance/kernel-development.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index df6f2dd3..ab5869b8 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -146,10 +146,6 @@ eventually merged with the main :file:`.config`. #. Open the kernel :file:`config-fragment` file in an editor. - - Due to how |CL| packaging tools make use of :command:`mock` environments - psuedo-GUI tools that abstract kernel configuration such as menuconfig do - not work. .. code-block:: bash @@ -188,6 +184,15 @@ eventually merged with the main :file:`.config`. make config +.. note:: + + The |CL| packaging tools make use of :command:`mock` environments for + building software. + + If you want to make use of GUI tools to edit the kernel confguration, such as + :command:`menuconfig`, instead of manually editing the :file:`config` + file, you can from the :command:`mock` environment under + :file:`/var/lib/mock/clear-linux/root/builddir/build/BUILD/kernel-*` Modify kernel source code From 4287088ec10822f0df0fde433183c065f2518d10 Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Thu, 14 Feb 2019 15:43:43 -0800 Subject: [PATCH 18/35] Add tip on switching git tag --- .../clear-linux/guides/maintenance/kernel-development.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index ab5869b8..f9e1bc72 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -80,8 +80,16 @@ Clone the existing kernel package repository from |CL| as a starting point. You can alternatively use a different kernel variant as the base for modification. For a list of kernel package names which you can clone instead, see the `clearlinux-pkgs GitHub`_. + The latest version of the |CL| kernel package is pulled as a starting + point. An older version can pulled by switching to different git tag with + :command:`git checkout tag/${TAG_NAME}` tag. + + + + + Change the kernel version ========================= From 9b996f7b98fc24ee6f0638eb12d73a603ef2d141 Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Thu, 14 Feb 2019 15:47:57 -0800 Subject: [PATCH 19/35] Add tip to change the ktarget name --- .../guides/maintenance/kernel-development.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index f9e1bc72..70d96bc9 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -87,9 +87,6 @@ Clone the existing kernel package repository from |CL| as a starting point. - - - Change the kernel version ========================= @@ -118,18 +115,23 @@ by autospec are not available and changes must be made manually. .. code-block:: bash Name: linux - Version: 4.20.5 - Release: 690 + Version: 4.20.8 + Release: 696 License: GPL-2.0 Summary: The Linux kernel Url: http://www.kernel.org/ Group: kernel - Source0: https://cdn.kernel.org/pub/linux/kernel/v4.x/linux-4.20.5.tar.xz + Source0: https://cdn.kernel.org/pub/linux/kernel/v4.x/linux-4.20.8.tar.xz Source1: config Source2: cmdline + %define ktarget native + .. note:: - Consider changing the Name in the RPM spec file to easily identify a modified kernel. + Consider changing the Name from *linux* in the RPM spec file to easily identify a modified kernel. + + Consider changing the ktarget from *native* in the RPM spec file to easily identify a modified kernel. + #. Commit and save the changes to the file. From 3f8156992b98e13db0fd0fc77a74894e1574b4c8 Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Thu, 14 Feb 2019 15:53:41 -0800 Subject: [PATCH 20/35] Chame rpm install to use rpm2cpio --- .../guides/maintenance/kernel-development.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index 70d96bc9..66cacc22 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -129,7 +129,7 @@ by autospec are not available and changes must be made manually. .. note:: Consider changing the Name from *linux* in the RPM spec file to easily identify a modified kernel. - + Consider changing the ktarget from *native* in the RPM spec file to easily identify a modified kernel. @@ -328,7 +328,7 @@ the kernel is ready to be compiled and packaged into an RPM. ls rpms/ - The kernel RPM will be named :file:`linux-.x86_64.rpm` + The kernel RPM will be named :file:`linux%{name}-%{version}-%{release}.x86_64.rpm` #. The kernel RPM file can be input to the `mixer tool`_ to create a custom @@ -341,20 +341,18 @@ machine for testing. This approach works well for individual development or testing. For a more scalable and customizable approach, consider using the `mixer tool`_ to provide a custom kernel with updates. -1. Install the kernel RPM onto the local system with the :command:`rpm` command. +1. Install the kernel onto the local system by extracting the RPM with the :command:`rpm2cpio` command. .. code-block:: bash - sudo rpm -ivh linux-custom...x86_64.rpm + sudo rpm2cpio linux%{name}-%{version}-%{release}.x86_64.rpm | (cd /; sudo cpio -i -d -u -v); #. Update the |CL| boot manager using :command:`clr-boot-manager` and reboot. .. code-block:: bash - sudo clr-boot-manager update - sudo clr-boot-manager list-kernels - sudo clr-boot-manager set-kernel + sudo clr-boot-manager set-kernel org.clearlinux.${Target}.%{version}-%{release} sudo reboot From 07eecae52ce3c275430329d1fd94c0fbf14b7d4b Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Thu, 14 Feb 2019 16:39:20 -0800 Subject: [PATCH 21/35] Update to use CL tooling to get exact kernel source --- .../guides/maintenance/kernel-development.rst | 44 +++++++++++++++---- 1 file changed, 35 insertions(+), 9 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index 66cacc22..1145dda8 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -78,7 +78,8 @@ Clone the existing kernel package repository from |CL| as a starting point. .. note:: The "linux" package is the kernel that comes with |CL| in the kernel-native bundle. You can alternatively use a different kernel variant as the base for modification. - For a list of kernel package names which you can clone instead, see the `clearlinux-pkgs GitHub`_. + For a list of kernel package names which you can clone instead, + see the `clearlinux-pkgs GitHub`_. The latest version of the |CL| kernel package is pulled as a starting point. An older version can pulled by switching to different git tag with @@ -128,9 +129,11 @@ by autospec are not available and changes must be made manually. %define ktarget native .. note:: - Consider changing the Name from *linux* in the RPM spec file to easily identify a modified kernel. + Consider changing the Name from *linux* in the RPM spec file to easily + identify a modified kernel. - Consider changing the ktarget from *native* in the RPM spec file to easily identify a modified kernel. + Consider changing the ktarget from *native* in the RPM spec file to easily + identify a modified kernel. #. Commit and save the changes to the file. @@ -211,26 +214,45 @@ Modify kernel source code Changes to kernel code are applied with patch files. Patch files are formatted git commits that can be applied to the main source code. +You will need to obtain a copy of the source code, +make modifications, generate patch file(s), and add them to the RPM SPEC +file for inclusion during the kernel build. + If you have a large number of patches or a more complex workflow, consider using a patch management tool in addition to Git such as `Quilt`_. -#. Clone the linux kernel source code into a new working directory. +#. Run make sources to pull the kernel source code specified in the RPM + SPEC file. In the example, it downloads the + :file:`linux-4.20.8.tar.xz` file. .. code-block:: bash - git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + make sources -#. Make any code changes to the Linux source files. +#. Extract the kernel source code archive and enter the extracted directory. + This will create a working copy of the Linux source you can modify. + In this example, it is extracted into a + :file:`linux-4.20.8` directory. + + .. code-block:: bash + + tar -xvf linux-4.20.8.tar.xz + + cd linux-4.20.8/ + + +#. Make any desired code changes to the Linux source code files. #. Track and commit your changes to the local git repo. .. code-block:: bash - git commit -m "My patch for driver A" + git add %{filename} + git commit -m "My patch for driver A" %{filename} #. Generate a patch file based on your git commits. @@ -248,7 +270,7 @@ consider using a patch management tool in addition to Git such as .. code-block:: bash - cp patches/*.patch ~/clearlinux/packages/linux/ + cp *.patch ~/clearlinux/packages/linux/ #. Navigate back to the RPM build directory. @@ -267,7 +289,9 @@ consider using a patch management tool in addition to Git such as #. Locate the section of the SPEC file that contains existing patch variable definitions and append your patch file name. Ensure the - patch number does not collide with an existing patch. + patch number does not collide with an existing patch. + In this example, the patch file is called + :file:`2001-my-patch-for-driver-A.patch` .. code-block:: bash @@ -288,6 +312,8 @@ consider using a patch management tool in addition to Git such as #. Locate the section of the SPEC file further down that contains patch application and append your patch file number used in the step above. + In this example, the patch file is called + :file:`2001-my-patch-for-driver-A.patch` .. code-block:: bash From f080e928feed3f3c24b174ae5ed1eac351e8e325 Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Thu, 14 Feb 2019 17:06:28 -0800 Subject: [PATCH 22/35] Add section on changing kernel parameters --- .../guides/maintenance/kernel-development.rst | 31 +++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index 1145dda8..265a4222 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -312,8 +312,7 @@ consider using a patch management tool in addition to Git such as #. Locate the section of the SPEC file further down that contains patch application and append your patch file number used in the step above. - In this example, the patch file is called - :file:`2001-my-patch-for-driver-A.patch` + In this example, patch2001 is added. .. code-block:: bash @@ -334,6 +333,33 @@ consider using a patch management tool in addition to Git such as +Modify kernel boot parameters +============================= +The kernel boot options are passed from the bootloader to the kernel with +command-line parameters. + +While temporarily changes can be made to kernel parameters on a running +system or on a during boot, you can also modify the default parameters that +are persistent and distributed with a customized kernel. + + +#. Open the kernel :file:`cmdline` file in an editor. + + .. code-block:: bash + + $EDITOR cmdline + +#. Make any desired change to the kernel parameters. + For example, you can remove the :command:`quiet` parameter to see more + verbose output of kernel log messages during the boot process. + +#. Commit and save the changes to the :file:`cmdline` file. + +See the +`Kernel parameters documentation`_ for a list of available parameters. + + + Build and install the kernel **************************** After changes have been made to the kernel SPEC file and config file, @@ -404,5 +430,6 @@ Related topics .. _`Quilt`: http://savannah.nongnu.org/projects/quilt .. _`clearlinux-pkgs GitHub`: https://github.com/clearlinux-pkgs?&q=linux .. _`kernel.org`: https://www.kernel.org/ +.. _`Kernel parameters documentation`: https://www.kernel.org/doc/Documentation/admin-guide/kernel-parameters.txt .. _`autospec`: https://clearlinux.org/documentation/clear-linux/concepts/autospec-about .. _`git-format-patch Documentation`: https://git-scm.com/docs/git-format-patch From 126c33eb5e549bb6d21d5d63a3150d435fe8bf82 Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Tue, 19 Feb 2019 11:01:39 -0800 Subject: [PATCH 23/35] Revamp kernel config section Revamp kernel configuration section to not force the workflow of the CL team. --- .../guides/maintenance/kernel-development.rst | 162 ++++++++++-------- 1 file changed, 86 insertions(+), 76 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index 265a4222..369488c6 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -19,8 +19,8 @@ used for development instead. The latest source RPM files are available at: `https://download.clearlinux.org/current/source/SRPMS/`_ -Request the change be included with the |CL| kernel -*************************************************** +Request changes be included with the |CL| kernel +************************************************ If the kernel modification you need is already open source and likely to be useful to others, consider submitting a request to include it in the @@ -47,7 +47,6 @@ To create a custom kernel, start with the |CL| development environment. Then make changes to the kernel, build it, and install it. - Install the |CL| development tooling framework ============================================== @@ -129,84 +128,106 @@ by autospec are not available and changes must be made manually. %define ktarget native .. note:: - Consider changing the Name from *linux* in the RPM spec file to easily - identify a modified kernel. + - Consider changing the Name from *linux* in the RPM spec file to easily + identify a modified kernel. - Consider changing the ktarget from *native* in the RPM spec file to easily - identify a modified kernel. + - Consider changing the ktarget from *native* in the RPM spec file to easily + identify a modified kernel. #. Commit and save the changes to the file. +Pull a copy of the kernel source code +===================================== + +You will need to obtain a local copy of the source code to make modifications +against. + + +#. Run make sources to pull the kernel source code specified in the RPM + SPEC file. In the example, it downloads the + :file:`linux-4.20.8.tar.xz` file. + + .. code-block:: bash + + make sources + + +#. Extract the kernel source code archive. This will create a working copy of + the Linux source which you can modify. + + .. code-block:: bash + + tar -xvf linux-4.20.8.tar.xz + + +#. Navigate to the extracted directory. In this example, it has been + extracted into a :file:`linux-4.20.8` directory. + + .. code-block:: bash + + cd linux-4.20.8/ + + Modify kernel configuration =========================== -Existing kernel features and in-tree kernel modules can be enabled or -disabled in the kernel configuration file, :file:`.config` , at compile time. +The kernel source has many different configuration options available to pick +support different hardware and software features. -To manage unique changes that have been made to the kernel config file, -|CL| uses a kernel config fragment file named :file:`config-fragment`. -Managing kernel configuration changes with a configuration fragment file -instead of directly editing the :file:`.config` file helps identify the -unique configuration changes that have been made and makes applying any -future default configuration values easier. - -The :file:`config-fragment` is the **only** file that is modified and is -eventually merged with the main :file:`.config`. +These configuration values must be provided in the :file:`.config` file at +compile time. +#. Make sure you have followed the steps to + `Pull a copy of the kernel source code`_ and are in the kernel source + working directory. -#. Open the kernel :file:`config-fragment` file in an editor. + +#. If you have an existing :file:`.config` file from an old kernel, copy it + into the working directory as :file:`.config` for comparison. + Otherwise, generate a base kernel configuration with default values + for the linux source version and put them in a :file:`.config` file + within the working directory. .. code-block:: bash - $EDITOR config-fragment + make defconfig -#. Find the configuration values you are looking for. - If a particular setting does not already exist, it can be added manually. +#. Make any desired changes to the :file:`.config` using a kernel + configuration tool. Below are some popular options: - For example, the snippet below shows BTRFS support configuration indicating - it is enabled in-tree. + - :command:`$EDITOR .config` - the .config file can be directly edited for + simple changes with names that are already known. + + - :command:`make config` - a text-based tool that asks questions + one-by-one to decide configuration options. + + - :command:`make menuconfig` - a terminal user interface that provides + menus to decide configuration options. + + - :command:`make xconfig` - a graphical user interface that provides + tree views to decide configuration options. + + + More configuration tools can be found by looking at the make help: + :command:`make help | grep config` + + +#. Commit and save the changes to the :file:`.config` file. + + +#. Copy the :file:`.config` file from the kernel source directory into + the kernel package directory as :file:`config` for inclusion in the build. .. code-block:: bash - CONFIG_BTRFS_FS=y - CONFIG_BTRFS_FS_POSIX_ACL=y + cp .config ../config -#. Modify the configuration values as desired. - - For example, the snippet below shows BTRFS support configuration changed - change to be disabled and commented out. - - .. code-block:: bash - - # CONFIG_BTRFS_FS is not set - # CONFIG_BTRFS_FS_POSIX_ACL is not set - -#. Commit and save the changes to the :file:`config-fragment` file. - - -#. Run the :command:`make config` command to apply the changes made in the - :file:`config-fragment` file and regenerate the :file:`config` file. - - .. code-block:: bash - - make config - -.. note:: - - The |CL| packaging tools make use of :command:`mock` environments for - building software. - - If you want to make use of GUI tools to edit the kernel confguration, such as - :command:`menuconfig`, instead of manually editing the :file:`config` - file, you can from the :command:`mock` environment under - :file:`/var/lib/mock/clear-linux/root/builddir/build/BUILD/kernel-*` - Modify kernel source code ========================= @@ -223,25 +244,9 @@ consider using a patch management tool in addition to Git such as `Quilt`_. -#. Run make sources to pull the kernel source code specified in the RPM - SPEC file. In the example, it downloads the - :file:`linux-4.20.8.tar.xz` file. - - .. code-block:: bash - - make sources - - -#. Extract the kernel source code archive and enter the extracted directory. - This will create a working copy of the Linux source you can modify. - In this example, it is extracted into a - :file:`linux-4.20.8` directory. - - .. code-block:: bash - - tar -xvf linux-4.20.8.tar.xz - - cd linux-4.20.8/ +#. Make sure you have followed the steps to + `Pull a copy of the kernel source code`_ and are in the kernel source + working directory. #. Make any desired code changes to the Linux source code files. @@ -349,10 +354,12 @@ are persistent and distributed with a customized kernel. $EDITOR cmdline + #. Make any desired change to the kernel parameters. For example, you can remove the :command:`quiet` parameter to see more verbose output of kernel log messages during the boot process. + #. Commit and save the changes to the :file:`cmdline` file. See the @@ -393,12 +400,14 @@ machine for testing. This approach works well for individual development or testing. For a more scalable and customizable approach, consider using the `mixer tool`_ to provide a custom kernel with updates. -1. Install the kernel onto the local system by extracting the RPM with the :command:`rpm2cpio` command. +1. Install the kernel onto the local system by extracting the RPM with the + :command:`rpm2cpio` command. .. code-block:: bash sudo rpm2cpio linux%{name}-%{version}-%{release}.x86_64.rpm | (cd /; sudo cpio -i -d -u -v); + #. Update the |CL| boot manager using :command:`clr-boot-manager` and reboot. .. code-block:: bash @@ -408,6 +417,7 @@ testing. For a more scalable and customizable approach, consider using the sudo reboot + #. After a reboot, verify the customized kernel is running. .. code-block:: bash From 00412e034694212c32b25592c0014401f9b61227 Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Tue, 19 Feb 2019 11:26:59 -0800 Subject: [PATCH 24/35] Use <> for replacements in codeblocks Per contribution guidelines --- .../guides/maintenance/kernel-development.rst | 31 +++++++++++-------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index 369488c6..eb7d3263 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -82,7 +82,7 @@ Clone the existing kernel package repository from |CL| as a starting point. The latest version of the |CL| kernel package is pulled as a starting point. An older version can pulled by switching to different git tag with - :command:`git checkout tag/${TAG_NAME}` tag. + :command:`git checkout tag/` tag. @@ -174,12 +174,16 @@ against. Modify kernel configuration =========================== -The kernel source has many different configuration options available to pick -support different hardware and software features. +The kernel source has many configuration options available to pick +support for different hardware and software features. These configuration values must be provided in the :file:`.config` file at compile time. +You will need to obtain a copy of the source code, make modifications to the +:file:`.config` file, and include the :file:`.config` file in the kernel +package. + #. Make sure you have followed the steps to `Pull a copy of the kernel source code`_ and are in the kernel source @@ -188,14 +192,15 @@ compile time. #. If you have an existing :file:`.config` file from an old kernel, copy it into the working directory as :file:`.config` for comparison. - Otherwise, generate a base kernel configuration with default values - for the linux source version and put them in a :file:`.config` file - within the working directory. + Otherwise, generate a base kernel configuration. .. code-block:: bash make defconfig + This will create a :file:`.config` file within the working directory + containing default values for the linux version. + #. Make any desired changes to the :file:`.config` using a kernel configuration tool. Below are some popular options: @@ -213,8 +218,8 @@ compile time. tree views to decide configuration options. - More configuration tools can be found by looking at the make help: - :command:`make help | grep config` + More configuration tools can be found by looking at the make help: + :command:`make help | grep config` #. Commit and save the changes to the :file:`.config` file. @@ -256,8 +261,8 @@ consider using a patch management tool in addition to Git such as .. code-block:: bash - git add %{filename} - git commit -m "My patch for driver A" %{filename} + git add + git commit -m "My patch for driver A" #. Generate a patch file based on your git commits. @@ -387,7 +392,7 @@ the kernel is ready to be compiled and packaged into an RPM. ls rpms/ - The kernel RPM will be named :file:`linux%{name}-%{version}-%{release}.x86_64.rpm` + The kernel RPM will be named :file:`linux--.x86_64.rpm` #. The kernel RPM file can be input to the `mixer tool`_ to create a custom @@ -405,7 +410,7 @@ testing. For a more scalable and customizable approach, consider using the .. code-block:: bash - sudo rpm2cpio linux%{name}-%{version}-%{release}.x86_64.rpm | (cd /; sudo cpio -i -d -u -v); + sudo rpm2cpio linux--.x86_64.rpm | (cd /; sudo cpio -i -d -u -v); #. Update the |CL| boot manager using :command:`clr-boot-manager` and reboot. @@ -413,7 +418,7 @@ testing. For a more scalable and customizable approach, consider using the .. code-block:: bash sudo clr-boot-manager list-kernels - sudo clr-boot-manager set-kernel org.clearlinux.${Target}.%{version}-%{release} + sudo clr-boot-manager set-kernel org.clearlinux..- sudo reboot From ab9cf0572af9be121527cbf6ecd22a555b4ed656 Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Tue, 19 Feb 2019 11:42:46 -0800 Subject: [PATCH 25/35] Restructure doc headers This PR closes #249 --- .../guides/maintenance/kernel-development.rst | 28 ++++++++++++------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index eb7d3263..3457c4c1 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -32,8 +32,8 @@ modified kernel. Make enhancement requests to the |CL| distribution `on GitHub`_ . -Customize the Linux kernel source -********************************* +Set up kernel development environment +************************************* In some cases, it may be necessary to modify the kernel to suit your specific needs or test new kernel code as a developer. @@ -56,8 +56,8 @@ Install the |CL| development tooling framework -Clone the Linux kernel package -============================== +Clone the kernel package +======================== Clone the existing kernel package repository from |CL| as a starting point. #. Clone the Linux kernel package from |CL|. @@ -138,8 +138,8 @@ by autospec are not available and changes must be made manually. #. Commit and save the changes to the file. -Pull a copy of the kernel source code -===================================== +Pull a copy of the Linux kernel source code +=========================================== You will need to obtain a local copy of the source code to make modifications against. @@ -170,6 +170,15 @@ against. cd linux-4.20.8/ +Customize the Linux kernel source +********************************* + +After the kernel sources have been obtained, customizations to the kernel +configuration or source code can be made for inclusion with the kernel +build. + +These customizations are option optional. + Modify kernel configuration =========================== @@ -180,9 +189,8 @@ support for different hardware and software features. These configuration values must be provided in the :file:`.config` file at compile time. -You will need to obtain a copy of the source code, make modifications to the -:file:`.config` file, and include the :file:`.config` file in the kernel -package. +You will need to make modifications to the :file:`.config` file, and include +it in the kernel package. #. Make sure you have followed the steps to @@ -374,7 +382,7 @@ See the Build and install the kernel **************************** -After changes have been made to the kernel SPEC file and config file, +After changes have been made to the kernel source and RPM SPEC file, the kernel is ready to be compiled and packaged into an RPM. #. Start the compilation process by issuing the :command:`make build` command. From f65a253767eb8459e2ede05436ce89e50fd6e66f Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Tue, 19 Feb 2019 16:05:39 -0800 Subject: [PATCH 26/35] Fix broken internal reference --- .../clear-linux/guides/maintenance/kernel-development.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index 3457c4c1..ad706c35 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -194,8 +194,8 @@ it in the kernel package. #. Make sure you have followed the steps to - `Pull a copy of the kernel source code`_ and are in the kernel source - working directory. + `Pull a copy of the Linux kernel source code`_ and are in the kernel + source working directory. #. If you have an existing :file:`.config` file from an old kernel, copy it @@ -258,8 +258,8 @@ consider using a patch management tool in addition to Git such as #. Make sure you have followed the steps to - `Pull a copy of the kernel source code`_ and are in the kernel source - working directory. + `Pull a copy of the Linux kernel source code`_ and are in the kernel + source working directory. #. Make any desired code changes to the Linux source code files. From 583522681602809623e7e4398d1749e71aa8d002 Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Tue, 19 Feb 2019 20:20:07 -0800 Subject: [PATCH 27/35] Some changes requested by @mvincerx --- .../guides/maintenance/kernel-development.rst | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index ad706c35..9b122375 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -1,7 +1,7 @@ .. _kernel-development: -Kernel development on Clear Linux -################################# +Kernel development on |CL-ATTR| +############################### This document shows how to obtain and compile a Linux kernel source using the |CL-ATTR| development tooling. @@ -60,7 +60,9 @@ Clone the kernel package ======================== Clone the existing kernel package repository from |CL| as a starting point. -#. Clone the Linux kernel package from |CL|. +#. Clone the Linux kernel package from |CL|. + Using the :command:`make clone_` command within the :file:`clearlinux/` + directory clones the package from the `clearlinux-pkgs GitHub`_. .. code-block:: bash @@ -74,11 +76,13 @@ Clone the existing kernel package repository from |CL| as a starting point. cd ~/clearlinux/packages/linux + +The "linux" package is the kernel that comes with |CL| in the kernel-native +bundle.You can alternatively use a different kernel variant as the base for +modification. For a list of kernel package names which you can clone instead, +see the `clearlinux-pkgs GitHub`_. + .. note:: - The "linux" package is the kernel that comes with |CL| in the kernel-native bundle. - You can alternatively use a different kernel variant as the base for modification. - For a list of kernel package names which you can clone instead, - see the `clearlinux-pkgs GitHub`_. The latest version of the |CL| kernel package is pulled as a starting point. An older version can pulled by switching to different git tag with From 27dfab02f60f00b515b4ae5b4b98c2a3c4a33db3 Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Wed, 20 Feb 2019 10:27:42 -0800 Subject: [PATCH 28/35] Update GH link per @miguelinux --- source/clear-linux/guides/maintenance/kernel-development.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index 9b122375..b992839a 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -450,7 +450,7 @@ Related topics * :ref:`mixer` .. _`kernels available in Clear Linux`: https://clearlinux.org/documentation/clear-linux/reference/compatible-kernels -.. _`on GitHub`: https://github.com/clearlinux/distribution +.. _`on GitHub`: https://github.com/clearlinux/distribution/issues/new/choose .. _`https://download.clearlinux.org/current/source/SRPMS/`: https://download.clearlinux.org/current/source/SRPMS/ .. _`mixer tool`: https://clearlinux.org/features/mixer-tool .. _user-setup script: https://github.com/clearlinux/common/blob/master/user-setup.sh From f1d038810377a9f81fc2556205299af04562dbff Mon Sep 17 00:00:00 2001 From: "Brett T. Warden" <4c0e8e88@tm.wgz.org> Date: Wed, 20 Feb 2019 19:18:09 +0000 Subject: [PATCH 29/35] Fix typo pointed out by @bwarden Co-Authored-By: puneetse <22071208+puneetse@users.noreply.github.com> --- source/clear-linux/guides/maintenance/kernel-development.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index b992839a..a2bab4a0 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -181,7 +181,7 @@ After the kernel sources have been obtained, customizations to the kernel configuration or source code can be made for inclusion with the kernel build. -These customizations are option optional. +These customizations are optional. Modify kernel configuration From d0b8da5b62ca168ea97286b15fc702fae8497342 Mon Sep 17 00:00:00 2001 From: "Brett T. Warden" <4c0e8e88@tm.wgz.org> Date: Wed, 20 Feb 2019 19:18:37 +0000 Subject: [PATCH 30/35] Fix typo pointed out by @bwarden Co-Authored-By: puneetse <22071208+puneetse@users.noreply.github.com> --- source/clear-linux/guides/maintenance/kernel-development.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index a2bab4a0..bd76a13d 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -360,7 +360,7 @@ Modify kernel boot parameters The kernel boot options are passed from the bootloader to the kernel with command-line parameters. -While temporarily changes can be made to kernel parameters on a running +While temporary changes can be made to kernel parameters on a running system or on a during boot, you can also modify the default parameters that are persistent and distributed with a customized kernel. From 0bc659380faa6f0c6121bf58ee4706930d1ee6af Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Wed, 20 Feb 2019 11:22:19 -0800 Subject: [PATCH 31/35] Remove unnecessary sudo on rpm2cpio --- source/clear-linux/guides/maintenance/kernel-development.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index b992839a..d98d04c3 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -422,7 +422,7 @@ testing. For a more scalable and customizable approach, consider using the .. code-block:: bash - sudo rpm2cpio linux--.x86_64.rpm | (cd /; sudo cpio -i -d -u -v); + rpm2cpio linux--.x86_64.rpm | (cd /; sudo cpio -i -d -u -v); #. Update the |CL| boot manager using :command:`clr-boot-manager` and reboot. From 55ca8102097a1bbf82ff9c2905e6d2cf094dbe11 Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Wed, 20 Feb 2019 11:56:32 -0800 Subject: [PATCH 32/35] Add note about using ccache plugin for mock --- .../guides/maintenance/kernel-development.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index 18fcd9f4..58c82f5f 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -389,6 +389,11 @@ Build and install the kernel After changes have been made to the kernel source and RPM SPEC file, the kernel is ready to be compiled and packaged into an RPM. +The |CL| development tooling makes use of :command:`mock` environments to +isolate building of packages in a sanitized workspace. + + + #. Start the compilation process by issuing the :command:`make build` command. This process is typically resource intensive and will take a while. @@ -397,6 +402,12 @@ the kernel is ready to be compiled and packaged into an RPM. make build + .. note:: + The `ccache plugin for mock`_ can be enabled to help speed up any future + rebuilds of the kernel package by caching compiler outputs and reusing + them. + + #. The result will be multiple :file:`.rpm` files in the :file:`rpms` directory as output. @@ -410,6 +421,7 @@ the kernel is ready to be compiled and packaged into an RPM. #. The kernel RPM file can be input to the `mixer tool`_ to create a custom bundle and mix of |CL|. + Alternatively, the kernel RPM bundle can be installed manually on a local @@ -458,5 +470,6 @@ Related topics .. _`clearlinux-pkgs GitHub`: https://github.com/clearlinux-pkgs?&q=linux .. _`kernel.org`: https://www.kernel.org/ .. _`Kernel parameters documentation`: https://www.kernel.org/doc/Documentation/admin-guide/kernel-parameters.txt +.. _`ccache plugin for mock`: https://fedoraproject.org/wiki/Mock/Plugin/CCache?rd=Subprojects/Mock/Plugin/CCache .. _`autospec`: https://clearlinux.org/documentation/clear-linux/concepts/autospec-about .. _`git-format-patch Documentation`: https://git-scm.com/docs/git-format-patch From d9d07ce19c99db621f81e1808a9af989e0b032e5 Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Wed, 20 Feb 2019 13:10:19 -0800 Subject: [PATCH 33/35] Change to use the CL kernel config as a template --- .../clear-linux/guides/maintenance/kernel-development.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index 58c82f5f..f3e5d88e 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -204,14 +204,11 @@ it in the kernel package. #. If you have an existing :file:`.config` file from an old kernel, copy it into the working directory as :file:`.config` for comparison. - Otherwise, generate a base kernel configuration. + Otherwise, use the |CL| kernel configuration file as template .. code-block:: bash - make defconfig - - This will create a :file:`.config` file within the working directory - containing default values for the linux version. + cp ~/clearlinux/packages/linux/config .config #. Make any desired changes to the :file:`.config` using a kernel From f5409367a1707be86e1870e3a88e8075da254212 Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Wed, 20 Feb 2019 18:36:52 -0800 Subject: [PATCH 34/35] Add changes requested by @miguelinux --- .../guides/maintenance/kernel-development.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index f3e5d88e..35d9ee9f 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -263,6 +263,24 @@ consider using a patch management tool in addition to Git such as source working directory. +#. Initialize the kernel source directory as a new git repo and commit + all the files to begin tracking changes. + + .. code-block:: bash + + git init + git add -A + git commit -m "Initial commit of Linux kernel source" + + +#. Apply ptches provided by the |CL| kernel package to the kernel source + in the working directory. + + .. code-block:: bash + + git am ../*.patch + + #. Make any desired code changes to the Linux source code files. From 4dc6c0330e62281613eb1066fa36243c0b0db666 Mon Sep 17 00:00:00 2001 From: puneetse <22071208+puneetse@users.noreply.github.com> Date: Wed, 20 Feb 2019 18:40:47 -0800 Subject: [PATCH 35/35] Clarify a few sentences --- .../clear-linux/guides/maintenance/kernel-development.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-development.rst b/source/clear-linux/guides/maintenance/kernel-development.rst index 35d9ee9f..cdac8a7c 100644 --- a/source/clear-linux/guides/maintenance/kernel-development.rst +++ b/source/clear-linux/guides/maintenance/kernel-development.rst @@ -263,8 +263,8 @@ consider using a patch management tool in addition to Git such as source working directory. -#. Initialize the kernel source directory as a new git repo and commit - all the files to begin tracking changes. +#. Initialize the kernel source directory as a new git repo and create a + commit with all the existing source files to begin tracking changes. .. code-block:: bash @@ -273,7 +273,7 @@ consider using a patch management tool in addition to Git such as git commit -m "Initial commit of Linux kernel source" -#. Apply ptches provided by the |CL| kernel package to the kernel source +#. Apply patches provided by the |CL| kernel package to the kernel source in the working directory. .. code-block:: bash @@ -281,7 +281,7 @@ consider using a patch management tool in addition to Git such as git am ../*.patch -#. Make any desired code changes to the Linux source code files. +#. Make any of your desired code changes to the Linux source code files. #. Track and commit your changes to the local git repo.