# MiniKbuild

**Repository Path**: openlabhub/mini-kbuild

## Basic Information

- **Project Name**: MiniKbuild
- **Description**: 轻量级嵌入式 Linux 构建框架，基于 Linux 内核 kbuild + Kconfig 基础设施。提供 menuconfig 菜单配置、模块化包管理、增量构建和交叉编译支持。附完整中文技术文档（6篇教程）。
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-04
- **Last Updated**: 2026-07-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MiniKbuild

轻量级嵌入式 Linux 构建框架，基于 Linux 内核 kbuild 基础设施。

MiniKbuild 将 Linux 内核的 kbuild 构建系统提取为一个独立的、可用于嵌入式工具链和应用程序构建的通用框架。它提供了基于 Kconfig 的图形化配置界面和模块化的包构建机制，适合需要灵活定制构建内容的嵌入式项目。

## 特性

- **Kconfig 配置系统** — 与 Linux 内核相同的菜单驱动配置界面（`menuconfig`/`nconfig`/`xconfig`/`gconfig`）
- **模块化包管理** — 每个包独立定义，通过 Kconfig 启用/禁用
- **增量构建** — 基于 kbuild 的依赖追踪，仅重建变更的文件
- **交叉编译支持** — 通过 `CROSS_COMPILE` 前缀轻松切换工具链
- **独立输出目录** — 通过 `O=` 参数将构建产物与源码分离
- **公共头文件库** — 提供链表（`list.h`）和日志（`log.h`）等常用工具

## 系统要求

- GCC 编译器（支持 C99）
- GNU Make
- ncurses 开发库（用于 `make menuconfig`）
  - Debian/Ubuntu: `sudo apt install libncurses-dev`
  - Fedora/RHEL: `sudo dnf install ncurses-devel`

## 快速开始

```bash
# 1. 生成默认配置
make defconfig

# 2. 图形化配置（可选）
make menuconfig

# 3. 构建所有启用的包
make

# 4. 查看构建产物
ls output/binutils/
```

## 目录结构

```
MiniKbuild/
├── Makefile              # 顶层构建文件
├── Kconfig               # 顶层配置入口
├── COPYING               # GPL v2 许可证
├── README.md             # 本文件
├── configs/
│   └── defconfig         # 默认配置
├── include/
│   ├── list.h            # 双向链表实现
│   └── log.h             # 日志宏库
├── package/
│   ├── Kconfig           # 包配置定义
│   ├── Makefile          # 包构建入口
│   ├── demo/             # 示例包
│   │   ├── Makefile
│   │   └── demo-0.1.c
│   └── objdump/          # objdump 工具包
│       ├── Makefile
│       └── objdump-0.1.c
├── scripts/
│   ├── Kbuild.include    # kbuild 通用定义
│   ├── Makefile.build    # 构建规则
│   ├── Makefile.clean    # 清理规则
│   ├── Makefile.host     # 宿主程序构建规则
│   ├── Makefile.lib      # 库构建规则
│   ├── basic/            # 基础构建工具（fixdep）
│   └── kconfig/          # Kconfig 配置工具源码
└── output/               # 构建输出目录（自动生成）
    └── binutils/         # 编译产物
```

## 构建命令

### 基础构建

| 命令 | 说明 |
|------|------|
| `make` | 构建所有启用的包（等同于 `make all`） |
| `make V=1` | 详细构建，显示完整命令 |
| `make V=2` | 显示每个目标被重建的原因 |
| `make W=1` | 启用额外的 GCC 警告检查（1/2/3 级，可组合如 `W=12`） |
| `make O=dir` | 将构建产物输出到指定目录 |

### 配置管理

| 命令 | 说明 |
|------|------|
| `make menuconfig` | 基于 ncurses 的菜单式配置（推荐） |
| `make nconfig` | 基于 ncurses 的增强菜单 |
| `make defconfig` | 使用 `configs/defconfig` 生成默认配置 |
| `make savedefconfig` | 将当前配置保存为最小化的 defconfig |
| `make oldconfig` | 基于现有 `.config` 更新配置（仅提示新增选项） |
| `make allnoconfig` | 所有选项设为 n 的新配置 |
| `make allyesconfig` | 所有选项设为 y 的新配置 |
| `make randconfig` | 随机配置（用于测试） |

### 清理

| 命令 | 说明 |
|------|------|
| `make clean` | 删除构建产物，保留配置 |
| `make mrproper` | 删除所有生成文件（含配置） |
| `make distclean` | mrproper + 删除编辑器备份和补丁残留 |

### 代码导航

| 命令 | 说明 |
|------|------|
| `make tags` | 生成 ctags 索引 |
| `make TAGS` | 生成 etags 索引 |
| `make cscope` | 生成 cscope 索引 |
| `make gtags` | 生成 GNU GLOBAL 索引 |

## 配置选项

