179 lines
5.6 KiB
ReStructuredText
179 lines
5.6 KiB
ReStructuredText
.. Fedora Kernel and ARK Documentation documentation master file, created by
|
|
sphinx-quickstart on Thu May 7 14:44:56 2020.
|
|
You can adapt this file completely to your liking, but it should at least
|
|
contain the root `toctree` directive.
|
|
|
|
=================
|
|
Fedora/ARK Kernel
|
|
=================
|
|
|
|
This documentation covers setting up a development environment, the repository
|
|
layout, and the general contribution workflow.
|
|
|
|
.. _quick-start:
|
|
|
|
Quick Start
|
|
===========
|
|
|
|
Setup
|
|
-----
|
|
|
|
To start with you need to:
|
|
|
|
1. Make a `GitLab account`_ if you do not already have one.
|
|
2. `Fork the repository`_. Wait patiently for this to complete.
|
|
3. Configure pull mirroring on your fork (see below).
|
|
4. Set up `Koji`_ or `Mock`_ if desired.
|
|
|
|
Pull mirroring keeps your fork in sync and avoids the need to configure a
|
|
separate remote in Git. Once GitLab finishes forking the repository:
|
|
|
|
* Go to your fork from your `personal GitLab projects`_.
|
|
* In the sidebar, click 'Settings' and then 'Repository'.
|
|
* Next to 'Mirroring repositories', click 'Expand'.
|
|
* Enter the Git repository URL: https://gitlab.com/cki-project/kernel-ark.git
|
|
* Ensure the 'Mirror direction' is 'Pull'.
|
|
* Leave the 'Password' blank.
|
|
* Select 'Overwrite diverged branches' (ARK rebases every GA release)
|
|
* Leave the other checkboxes blank (or select them if desired).
|
|
* Click 'Mirror Repository'. The first update will take about 20 minutes.
|
|
|
|
Cloning the Repository
|
|
----------------------
|
|
|
|
Install the dependencies for generating source RPM packages:
|
|
|
|
.. code-block:: sh
|
|
|
|
sudo dnf install git make gcc flex bison bzip2 rpm-build python3-pyyaml
|
|
|
|
Then clone the repository. To use SSH, `register your SSH key`_ in GitLab first.
|
|
|
|
.. code-block:: sh
|
|
|
|
# Clone using SSH
|
|
git clone git@gitlab.com:${GITLAB_USER_NAME}/kernel-ark.git && cd kernel-ark
|
|
# Clone using HTTPS
|
|
git clone https://gitlab.com/${GITLAB_USER_NAME}/kernel-ark.git && cd kernel-ark
|
|
|
|
The ``os-build`` branch is checked out automatically after cloning. This
|
|
branch contains the configuration and build scripts, and it is regularly
|
|
updated to work with Linus's master branch.
|
|
|
|
The ``ark-latest`` branch contains a very recent 'known-good' version of the
|
|
os-build branch that can be used if the os-build branch does not compile due to
|
|
upstream bugs. However, the os-build branch must be used as a Merge Request
|
|
target for all Fedora/ARK specific changes.
|
|
|
|
Build Dependencies
|
|
------------------
|
|
|
|
kernel-ark has a long list of BuildRequires that are specified in the
|
|
kernel.spec file. Built-in rpm commands like 'yum builddep' will not
|
|
work on all OSes (`see BZ 2103214`_),
|
|
and 'yum deplist' which requires the configuration and enabling of a source
|
|
repository. As a result a 'dist-get-buildreqs' target has been added that will
|
|
provide a list of missing dependencies. This list can be consumed by other
|
|
commands to install missing packages:
|
|
|
|
.. code-block:: sh
|
|
|
|
# install missing build dependencies
|
|
sudo dnf -y install $(make dist-get-buildreqs | grep "Missing dependencies:" | cut -d":" -f2-)
|
|
|
|
Some packages may require the enabling of additional repositories such as the
|
|
system-sb-certs package which can be found in a Centos-Stream or RHEL CodeReady
|
|
Linux Builder (CRB) repository.
|
|
|
|
Local builds
|
|
------------
|
|
|
|
With the ``os-build`` or ``ark-latest`` branch checked out, get the kernel .config:
|
|
|
|
.. code-block:: sh
|
|
|
|
make dist-<flavor>-configs # or make dist-configs-arch
|
|
cp redhat/configs/kernel-<version>-<arch>.config .config
|
|
|
|
Where flavor can be ``rhel`` or ``fedora``
|
|
|
|
You can now execute any common upstream make targets (make, make -j, make cscope, etc.).
|
|
|
|
Building packages
|
|
-----------------
|
|
|
|
With the ``os-build`` or ``ark-latest`` branch checked out, build a source RPM package:
|
|
|
|
.. code-block:: sh
|
|
|
|
make dist-srpm
|
|
|
|
You can now build the binary RPM packages however you would like:
|
|
|
|
.. code-block:: sh
|
|
|
|
# Build packages locally in Mock
|
|
mock redhat/rpm/SRPMS/kernel-*.src.rpm
|
|
# Build packages in Fedora's Koji
|
|
koji build --scratch rawhide redhat/rpm/SRPMS/kernel-*.src.rpm
|
|
koji build --scratch eln redhat/rpm/SRPMS/kernel-*.src.rpm
|
|
|
|
or
|
|
|
|
.. code-block:: sh
|
|
|
|
# this target requires internal Red Hat network access and will always
|
|
# build against the latest RHEL major compose
|
|
make dist-brew
|
|
|
|
The dist-brew target can be used with the BUILD_FLAGS variable to specify specific architectures. For example, to only build the x86_64 and noarch architectures,
|
|
|
|
.. code-block:: sh
|
|
|
|
# this target requires internal Red Hat network access and will always
|
|
# build against the latest RHEL major compose
|
|
make dist-brew BUILD_FLAGS="--arch-override=x86_64,noarch"
|
|
|
|
Want to add a patch? Just apply it with ``git cherry-pick`` or ``git am``, and
|
|
re-run ``make dist-srpm``. To modify the kernel configuration, make changes in
|
|
``redhat/configs/`` (consult the repository layout for details on this).
|
|
|
|
|
|
Contributor Guide
|
|
=================
|
|
|
|
.. toctree::
|
|
:maxdepth: 2
|
|
|
|
repository-layout
|
|
submitting-contributions
|
|
faq
|
|
makefile-changes
|
|
kernel-naming
|
|
|
|
|
|
Maintainer Guide
|
|
================
|
|
|
|
.. toctree::
|
|
:maxdepth: 2
|
|
|
|
maintaining
|
|
|
|
|
|
.. _GitLab account: https://gitlab.com/users/sign_in#register-pane
|
|
.. _personal GitLab projects: https://gitlab.com/?name=kernel-ark&personal=true
|
|
.. _Fork the repository: https://gitlab.com/cki-project/kernel-ark/-/forks/new
|
|
.. _register your SSH key: https://gitlab.com/-/profile/keys
|
|
.. _Koji: https://docs.fedoraproject.org/en-US/package-maintainers/Using_the_Koji_Build_System/
|
|
.. _Mock: https://fedoraproject.org/wiki/Using_Mock_to_test_package_builds#How_do_I_set_up_Mock.3F
|
|
.. _see BZ 2103214: https://bugzilla.redhat.com/2103214
|
|
|
|
|
|
Indices and tables
|
|
==================
|
|
|
|
* :ref:`genindex`
|
|
* :ref:`modindex`
|
|
* :ref:`search`
|