第 2 章：开发环境搭建

工欲善其事，必先利其器。本章将手把手带你配置完整的 OpenGL/OpenCL 开发环境，覆盖 Linux、macOS 和 Windows 三大平台。

2.1 开发环境总览

一个典型的 OpenGL 项目需要以下组件：

┌─────────────────────────────────────────────┐
│              你的应用程序                      │
├──────────┬──────────┬──────────┬─────────────┤
│  GLFW    │  GLAD    │   GLM    │ stb_image   │
│ 窗口管理  │ 扩展加载  │ 数学库   │ 图片加载     │
├──────────┴──────────┴──────────┴─────────────┤
│              OpenGL / OpenCL API              │
├─────────────────────────────────────────────┤
│              GPU 驱动 (Mesa/NVIDIA/AMD)       │
├─────────────────────────────────────────────┤
│              操作系统                         │
└─────────────────────────────────────────────┘

组件职责对比

组件	作用	是否必需	备注
GLFW	创建窗口、管理 OpenGL 上下文、处理输入	✅ 是	替代品：SDL2、GLUT
GLAD	加载 OpenGL 扩展函数指针	✅ 是	替代品：GLEW、gl3w
GLM	矩阵/向量数学运算	✅ 推荐	头文件库，无需编译
stb_image	加载图片文件	可选	单头文件库
Mesa	开源 OpenGL/OpenCL 驱动	Linux 用	NVIDIA 用户需专有驱动

2.2 Linux 环境配置

2.2.1 安装基础工具链

# Ubuntu / Debian
sudo apt update
sudo apt install -y \
    build-essential \
    cmake \
    git \
    pkg-config

# Fedora
sudo dnf groupinstall "Development Tools"
sudo dnf install cmake git pkg-config

# Arch Linux
sudo pacman -S base-devel cmake git

2.2.2 安装 Mesa 驱动与 OpenGL 开发库

# Ubuntu / Debian
sudo apt install -y \
    libgl1-mesa-dev \
    libglu1-mesa-dev \
    mesa-utils \
    libegl1-mesa-dev

# 验证 Mesa 版本
glxinfo | grep "OpenGL version"
# 预期输出: OpenGL version string: 4.6 (Compatibility Profile) Mesa 23.x.x

2.2.3 安装 GLFW

# 方式 1：包管理器（推荐）
sudo apt install -y libglfw3-dev

# 方式 2：从源码编译（获取最新版本）
git clone https://github.com/glfw/glfw.git
cd glfw
mkdir build && cd build
cmake .. -DBUILD_SHARED_LIBS=ON -DGLFW_BUILD_EXAMPLES=OFF -DGLFW_BUILD_TESTS=OFF
make -j$(nproc)
sudo make install
sudo ldconfig

2.2.4 安装 GLEW（或使用 GLAD）

# GLEW 安装
sudo apt install -y libglew-dev

# 验证
glewinfo | head -5

💡 GLEW vs GLAD：GLAD 是更新的替代方案，支持按需加载函数，推荐使用。GLEW 仍然是稳定的选择。本教程的代码兼容两者。

2.2.5 配置 GLAD

GLAD 需要通过 Web 界面生成定制的加载器：

访问 https://glad.dav1d.de/
配置选项：
- Language: C/C++
- Specification: OpenGL
- API: gl Version 4.6（或你需要的版本）
- Profile: Core
- Generate a loader: ✅
点击 Generate，下载 glad.zip
解压到项目目录：

# 解压后的目录结构
include/
├── glad/
│   └── glad.h
└── KHR/
    └── khrplatform.h
src/
└── glad.c

# 安装到系统路径（可选）
sudo cp -r include/glad /usr/local/include/
sudo cp -r include/KHR /usr/local/include/
sudo cp src/glad.c /usr/local/src/

2.2.6 安装 GLM

# Ubuntu / Debian
sudo apt install -y libglm-dev

# 或使用 header-only 方式
git clone https://github.com/g-truc/glm.git
sudo cp -r glm/glm /usr/local/include/

2.2.7 安装 OpenCL 开发库

# NVIDIA GPU
sudo apt install -y nvidia-opencl-dev

# AMD GPU (Mesa 开源驱动)
sudo apt install -y mesa-opencl-icd

# Intel GPU
sudo apt install -y intel-opencl-icd

# 通用 OpenCL 头文件（如果包管理器版本过旧）
sudo apt install -y opencl-headers ocl-icd-opencl-dev

# 验证 OpenCL 可用
sudo apt install -y clinfo
clinfo | head -20