通过 `make menuconfig` 或直接编辑 `.config` 文件进行配置：

| 选项 | 类型 | 说明 |
|------|------|------|
| `CONFIG_PACKAGE_DEMO` | bool | 示例包 — 编译 demo 程序 |
| `CONFIG_PACKAGE_OBJDUMP` | bool | objdump 工具 — 编译 objdump 程序 |
| `CONFIG_ENABLE_LOGGING` | bool | 启用日志输出 — 启用后 `print_dbg/info/warn/err` 宏生效 |

## 头文件 API

### log.h — 日志宏

需先在 menuconfig 中启用 `CONFIG_ENABLE_LOGGING`。

```c
#include <log.h>

void example(void)
{
    print_dbg("调试信息：%d\n", 42);
    print_info("一般信息：%s\n", "hello");
    print_warn("警告：%s 已过期\n", "证书");
    print_err("错误：无法打开 %s\n", "/dev/null");
}
```

日志输出格式：`[级别] 函数名: 消息`，输出到 stderr。

未启用 `CONFIG_ENABLE_LOGGING` 时，所有日志调用在编译时被完全移除（零开销）。

### list.h — 双向链表

源自 Linux 内核的侵入式双向链表实现。

```c
#include <list.h>

/* 定义包含链表节点的结构体 */
struct task {
    int id;
    char name[32];
    struct list_head node;    /* 链表节点 */
};

/* 初始化链表头 */
LIST_HEAD(task_list);

/* 添加元素 */
struct task t = { .id = 1 };
list_add_tail(&t.node, &task_list);

/* 遍历链表 */
struct task *pos;
list_for_each_entry(pos, &task_list, node) {
    printf("任务 %d: %s\n", pos->id, pos->name);
}

/* 安全遍历（可在遍历中删除元素） */
struct task *n;
list_for_each_entry_safe(pos, n, &task_list, node) {
    if (pos->id == 1) {
        list_del(&pos->node);
    }
}
```

可用操作：`list_add`、`list_add_tail`、`list_del`、`list_replace`、`list_empty`、`list_entry`、`list_for_each`、`list_for_each_entry`、`list_for_each_entry_safe`。

## 交叉编译

```bash
# 使用交叉编译工具链
make CROSS_COMPILE=arm-linux-gnueabihf-

# 指定输出目录
make O=/tmp/build CROSS_COMPILE=aarch64-linux-gnu-
```

## 添加新包

### 1. 创建包目录

```
package/mypackage/
├── Makefile
└── mypackage-0.1.c
```

### 2. 编写包 Makefile

```makefile
#################################################
#
# mypackage 自定义包
#
#################################################
PKG_NAME    = mypackage
PKG_VERSION = 0.1
PKG_SOURCE  = $(PKG_NAME)-$(PKG_VERSION).c
PKG_CMD     = $(PKG_NAME)_$(PKG_VERSION)
SUB_TARGET  += $(PACKAGE_DIR)/$(PKG_NAME)

PKG_CC      = $(CC)
PKG_CFLAGS  = $(CFLAGS)

quiet_cmd_$(PKG_CMD) = CC      $(PKG_NAME)
      cmd_$(PKG_CMD) = $(PKG_CC) $(PKG_CFLAGS) \
                        $(PACKAGE_DIR)/$(PKG_NAME)/$(PKG_SOURCE) \
                        -o $(STAGING_DIR)/binutils/$(PKG_NAME)

$(PACKAGE_DIR)/$(PKG_NAME): FORCE
	$(call if_changed,$(PKG_CMD))
```

### 3. 注册到 Kconfig

在 `package/Kconfig` 中添加：

```kconfig
config PACKAGE_MYPACKAGE
	bool "mypackage 自定义工具"
	help
	  自定义工具的简要说明。
```

### 4. 注册到包 Makefile

在 `package/Makefile` 中添加：

```makefile
PACKAGE-$(CONFIG_PACKAGE_MYPACKAGE) += mypackage/
```

完成后执行 `make menuconfig` 即可在菜单中看到新包，启用后 `make` 会自动编译。

## 版本号

当前版本定义在顶层 `Makefile` 中：

```makefile
VERSION = 0
PATCHLEVEL = 1
SUBLEVEL = 0
EXTRAVERSION =
```

通过 `make kernelversion` 或 `make kernelrelease` 查看版本信息。

## 许可证

本项目以 GNU General Public License v2.0 发布，详见 `COPYING` 文件。

## 致谢

本项目源自 [BiscuitOS](https://github.com/BuddyZhang1/BiscuitOS) 项目（作者：BuddyZhang1），在其构建系统基础上独立化改造而成。构建基础设施（kbuild/Kconfig）源自 Linux 内核源码树。详细声明见 [`NOTICE`](NOTICE) 文件。

## 赞助

如果本项目对您有帮助，欢迎扫码赞赏支持：

![赞赏码](assets/sponsor-qrcode.png)