[PATCH] Documentation: Add a source tree map overview

[PATCH] Documentation: Add a source tree map overview

[William Raezer]

[-- Attachment #1.1: Type: text/plain, Size: 1201 bytes --]

Hello,

My name is William Raezer, and this is my first contribution to the Linux
kernel. I'm submitting a simple but hopefully helpful addition: a
high-level map of the Linux kernel source tree as a new document in
`Documentation/source-map.rst`.

As someone beginning to explore the internals of the Linux kernel, I
noticed that while there is some documentation available that describes the
subsystems in principle, there's no centralized overview of the source tree
structure itself. This patch adds a basic source map that describes the
role of each top-level directory in the kernel source.

The goal is to assist both myself and others in navigating the codebase,
especially new contributors who may be overwhelmed by the kernel's size and
complexity. As a follow-up, I plan to add subsystem-level maps for key
directories such as `kernel/`, `mm/`, and `fs/`.

I hope this addition is seen as a positive and useful step, and I’m open to
feedback or suggestions to improve it.

Best regards,
William Raezer
wraezer@gmail.com

Signed-off-by: William Raezer <wraezer@gmail.com>

-- 
"If you don't have something nice to say, at least be creative."
--Madilyn Bailey

[-- Attachment #1.2: Type: text/html, Size: 1543 bytes --]

[-- Attachment #2: 0001-Documentation-Add-a-source-tree-map-overview.patch --]
[-- Type: text/x-patch, Size: 2751 bytes --]

From: William Raezer <wraezer@gmail.com>
Subject: [PATCH] Documentation: Add a source tree map overview

This patch introduces a high-level map of the Linux kernel source tree,
describing the purpose of each top-level directory. The goal is to help
new and experienced contributors alike understand the structure of the
kernel source code.

This documentation aims to improve the discoverability and accessibility
of various kernel subsystems and will be extended with subsystem-level
maps in future contributions.

Signed-off-by: William Raezer <wraezer@gmail.com>

diff --git a/Documentation/source-map.rst b/Documentation/source-map.rst
new file mode 100644
index 000000000000..111111111111
--- /dev/null
+++ b/Documentation/source-map.rst
@@
+.. SPDX-License-Identifier: GPL-2.0
+
+========================
+Linux Kernel Source Map
+========================
+
+This document provides an overview of the Linux kernel source tree, describing the
+purpose of each top-level directory. It serves as a reference for developers
+looking to understand the structure of the kernel source code.
+
+Top-Level Directories
+=====================
+
+- **arch/**: Architecture-specific code for supported CPU platforms (e.g., x86, arm64).
+- **block/**: Generic block layer code for managing block devices.
+- **certs/**: Certificate management used for module signing and kernel verification.
+- **crypto/**: Cryptographic algorithms and the crypto API.
+- **Documentation/**: Kernel documentation, mostly in reStructuredText format.
+- **drivers/**: Device drivers organized by class.
+- **fs/**: Filesystem code and the Virtual Filesystem Switch (VFS).
+- **include/**: Header files shared across kernel components.
+- **init/**: Code for kernel boot and initialization.
+- **io_uring/**: High-performance asynchronous I/O support.
+- **ipc/**: Inter-process communication mechanisms.
+- **kernel/**: Core kernel functionality including scheduling, signals, and system calls.
+- **lib/**: Common utility functions.
+- **LICENSES/**: SPDX license metadata for compliance.
+- **mm/**: Memory management subsystem.
+- **net/**: Networking protocols and infrastructure.
+- **rust/**: Infrastructure for Rust-based kernel components.
+- **samples/**: Sample modules and test code.
+- **scripts/**: Build and configuration scripts.
+- **security/**: Security modules like SELinux and AppArmor.
+- **sound/**: Audio subsystem and drivers.
+- **tools/**: User-space tools related to the kernel.
+- **usr/**: Initramfs image construction code.
+- **virt/**: Virtualization infrastructure (e.g., KVM).
+
+See Also
+========
+
+- `MAINTAINERS <../MAINTAINERS>`_: Maintainer contact information.
+- `kernel.org Documentation <https://www.kernel.org/doc/html/latest/>`_

Re: [PATCH] Documentation: Add a source tree map overview

[Randy Dunlap]

Hi,

On 6/1/25 9:22 AM, William Raezer wrote:
> Hello,
> 

Please wrap email lines at around 72-75 characters each.

> My name is William Raezer, and this is my first contribution to the Linux kernel. I'm submitting a simple but hopefully helpful addition: a high-level map of the Linux kernel source tree as a new document in `Documentation/source-map.rst`.

This looks somewhat useful, although I was expecting more of a graphic presentation
of the tree structure. But that would cause trouble with the role of each subdirectory.
(and one can always use `tree` for that)

> As someone beginning to explore the internals of the Linux kernel, I noticed that while there is some documentation available that describes the subsystems in principle, there's no centralized overview of the source tree structure itself. This patch adds a basic source map that describes the role of each top-level directory in the kernel source.
> 
> The goal is to assist both myself and others in navigating the codebase, especially new contributors who may be overwhelmed by the kernel's size and complexity. As a follow-up, I plan to add subsystem-level maps for key directories such as `kernel/`, `mm/`, and `fs/`.
> 
> I hope this addition is seen as a positive and useful step, and I’m open to feedback or suggestions to improve it.

Patches should generally be inline as email text, not as attachments.
This is up to the maintainer to decide about...
and gmail is not good as maintaining whitespace in emails.
(I don't see any whitespace problems in the current patch.)

I get a warning when building with this patch applied:

Documentation/source-map.rst: WARNING: document isn't included in any toctree [toc.not_included]

Also, when I look at source-map.html with a web browser, no parts of
the source-map are shown. (tested with multiple browsers)

Thanks.
-- 
~Randy

Re: [PATCH] Documentation: Add a source tree map overview

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 2231 bytes --]

On Sun, Jun 01, 2025 at 09:50:14AM -0700, Randy Dunlap wrote:
> Hi,
> 
> On 6/1/25 9:22 AM, William Raezer wrote:
> > Hello,
> > 
> 
> Please wrap email lines at around 72-75 characters each.
> 
> > My name is William Raezer, and this is my first contribution to the Linux kernel. I'm submitting a simple but hopefully helpful addition: a high-level map of the Linux kernel source tree as a new document in `Documentation/source-map.rst`.
> 
> This looks somewhat useful, although I was expecting more of a graphic presentation
> of the tree structure. But that would cause trouble with the role of each subdirectory.
> (and one can always use `tree` for that)

I was expecting tree output either.

> 
> > As someone beginning to explore the internals of the Linux kernel, I noticed that while there is some documentation available that describes the subsystems in principle, there's no centralized overview of the source tree structure itself. This patch adds a basic source map that describes the role of each top-level directory in the kernel source.
> > 
> > The goal is to assist both myself and others in navigating the codebase, especially new contributors who may be overwhelmed by the kernel's size and complexity. As a follow-up, I plan to add subsystem-level maps for key directories such as `kernel/`, `mm/`, and `fs/`.
> > 
> > I hope this addition is seen as a positive and useful step, and I’m open to feedback or suggestions to improve it.
> 
> Patches should generally be inline as email text, not as attachments.
> This is up to the maintainer to decide about...
> and gmail is not good as maintaining whitespace in emails.
> (I don't see any whitespace problems in the current patch.)

tl;dr: see Documentation/process/submitting-patches.rst.

> 
> I get a warning when building with this patch applied:
> 
> Documentation/source-map.rst: WARNING: document isn't included in any toctree [toc.not_included]

make htmldocs.

> 
> Also, when I look at source-map.html with a web browser, no parts of
> the source-map are shown. (tested with multiple browsers)

Do you mean toctree in the sidebar?

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH] Documentation: Add a source tree map overview

[Randy Dunlap]

On 6/1/25 6:26 PM, Bagas Sanjaya wrote:
> On Sun, Jun 01, 2025 at 09:50:14AM -0700, Randy Dunlap wrote:
>> Hi,
>>
>> On 6/1/25 9:22 AM, William Raezer wrote:
>>> Hello,
>>>
>>
>> Please wrap email lines at around 72-75 characters each.
>>
>>> My name is William Raezer, and this is my first contribution to the Linux kernel. I'm submitting a simple but hopefully helpful addition: a high-level map of the Linux kernel source tree as a new document in `Documentation/source-map.rst`.
>>
>> This looks somewhat useful, although I was expecting more of a graphic presentation
>> of the tree structure. But that would cause trouble with the role of each subdirectory.
>> (and one can always use `tree` for that)
> 
> I was expecting tree output either.
> 
>>
>>> As someone beginning to explore the internals of the Linux kernel, I noticed that while there is some documentation available that describes the subsystems in principle, there's no centralized overview of the source tree structure itself. This patch adds a basic source map that describes the role of each top-level directory in the kernel source.
>>>
>>> The goal is to assist both myself and others in navigating the codebase, especially new contributors who may be overwhelmed by the kernel's size and complexity. As a follow-up, I plan to add subsystem-level maps for key directories such as `kernel/`, `mm/`, and `fs/`.
>>>
>>> I hope this addition is seen as a positive and useful step, and I’m open to feedback or suggestions to improve it.
>>
>> Patches should generally be inline as email text, not as attachments.
>> This is up to the maintainer to decide about...
>> and gmail is not good as maintaining whitespace in emails.
>> (I don't see any whitespace problems in the current patch.)
> 
> tl;dr: see Documentation/process/submitting-patches.rst.
> 
>>
>> I get a warning when building with this patch applied:
>>
>> Documentation/source-map.rst: WARNING: document isn't included in any toctree [toc.not_included]
> 
> make htmldocs.
> 
>>
>> Also, when I look at source-map.html with a web browser, no parts of
>> the source-map are shown. (tested with multiple browsers)

No, I mean that what I see is mostly a blank/empty page.
Other that the sidebar, it only contains this line:

©The kernel development community. | Powered by Sphinx 8.2.3 & Alabaster 1.0.0 | Page source


-- 
~Randy

Re: [PATCH] Documentation: Add a source tree map overview

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 623 bytes --]

On Sun, Jun 01, 2025 at 07:49:08PM -0700, Randy Dunlap wrote:
> 
> 
> On 6/1/25 6:26 PM, Bagas Sanjaya wrote:
> > On Sun, Jun 01, 2025 at 09:50:14AM -0700, Randy Dunlap wrote:
> >>
> >> Also, when I look at source-map.html with a web browser, no parts of
> >> the source-map are shown. (tested with multiple browsers)
> 
> No, I mean that what I see is mostly a blank/empty page.
> Other that the sidebar, it only contains this line:
> 
> ©The kernel development community. | Powered by Sphinx 8.2.3 & Alabaster 1.0.0 | Page source

OK, thanks!

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]