2.3 macOS 环境配置

2.3.1 安装 Xcode 命令行工具

xcode-select --install

2.3.2 使用 Homebrew 安装依赖

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

# 安装开发库
brew install cmake glfw glew glm

# macOS 自带 OpenCL 框架，无需额外安装

2.3.3 macOS 特殊注意

⚠️ macOS OpenGL 限制：Apple 从 macOS 10.14 开始弃用 OpenGL，最高支持 OpenGL 4.1。GLSL 版本限制在 4.10。如果你需要最新 OpenGL 特性，考虑使用 MoltenVK（Vulkan→Metal 转换层）或直接使用 Metal。

# 检查 macOS 支持的 OpenGL 版本
system_profiler SPDisplaysDataType | grep "OpenGL"

2.3.4 macOS CMake 链接差异

macOS 需要链接 OpenGL.framework：

# CMakeLists.txt 中的 macOS 特殊处理
if(APPLE)
    find_package(OpenGL REQUIRED)
    target_link_libraries(myapp ${OPENGL_LIBRARIES})
endif()

2.4 Windows 环境配置

2.4.1 安装 Visual Studio

安装 Visual Studio 2022 Community，勾选 “使用 C++ 的桌面开发” 工作负载。

2.4.2 安装 vcpkg（推荐）

# 克隆 vcpkg
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat

# 安装依赖
.\vcpkg install glfw3 glew glm opencl

2.4.3 手动配置 GLAD

与 Linux 相同，从 https://glad.dav1d.de/ 生成并下载，将 include/ 和 src/ 加入项目。

2.5 CMake 项目模板

2.5.1 完整的 CMakeLists.txt

