# 安装指南 | Installation

本页面提供 NetLeaf 在各平台上的详细安装说明。

---

## 目录 | Table of Contents

- [Windows 安装](#windows-安装)
- [Linux 安装](#linux-安装)
- [macOS 安装](#macos-安装)
- [TLS/SSL 构建](#tlsssl-构建)
- [MQTT 构建](#mqtt-构建)
- [集成到项目](#集成到项目)
- [验证安装](#验证安装)

---

## Windows 安装

### 系统要求 | System Requirements

- **操作系统**: Windows 10 1809+, Windows 11, Windows Server 2019+
- **编译器**: Visual Studio 2022 (Community/Professional/Enterprise)
- **构建工具**: CMake 3.15 或更高版本
- **架构支持**: x86 (Win32), x64, ARM64

### 安装步骤 | Installation Steps

#### 1. 安装 Visual Studio 2022

下载并安装 [Visual Studio 2022](https://visualstudio.microsoft.com/)，确保安装以下组件：
- 使用 C++ 的桌面开发 (Desktop development with C++)
- CMake tools for Visual Studio

#### 2. 安装 CMake

下载并安装 [CMake](https://cmake.org/download/)，或使用 Visual Studio 内置的 CMake。

#### 3. 克隆项目 | Clone the Repository

```powershell
git clone https://github.com/solo-agent/NetLeaf.git
cd NetLeaf
```

#### 4. 构建项目 | Build the Project

**方式一：使用批处理脚本 (推荐)**

```powershell
# 构建所有架构 (x86, x64, ARM64)
.\build_all_windows.bat

# 或构建单个架构
.\build.bat x64       # x64
.\build.bat x86       # x86 (Win32)
.\build.bat arm64     # ARM64
```

**方式二：手动 CMake**

```powershell
# x64
mkdir build_x64
cd build_x64
cmake .. -G "Visual Studio 17 2022" -A x64
cmake --build . --config Release
```

---

## Linux 安装

### 系统要求 | System Requirements

- **操作系统**: Ubuntu 20.04+, Debian 11+, CentOS 8+, 或其他现代 Linux 发行版
- **编译器**: GCC 8+ 或 Clang 10+
- **构建工具**: CMake 3.15+, Make
- **架构支持**: x64, ARM64 (计划中)

### 安装步骤 | Installation Steps

#### 1. 安装依赖 | Install Dependencies

**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install -y build-essential cmake git
```

**CentOS/RHEL:**
```bash
sudo yum install -y gcc gcc-c++ make cmake git
```

#### 2. 克隆项目 | Clone the Repository

```bash
git clone https://github.com/solo-agent/NetLeaf.git
cd NetLeaf
```

#### 3. 构建项目 | Build the Project

**方式一：使用 Shell 脚本 (推荐)**

```bash
chmod +x build_all_linux.sh
./build_all_linux.sh
```

**方式二：手动 CMake**

```bash
mkdir build_linux
cd build_linux
cmake ..
make -j$(nproc)
```

**使用 WSL (Windows Subsystem for Linux):**

```powershell
.\build_wsl.sh
```

---

## macOS 安装

### 系统要求 | System Requirements

- **操作系统**: macOS 10.15+ (Catalina or later)
- **编译器**: Xcode 12+ 或 osxcross (交叉编译)
- **构建工具**: CMake 3.15+
- **架构支持**: x64, ARM64 (Apple Silicon)

### 安装步骤 | Installation Steps

#### 方式一：使用 osxcross 交叉编译 (推荐)

在 Linux/WSL 环境下使用 osxcross 工具链进行交叉编译：

```bash
# 确保 osxcross 已安装
# 参考: https://github.com/tpoechtrager/osxcross

# 构建所有 macOS 架构
chmod +x build_macos.sh
./build_macos.sh
```

#### 方式二：直接在 macOS 上构建

```bash
# 安装 Xcode 命令行工具
xcode-select --install

# 安装 Homebrew (如果未安装)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 CMake
brew install cmake

# 构建项目
mkdir build_macos
cd build_macos
cmake ..
make -j$(sysctl -n hw.ncpu)
```

### 注意事项 | Notes

- **IPC 模块**: 在 macOS 上不可用
- **LinkAgg 模块**: 在 macOS 上不可用（依赖 IPC）
- **Vue 模块**: 完全支持
- **其他模块**: 完全支持

---

## TLS/SSL 构建

### 系统要求 | System Requirements

- **mbedTLS**: 已内置于 `third-party/mbedtls/` 目录
- **编译器**: 支持 C99 标准的编译器
- **可选依赖**: OpenSSL (仅在使用外部 TLS 库时需要)

### 构建 TLS 扩展

**方式一：使用 CMake 选项**

```powershell
# 构建包含 TLS 的版本
mkdir build_with_tls
cd build_with_tls
cmake .. -DBUILD_TLS=ON -DBUILD_MQTT=ON
cmake --build . --config Release
```

**方式二：修改 CMakeLists.txt**

```cmake
# 在项目根目录的 CMakeLists.txt 中添加
option(BUILD_TLS "Build TLS/SSL extension" ON)
option(BUILD_MQTT "Build MQTT client module" ON)
```

### 构建输出

编译完成后，将生成以下文件：

| 文件 | 说明 |
|------|------|
| `netleaf_tls.dll` (Windows) | TLS/SSL 加密扩展动态库 |
| `libnetleaf_tls.so` (Linux) | TLS/SSL 加密扩展共享库 |
| `libnetleaf_tls.dylib` (macOS) | TLS/SSL 加密扩展动态库 |
| `netleaf_mqtt.dll` (Windows) | MQTT 客户端模块（含 TLS） |
| `libnetleaf_mqtt.so` (Linux) | MQTT 客户端模块（含 TLS） |
| `libnetleaf_mqtt.dylib` (macOS) | MQTT 客户端模块（含 TLS） |

---

## MQTT 构建

### 基础构建（不含 TLS）

```powershell
# 仅构建 MQTT 核心功能
mkdir build_mqtt_no_tls
cd build_mqtt_no_tls
cmake .. -DBUILD_MQTT=ON -DBUILD_TLS=OFF
cmake --build . --config Release
```

### 完整构建（含 TLS）

```powershell
# 构建 MQTT + TLS 完整版本
mkdir build_mqtt_full
cd build_mqtt_full
cmake .. -DBUILD_MQTT=ON -DBUILD_TLS=ON
cmake --build . --config Release
```

### 构建选项说明

| 选项 | 默认值 | 说明 |
|------|--------|------|
| `BUILD_MQTT` | ON | 构建 MQTT 客户端模块 |
| `BUILD_TLS` | OFF | 构建 TLS/SSL 加密扩展（MQTT 会依赖此选项） |
| `BUILD_TESTING` | ON | 构建测试程序 |
| `BUILD_EXAMPLES` | ON | 构建示例程序 |

---

## 集成到项目 | Integrate into Your Project

### 使用 CMake (推荐)

将 NetLeaf 作为子模块或复制到您的项目中，然后在您的 `CMakeLists.txt` 中添加：

```cmake
# 添加 NetLeaf 子目录
add_subdirectory(path/to/NetLeaf)

# 链接到您的目标（使用动态库）
target_link_libraries(your_target PRIVATE netleaf_core)
```

### 直接链接库文件

构建 NetLeaf 后，将以下文件添加到您的项目中：

| 平台 | 包含目录 | 动态库文件 |
|------|---------|-----------|
| Windows x64 | `include/` | `build_x64/bin/Release/netleaf.dll` |
| Windows x86 | `include/` | `build_x86/bin/Release/netleaf.dll` |
| Windows ARM64 | `include/` | `build_arm64/bin/Release/netleaf.dll` |
| Linux x64 | `include/` | `build_linux/bin/libnetleaf.so` |
| macOS x64 | `include/` | `build_macos_x64/bin/libnetleaf.dylib` |
| macOS ARM64 | `include/` | `build_macos_arm64/bin/libnetleaf.dylib` |

---

## 验证安装 | Verify Installation

### 运行测试 | Run Tests

构建完成后，运行简单服务器验证：

```powershell
# Windows
cd build_x64
.\bin\Release\simple_server.exe

# Linux
cd build_wsl
./bin/simple_server

# macOS
cd build_macos_x64
./bin/simple_server
```

访问 http://localhost:8080 确认服务器正常运行。

### 编译您的第一个程序 | Compile Your First Program

创建一个简单的测试文件 `test.c`：

```c
#include "netleaf.h"
#include <stdio.h>

int main() {
    nl_web_server_t* server = nl_web_create(8080);
    if (!server) {
        printf("Failed to create server\n");
        return 1;
    }
    
    nl_web_add_html(server, "/", "<h1>Hello NetLeaf!</h1>");
    
    printf("Server running on http://localhost:8080\n");
    nl_web_start(server);
    
    // 事件循环
    while (1) {
        nl_modules_tick();
    }
    
    nl_web_destroy(server);
    nl_modules_shutdown();
    return 0;
}
```

编译并运行：

**Windows (MSVC):**
```powershell
cl test.c /I include /link build_x64/lib/Release/netleaf.lib
.\test.exe
```

**Linux (GCC):**
```bash
gcc test.c -I include -L build_wsl/lib -lnetleaf -o test
./test
```

---

## 常见问题 | FAQ

### Q: 构建时提示找不到 CMake？
**A:** 确保 CMake 已安装并添加到系统 PATH 环境变量中。

### Q: Linux 上编译错误提示缺少头文件？
**A:** 确保安装了完整的 build-essential 或开发工具包。

### Q: 如何使用调试版本？
**A:** 将 CMake 构建配置改为 Debug：
```powershell
cmake --build . --config Debug
```

---

[返回主页](./Home)