File KERNEL_SOURCES_README.md of Package kernel-source

# SUSE Kernel Sources Guide

## Overview

This repository contains the SUSE kernel source package infrastructure, but the actual Linux kernel source code is distributed separately as a compressed archive for efficiency.

## Kernel Source Archive

### Current Version
- **File**: `linux-6.11.tar.xz` 
- **Size**: ~140 MB compressed
- **Source**: Linux kernel.org
- **URL**: https://www.kernel.org/pub/linux/kernel/v6.x/linux-6.11.tar.xz

### Automatic Download

The kernel sources are automatically downloaded during the RPM build process. The spec files reference:

```spec
Source0: https://www.kernel.org/pub/linux/kernel/v6.x/linux-%srcversion.tar.xz
```

Where `%srcversion` is currently set to `6.11`.

### Manual Download

If you need to manually download the kernel sources:

#### Method 1: Using wget/curl
```bash
# Download the exact version used by SUSE
wget https://www.kernel.org/pub/linux/kernel/v6.x/linux-6.11.tar.xz

# Or using curl
curl -O https://www.kernel.org/pub/linux/kernel/v6.x/linux-6.11.tar.xz
```

#### Method 2: Using OSC (for SUSE developers)
```bash
# OSC will automatically download sources when building
osc build

# Or explicitly download sources
osc service run download_files
```

#### Method 3: Using the Build System
```bash
# The RPM build process automatically fetches sources
rpmbuild -bp kernel-source.spec
```

### Extracting the Sources

Once downloaded, extract the kernel sources:

```bash
# Extract the archive
tar -xf linux-6.11.tar.xz

# This creates a directory: linux-6.11/
cd linux-6.11/
```

### Verifying the Download

The repository includes signature verification:

```bash
# Verify the download (if you have the signing key)
gpg --verify linux-6.11.tar.sign linux-6.11.tar.xz
```

The signing key is included as `linux.keyring` in this repository.

## What's in This Repository vs. The Archive

### This Repository Contains:
- **SUSE-specific patches** (`patches.*.tar.bz2`)
- **Kernel configurations** (`config.tar.bz2`)
- **Build infrastructure** (`.spec` files, scripts)
- **Documentation** (README files)
- **SUSE modifications and enhancements**

### The linux-6.11.tar.xz Archive Contains:
- **Upstream Linux kernel source code**
- **Core kernel files** (drivers, filesystems, etc.)
- **Architecture-specific code**
- **Kernel documentation**
- **Build system** (Makefiles, Kconfig)

## Build Process Overview

1. **Download**: `linux-6.11.tar.xz` is downloaded from kernel.org
2. **Extract**: Sources are extracted to `linux-6.11/`
3. **Patch**: SUSE patches from `patches.*.tar.bz2` are applied
4. **Configure**: Kernel configurations from `config.tar.bz2` are used
5. **Build**: The kernel is compiled with SUSE modifications

## Different Kernel Versions

To work with a different kernel version:

1. **Update the spec files**: Change `%define srcversion X.Y` 
2. **Update the URL**: Ensure the new version exists at kernel.org
3. **Test compatibility**: Verify SUSE patches apply cleanly
4. **Update configurations**: May need config updates for new features

### Example: Upgrading to 6.12
```spec
# In kernel-*.spec files, change:
%define srcversion 6.12
# URL becomes: linux-6.12.tar.xz
```

## Storage Considerations

### Why the Archive Isn't Always in Git

- **Size**: ~140 MB compressed, ~1.2 GB uncompressed
- **Redundancy**: Available from authoritative source (kernel.org)
- **Efficiency**: Download only when needed
- **Updates**: New versions don't pollute git history

### Including the Archive

If you want to include the kernel sources in your git repository:

```bash
# Download if not present
wget https://www.kernel.org/pub/linux/kernel/v6.x/linux-6.11.tar.xz

# Add to git (optional - increases repo size significantly)
git add linux-6.11.tar.xz
git commit -m "Add kernel source archive for offline builds"
```

**Note**: This increases the repository size significantly but makes it completely self-contained.

## Related Files

- **`linux-6.11.tar.sign`**: GPG signature for verification
- **`linux.keyring`**: GPG public keys for verification
- **`source-timestamp`**: Build timestamp information
- **`series.conf`**: Patch application order and configuration

## Troubleshooting

### Download Issues
```bash
# Check if the URL is accessible
curl -I https://www.kernel.org/pub/linux/kernel/v6.x/linux-6.11.tar.xz

# Use a mirror if kernel.org is slow
wget https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-6.11.tar.xz
```

### Extraction Issues
```bash
# Verify archive integrity
xz -t linux-6.11.tar.xz

# Check available space (needs ~1.2 GB)
df -h .
```

### Build Issues
```bash
# Ensure all dependencies are installed
zypper install kernel-devel rpm-build

# Check for missing sources
rpmbuild -bp kernel-source.spec 2>&1 | grep -i "not found"
```

## References

- [Linux Kernel Archives](https://www.kernel.org/)
- [SUSE Kernel Documentation](README.SUSE)
- [Kernel Module Rebuild Guide](KMOD_REBUILD_README.md)
- [SUSE Kernel Source Repository](https://github.com/SUSE/kernel-source)