# CMakeLists.txt - OpenGL 项目模板
cmake_minimum_required(VERSION 3.16)
project(OpenGLTutorial VERSION 1.0.0 LANGUAGES C CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# ---- 查找依赖 ----
find_package(OpenGL REQUIRED)

# GLFW（优先使用系统安装，否则用 FetchContent）
find_package(glfw3 3.3 QUIET)
if(NOT glfw3_FOUND)
    include(FetchContent)
    FetchContent_Declare(
        glfw
        GIT_REPOSITORY https://github.com/glfw/glfw.git
        GIT_TAG        3.3.9
    )
    set(GLFW_BUILD_DOCS OFF CACHE BOOL "" FORCE)
    set(GLFW_BUILD_TESTS OFF CACHE BOOL "" FORCE)
    set(GLFW_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
    FetchContent_MakeAvailable(glfw)
endif()

# GLM（头文件库）
find_package(glm QUIET)
if(NOT glm_FOUND)
    include(FetchContent)
    FetchContent_Declare(
        glm
        GIT_REPOSITORY https://github.com/g-truc/glm.git
        GIT_TAG        0.9.9.8
    )
    FetchContent_MakeAvailable(glm)
endif()

# GLAD（假设源文件在 libs/glad/）
add_library(glad STATIC libs/glad/src/glad.c)
target_include_directories(glad PUBLIC libs/glad/include)

# ---- 构建目标 ----
add_executable(${PROJECT_NAME}
    src/main.cpp
)

target_link_libraries(${PROJECT_NAME}
    PRIVATE
        OpenGL::GL
        glfw
        glad
        glm::glm
)

# Linux 需要 dl 和 pthread
if(UNIX AND NOT APPLE)
    target_link_libraries(${PROJECT_NAME} PRIVATE dl pthread)
endif()

# Windows 需要额外库
if(WIN32)
    target_link_libraries(${PROJECT_NAME} PRIVATE opengl32)
endif()

2.5.2 项目目录结构

project/
├── CMakeLists.txt
├── libs/
│   └── glad/
│       ├── include/
│       │   ├── glad/glad.h
│       │   └── KHR/khrplatform.h
│       └── src/
│           └── glad.c
├── src/
│   ├── main.cpp
│   ├── shader.h
│   └── shader.cpp
├── shaders/
│   ├── vertex.glsl
│   └── fragment.glsl
├── assets/
│   └── textures/
└── build/

2.5.3 构建与运行

# 创建构建目录
mkdir build && cd build

# 配置
cmake .. -DCMAKE_BUILD_TYPE=Release

# 编译
cmake --build . -j$(nproc)

# 运行
./OpenGLTutorial

2.6 验证环境：最小可运行程序

2.6.1 main.cpp — 窗口与清屏

// src/main.cpp - 最小 OpenGL 程序：创建窗口并清屏
#include <glad/glad.h>
#include <GLFW/glfw3.h>
#include <iostream>

// 窗口大小改变回调
void framebuffer_size_callback(GLFWwindow* window, int width, int height) {
    glViewport(0, 0, width, height);
}

// 处理键盘输入
void processInput(GLFWwindow* window) {
    if (glfwGetKey(window, GLFW_KEY_ESCAPE) == GLFW_PRESS)
        glfwSetWindowShouldClose(window, true);
}

int main() {
    // ===== 1. 初始化 GLFW =====
    glfwInit();
    glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 4);
    glfwWindowHint(GLFW_CONTEXT_VERSION_MINOR, 6);
    glfwWindowHint(GLFW_OPENGL_PROFILE, GLFW_OPENGL_CORE_PROFILE);
#ifdef __APPLE__
    glfwWindowHint(GLFW_OPENGL_FORWARD_COMPAT, GL_TRUE);
#endif

    // ===== 2. 创建窗口 =====
    GLFWwindow* window = glfwCreateWindow(800, 600, "OpenGL Setup", NULL, NULL);
    if (!window) {
        std::cerr << "Failed to create GLFW window" << std::endl;
        glfwTerminate();
        return -1;
    }
    glfwMakeContextCurrent(window);
    glfwSetFramebufferSizeCallback(window, framebuffer_size_callback);

    // ===== 3. 加载 OpenGL 函数（GLAD） =====
    if (!gladLoadGLLoader((GLADloadproc)glfwGetProcAddress)) {
        std::cerr << "Failed to initialize GLAD" << std::endl;
        return -1;
    }

    // ===== 4. 打印版本信息 =====
    std::cout << "OpenGL Version: " << glGetString(GL_VERSION) << std::endl;
    std::cout << "GLSL Version:   " << glGetString(GL_SHADING_LANGUAGE_VERSION) << std::endl;
    std::cout << "Renderer:       " << glGetString(GL_RENDERER) << std::endl;

    // ===== 5. 设置视口 =====
    glViewport(0, 0, 800, 600);

    // ===== 6. 渲染循环 =====
    while (!glfwWindowShouldClose(window)) {
        processInput(window);

        // 清屏：深蓝色背景
        glClearColor(0.1f, 0.1f, 0.2f, 1.0f);
        glClear(GL_COLOR_BUFFER_BIT);

        glfwSwapBuffers(window);
        glfwPollEvents();
    }

    // ===== 7. 清理 =====
    glfwTerminate();
    return 0;
}

2.6.2 编译运行

cd build
cmake .. && make -j$(nproc)
./OpenGLTutorial

成功后你应该看到一个 800×600 的深蓝色窗口。按 ESC 关闭。

2.7 Shader 加载工具类

后续章节会频繁使用着色器，这里先封装一个可复用的工具类：

// src/shader.h - 着色器加载与编译工具类
#ifndef SHADER_H
#define SHADER_H

#include <glad/glad.h>
#include <string>
#include <fstream>
#include <sstream>
#include <iostream>

class Shader {
public:
    unsigned int ID;  // 着色器程序 ID

    Shader(const char* vertexPath, const char* fragmentPath) {
        // 1. 读取文件
        std::string vertexCode = readFile(vertexPath);
        std::string fragmentCode = readFile(fragmentPath);

        // 2. 编译着色器
        unsigned int vertex = compileShader(GL_VERTEX_SHADER, vertexCode.c_str(), vertexPath);
        unsigned int fragment = compileShader(GL_FRAGMENT_SHADER, fragmentCode.c_str(), fragmentPath);

        // 3. 链接程序
        ID = glCreateProgram();
        glAttachShader(ID, vertex);
        glAttachShader(ID, fragment);
        glLinkProgram(ID);
        checkLinkErrors(ID);

        // 4. 清理中间对象
        glDeleteShader(vertex);
        glDeleteShader(fragment);
    }

    void use() const { glUseProgram(ID); }

    // Uniform 设置函数
    void setBool(const std::string& name, bool value) const {
        glUniform1i(glGetUniformLocation(ID, name.c_str()), (int)value);
    }
    void setInt(const std::string& name, int value) const {
        glUniform1i(glGetUniformLocation(ID, name.c_str()), value);
    }
    void setFloat(const std::string& name, float value) const {
        glUniform1f(glGetUniformLocation(ID, name.c_str()), value);
    }

private:
    std::string readFile(const char* path) {
        std::ifstream file;
        file.exceptions(std::ifstream::failbit | std::ifstream::badbit);
        try {
            file.open(path);
            std::stringstream stream;
            stream << file.rdbuf();
            return stream.str();
        } catch (std::ifstream::failure& e) {
            std::cerr << "ERROR::SHADER::FILE_NOT_READ: " << path << std::endl;
            return "";
        }
    }

    unsigned int compileShader(GLenum type, const char* source, const char* path) {
        unsigned int shader = glCreateShader(type);
        glShaderSource(shader, 1, &source, NULL);
        glCompileShader(shader);

        int success;
        glGetShaderiv(shader, GL_COMPILE_STATUS, &success);
        if (!success) {
            char infoLog[1024];
            glGetShaderInfoLog(shader, 1024, NULL, infoLog);
            std::cerr << "ERROR::SHADER::COMPILATION_FAILED (" << path << "):\n"
                      << infoLog << std::endl;
        }
        return shader;
    }

    void checkLinkErrors(unsigned int program) {
        int success;
        glGetProgramiv(program, GL_LINK_STATUS, &success);
        if (!success) {
            char infoLog[1024];
            glGetProgramInfoLog(program, 1024, NULL, infoLog);
            std::cerr << "ERROR::PROGRAM::LINKING_FAILED:\n" << infoLog << std::endl;
        }
    }
};

#endif

2.8 stb_image 配置

2.8.1 下载与集成

# 下载 stb_image.h
wget https://raw.githubusercontent.com/nothings/stb/master/stb_image.h
# 放入项目 include 目录
mkdir -p libs/stb
mv stb_image.h libs/stb/

2.8.2 在一个 .cpp 文件中实现

// src/stb_image_impl.cpp - 只在一处定义实现
#define STB_IMAGE_IMPLEMENTATION
#include "stb_image.h"

然后在 CMakeLists.txt 中添加：

target_include_directories(${PROJECT_NAME} PRIVATE libs/stb)

2.9 Docker 开发环境（可选）

如果你不想在本机安装所有依赖，可以用 Docker：

# Dockerfile - OpenGL 开发环境
FROM ubuntu:22.04

RUN apt-get update && apt-get install -y \
    build-essential cmake git \
    libgl1-mesa-dev libglu1-mesa-dev \
    libglfw3-dev libglew-dev libglm-dev \
    mesa-utils xauth \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY . .

RUN mkdir build && cd build && cmake .. && make -j$(nproc)

CMD ["./build/OpenGLTutorial"]

⚠️ Docker 中运行 OpenGL 程序需要 X11 转发或使用离屏渲染（EGL）。详见第 16 章。

2.10 常见问题排查

问题 1：`GLFW: Failed to create GLFW window`

原因: GPU 驱动不支持请求的 OpenGL 版本
解决:
  1. 检查 glxinfo | grep "OpenGL version"
  2. 降低版本请求: glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 3)
  3. 确认使用的是独立 GPU 而非软件渲染器

