Merge pull request #173 from hengyoush/improve-build-docs

docs: improve how-to-build docs
hengyoush · Dec 12, 2024 · 4c43c0a · 4c43c0a
2 parents 1739e8b + 4b33577
commit 4c43c0a
Show file tree

Hide file tree

Showing 4 changed files with 107 additions and 45 deletions.
diff --git a/COMPILATION.md b/COMPILATION.md
@@ -10,7 +10,7 @@ This document describes the local compilation method for kyanos. My environment
 
 ## Installation of Compilation Environment Dependencies
 ### Ubuntu
-If you are using Ubuntu 22.04 or later, you can initialize the compilation environment with a single command.
+If you are using Ubuntu 20.04 or later, you can initialize the compilation environment with a single command.
 ```
 /bin/bash -c "$(curl -fsSL https://github.com/hengyoush/kyanos/blob/main/init_env.sh)"
 ```
@@ -22,19 +22,35 @@ In addition to the toolchain versions listed above, the compilation environment
 - pkgconf
 - libelf-dev
 
-### If Your Kernel Does Not Enable BTF
-If BTF is not enabled, you may be able to compile successfully, but you may not be able to start kyanos successfully.
 
-Check if BTF is enabled:
-```
-grep CONFIG_DEBUG_INFO_BTF "/boot/config-$(uname -r)"
-```
-If the result is `CONFIG_DEBUG_INFO_BTF=y`, it means BTF is enabled. If not, please download from [mirrors.openanolis.cn](https://mirrors.openanolis.cn/coolbpf/btf/) or [btfhub-archive](https://github.com/aquasecurity/btfhub-archive/), and use the `--btf` option to specify the downloaded BTF file when starting kyanos.
+## Compilation Commands
 
-## Compilation Command
-Execute
+If you are just developing and testing locally, you can execute
 ```
 make build-bpf && make
 ```
 
-Afterwards, the kyanos executable will be generated in the root directory of the project.
+the kyanos executable file will be generated in the root directory of the project.
+
+> [!IMPORTANT]
+> Note that this binary file does not include the BTF files from [btfhub-archive](https://github.com/aquasecurity/btfhub-archive/). If you run this kyanos on a lower version kernel without BTF support, it may fail to start. You can build a kyanos artifact with embedded BTF files using the following commands:  
+>x86_64:
+>```bash [x86_64]
+>make build-bpf && make btfgen BUILD_ARCH=x86_64 ARCH_BPF_NAME=x86 && make
+>```
+>arm64:
+>```bash [arm64]
+>make build-bpf && make btfgen BUILD_ARCH=arm64 ARCH_BPF_NAME=arm64 && make
+>```
+>
+> Note that make btfgen may take more than 15 minutes.
+
+
+> [!TIP]
+>If your kernel does not have BTF enabled, you may not be able to start kyanos successfully.
+>
+>Check if BTF is enabled:
+>```
+>grep CONFIG_DEBUG_INFO_BTF "/boot/config-$(uname -r)"
+>```
+>If the result is `CONFIG_DEBUG_INFO_BTF=y`, it means BTF is enabled. If not, please download the BTF file corresponding to your kernel version from [mirrors.openanolis.cn](https://mirrors.openanolis.cn/coolbpf/btf/) or [btfhub-archive](https://github.com/aquasecurity/btfhub-archive/), and use the `--btf` option to specify the downloaded BTF file when starting kyanos.
diff --git a/COMPILATION_CN.md b/COMPILATION_CN.md
@@ -10,7 +10,7 @@
 
 ## 编译环境依赖安装
 ### Ubuntu
-如果你使用的是ubuntu 22.04以及更新版本，可以使用一条命令即可完成编译环境的初始化。
+如果你使用的是ubuntu 20.04以及更新版本，可以使用一条命令即可完成编译环境的初始化。
 ```
 /bin/bash -c "$(curl -fsSL https://github.com/hengyoush/kyanos/blob/main/init_env.sh)"
 ```
@@ -22,20 +22,36 @@
 - pkgconf
 - libelf-dev
 
-### 如果你的内核没开启BTF
-如果没有开启BTF，那么虽然可能成功编译，但你可能无法成功启动 kyanos. 
-
-检查是否开启BTF：
-```
-grep CONFIG_DEBUG_INFO_BTF "/boot/config-$(uname -r)"
-```
-如果结果是`CONFIG_DEBUG_INFO_BTF=y`说明开启了，如果没开启请到  [mirrors.openanolis.cn](https://mirrors.openanolis.cn/coolbpf/btf/) or [btfhub-archive](https://github.com/aquasecurity/btfhub-archive/)上下载，然后启动 kyanos 时使用 `--btf` 选项指定下载的 btf 文件。
-
-
 ## 编译命令
-执行
+
+如果只是本地开发测试，可以执行
 ```
 make build-bpf && make
 ```
 
 之后在项目根目录下会生成 kyanos 可执行文件。
+
+> [!IMPORTANT]
+> 但是需要注意的是该二进制文件中没有包含 [btfhub-archive](https://github.com/aquasecurity/btfhub-archive/) 中的 btf 文件，如果直接拿这个 kyanos 去没有开启 BTF 支持的低版本内核上执行可能会启动失败，通过下面的命令可以构建出一个内嵌 btf 文件的 kyanos 产物：  
+> x86_64:  
+>```bash [x86_64]
+>make build-bpf && make btfgen BUILD_ARCH=x86_64 ARCH_BPF_NAME=x86 && make
+>```  
+>arm64: 
+>```bash [arm64]
+>make build-bpf && make btfgen BUILD_ARCH=arm64 ARCH_BPF_NAME=arm64 && make
+>```
+>
+> 需要注意 `make btfgen` 耗时可能超过 15min。
+
+
+> [!TIP]
+>如果你的内核没有开启BTF，你可能无法成功启动 kyanos. 
+>
+>检查是否开启BTF：
+>```
+>grep CONFIG_DEBUG_INFO_BTF "/boot/config-$(uname -r)"
+>```
+>如果结果是`CONFIG_DEBUG_INFO_BTF=y`说明开启了，如果没开启请到  [mirrors.openanolis.cn](https://mirrors.openanolis.cn/coolbpf/btf/) or [btfhub-archive](https://github.com/aquasecurity/btfhub-archive/)上下载对应你的内核版本的 btf 文件，然后启动 kyanos 时使用 `--btf` 选项指定下载的 btf 文件。
+
+
diff --git a/docs/cn/how-to-build.md b/docs/cn/how-to-build.md
@@ -15,7 +15,7 @@ prev: false
 
 ## 编译环境依赖安装
 ### Ubuntu
-如果你使用的是ubuntu 22.04以及更新版本，可以使用一条命令即可完成编译环境的初始化。
+如果你使用的是 ubuntu 20.04 以及更新版本，可以使用一条命令即可完成编译环境的初始化。
 ```
 /bin/bash -c "$(curl -fsSL https://github.com/hengyoush/kyanos/blob/main/init_env.sh)"
 ```
@@ -27,20 +27,35 @@ prev: false
 - pkgconf
 - libelf-dev
 
-### 如果你的内核没开启BTF
-如果没有开启BTF，那么虽然可能成功编译，但你可能无法成功启动 kyanos. 
-
-检查是否开启BTF：
-```
-grep CONFIG_DEBUG_INFO_BTF "/boot/config-$(uname -r)"
-```
-如果结果是`CONFIG_DEBUG_INFO_BTF=y`说明开启了，如果没开启请到  [mirrors.openanolis.cn](https://mirrors.openanolis.cn/coolbpf/btf/) or [btfhub-archive](https://github.com/aquasecurity/btfhub-archive/)上下载，然后启动 kyanos 时使用 `--btf` 选项指定下载的 btf 文件。
-
-
 ## 编译命令
-执行
+
+如果只是本地开发测试，可以执行
 ```
 make build-bpf && make
 ```
 
 之后在项目根目录下会生成 kyanos 可执行文件。
+
+> [!IMPORTANT]
+> 但是需要注意的是该二进制文件中没有包含 [btfhub-archive](https://github.com/aquasecurity/btfhub-archive/) 中的 btf 文件，如果直接拿这个 kyanos 去没有开启 BTF 支持的低版本内核上执行可能会启动失败，通过下面的命令可以构建出一个内嵌 btf 文件的 kyanos 产物：
+> ::: code-group
+>```bash [x86_64]
+>make build-bpf && make btfgen BUILD_ARCH=x86_64 ARCH_BPF_NAME=x86 && make
+>```
+>
+>```bash [arm64]
+>make build-bpf && make btfgen BUILD_ARCH=arm64 ARCH_BPF_NAME=arm64 && make
+>```
+>:::
+> 需要注意 `make btfgen` 耗时可能超过 15min。
+
+
+> [!TIP]
+>如果你的内核没有开启BTF，你可能无法成功启动 kyanos. 
+>
+>检查是否开启BTF：
+>```
+>grep CONFIG_DEBUG_INFO_BTF "/boot/config-$(uname -r)"
+>```
+>如果结果是`CONFIG_DEBUG_INFO_BTF=y`说明开启了，如果没开启请到  [mirrors.openanolis.cn](https://mirrors.openanolis.cn/coolbpf/btf/) or [btfhub-archive](https://github.com/aquasecurity/btfhub-archive/)上下载对应你的内核版本的 btf 文件，然后启动 kyanos 时使用 `--btf` 选项指定下载的 btf 文件。
+
diff --git a/docs/how-to-build.md b/docs/how-to-build.md
@@ -26,19 +26,34 @@ In addition to the toolchain versions listed above, the compilation environment
 - pkgconf
 - libelf-dev
 
-### If Your Kernel Does Not Enable BTF
-If BTF is not enabled, you may not be able to start kyanos successfully.
 
-Check if BTF is enabled:
-```
-grep CONFIG_DEBUG_INFO_BTF "/boot/config-$(uname -r)"
-```
-If the result is `CONFIG_DEBUG_INFO_BTF=y`, it means BTF is enabled. If not, please download from [mirrors.openanolis.cn](https://mirrors.openanolis.cn/coolbpf/btf/) or [btfhub-archive](https://github.com/aquasecurity/btfhub-archive/), and use the `--btf` option to specify the downloaded BTF file when starting kyanos.
+## Compilation Commands
 
-## Compilation Command
-Execute
+If you are just developing and testing locally, you can execute
 ```
 make build-bpf && make
 ```
 
-Afterwards, the kyanos executable will be generated in the root directory of the project.
+the kyanos executable file will be generated in the root directory of the project.
+
+> [!IMPORTANT]
+> Note that this binary file does not include the BTF files from [btfhub-archive](https://github.com/aquasecurity/btfhub-archive/). If you run this kyanos on a lower version kernel without BTF support, it may fail to start. You can build a kyanos artifact with embedded BTF files using the following commands:
+> ::: code-group
+>```bash [x86_64]
+>make build-bpf && make btfgen BUILD_ARCH=x86_64 ARCH_BPF_NAME=x86 && make
+>```
+>
+>```bash [arm64]
+>make build-bpf && make btfgen BUILD_ARCH=arm64 ARCH_BPF_NAME=arm64 && make
+>```
+>:::
+> Note that make btfgen may take more than 15 minutes.
+
+> [!TIP]
+>If your kernel does not have BTF enabled, you may not be able to start kyanos successfully.
+>
+>Check if BTF is enabled:
+>```
+>grep CONFIG_DEBUG_INFO_BTF "/boot/config-$(uname -r)"
+>```
+>If the result is `CONFIG_DEBUG_INFO_BTF=y`, it means BTF is enabled. If not, please download the BTF file corresponding to your kernel version from [mirrors.openanolis.cn](https://mirrors.openanolis.cn/coolbpf/btf/) or [btfhub-archive](https://github.com/aquasecurity/btfhub-archive/), and use the `--btf` option to specify the downloaded BTF file when starting kyanos.