问题 2：`gladLoadGLLoader` 返回 false

原因: GLAD 生成版本与实际驱动不匹配
解决:
  1. 确认 GLAD 生成时选择的 GL 版本 ≤ 驱动支持的版本
  2. 确认 gladLoadGLLoader 在 glfwMakeContextCurrent 之后调用

问题 3：链接错误 `undefined reference to 'glCreateShader'`

原因: 未链接 OpenGL 库
解决:
  Linux:   -lGL (或 CMake 中 OpenGL::GL)
  macOS:   -framework OpenGL
  Windows: -lopengl32

问题 4：`libGL error: No matching fbConfigs`

原因: 在无 GPU 的服务器上运行（或缺少 DISPLAY 环境变量）
解决:
  1. 使用 EGL 离屏渲染（见第 16 章）
  2. 或设置 DISPLAY: export DISPLAY=:0

2.11 开发工具推荐

工具	用途	获取方式
RenderDoc	GPU 帧捕获与调试	https://renderdoc.org/
APITrace	OpenGL API 调用追踪	https://apitrace.github.io/
glslangValidator	GLSL 着色器编译验证	随 Vulkan SDK 安装
clinfo	OpenCL 平台/设备查询	`apt install clinfo`
GPU Viewer	GPU 信息图形化查看	GNOME 应用商店
Shader Playground	在线 GLSL 编辑器	https://www.shadertoy.com/

2.12 注意事项

⚠️ GLAD 和 GLEW 不要同时使用。两者都是 OpenGL 扩展加载器，同时使用会导致函数指针冲突。选择一个即可，本教程默认使用 GLAD。

⚠️ NVIDIA 专有驱动 vs Nouveau：Linux 上 NVIDIA GPU 有开源驱动（Nouveau）和官方闭源驱动两种。性能差异巨大，开发时务必使用官方驱动：sudo ubuntu-drivers install。

⚠️ 显卡切换：笔记本上的 NVIDIA Optimus 技术可能导致程序使用集成显卡。使用 __NV_PRIME_RENDER_OFFLOAD=1 环境变量强制使用独立 GPU。

⚠️ CMake 版本：FetchContent 功能需要 CMake 3.11+，建议使用 3.16+ 以获得最佳兼容性。

2.13 业务场景

场景 1：团队开发环境统一

使用 Docker + vcpkg 锁定所有依赖版本，确保团队成员使用相同的库版本，避免"在我机器上能跑"的问题。

场景 2：CI/CD 中的 OpenGL 构建

GitHub Actions 中没有 GPU，但可以使用 Mesa 的软件渲染器（llvmpipe）编译和运行基础测试：

# .github/workflows/build.yml
- name: Install Mesa
  run: sudo apt install -y libgl1-mesa-dev mesa-utils
- name: Build
  run: mkdir build && cd build && cmake .. && make
- name: Test (Software Renderer)
  env:
    LIBGL_ALWAYS_SOFTWARE: 1
  run: cd build && ./OpenGLTutorial --headless

场景 3：远程开发（SSH + X11）

通过 SSH 连接远程 GPU 服务器开发：

# 本地终端
ssh -X user@remote-server

# 远程服务器
export DISPLAY=:10
cd project/build && ./OpenGLTutorial

2.14 扩展阅读

资源	说明
GLFW 官方文档	窗口管理 API 参考
GLAD 生成器	在线生成 OpenGL 加载器
CMake 官方教程	CMake 入门
vcpkg 文档	C++ 包管理器
Mesa 3D	开源 GPU 驱动文档
stb 库集合	单头文件工具库

本章小结

OpenGL 开发的核心依赖：GLFW（窗口）、GLAD（扩展加载）、GLM（数学库）
Linux 使用 Mesa 或厂商专有驱动；macOS 限制在 GL 4.1；Windows 需安装厂商驱动
CMake 是跨平台构建的最佳选择，配合 FetchContent 可自动拉取依赖
环境验证：成功创建窗口并清屏即表示环境正常
Shader 工具类是后续章节的基础设施，建议提前封装好

上一章：第 1 章：概述 下一章：第 3 章：OpenGL 基础

强曰为道

第 2 章：开发环境搭建

第 2 章：开发环境搭建

2.1 开发环境总览

组件职责对比

2.2 Linux 环境配置

2.2.1 安装基础工具链

2.2.2 安装 Mesa 驱动与 OpenGL 开发库

2.2.3 安装 GLFW

2.2.4 安装 GLEW（或使用 GLAD）

2.2.5 配置 GLAD

2.2.6 安装 GLM

2.2.7 安装 OpenCL 开发库

2.3 macOS 环境配置

2.3.1 安装 Xcode 命令行工具

2.3.2 使用 Homebrew 安装依赖

2.3.3 macOS 特殊注意

2.3.4 macOS CMake 链接差异

2.4 Windows 环境配置

2.4.1 安装 Visual Studio

2.4.2 安装 vcpkg（推荐）

2.4.3 手动配置 GLAD

2.5 CMake 项目模板

2.5.1 完整的 CMakeLists.txt

2.5.2 项目目录结构

2.5.3 构建与运行

2.6 验证环境：最小可运行程序

2.6.1 main.cpp — 窗口与清屏

2.6.2 编译运行

2.7 Shader 加载工具类

2.8 stb_image 配置

2.8.1 下载与集成

2.8.2 在一个 .cpp 文件中实现

2.9 Docker 开发环境（可选）

2.10 常见问题排查

问题 1：GLFW: Failed to create GLFW window

问题 2：gladLoadGLLoader 返回 false

问题 3：链接错误 undefined reference to 'glCreateShader'

问题 4：libGL error: No matching fbConfigs

2.11 开发工具推荐

2.12 注意事项

2.13 业务场景

场景 1：团队开发环境统一

场景 2：CI/CD 中的 OpenGL 构建

场景 3：远程开发（SSH + X11）

2.14 扩展阅读

本章小结

问题 1：`GLFW: Failed to create GLFW window`

问题 2：`gladLoadGLLoader` 返回 false

问题 3：链接错误 `undefined reference to 'glCreateShader'`

问题 4：`libGL error: No matching fbConfigs`