跳到主要内容

平台集成与部署

获取 SDK 和 Demo

1. Windows 平台​

1.1 开发环境​

必需工具:

  • Visual Studio 2019 或更高版本
  • Windows 10 SDK
  • CMake 3.15+

依赖库:

  • ws2_32.lib - Windows Sockets API
  • winhttp.lib - Windows HTTP Services

1.2 CMake 配置​

cmake_minimum_required(VERSION 3.15)
project(webglhost_native_demo VERSION 1.0.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_executable(demo demo.cpp)

target_include_directories(demo PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/include)

if(WIN32)
    target_link_libraries(demo PRIVATE ws2_32 winhttp)
    
    if(MSVC)
        target_compile_options(demo PRIVATE /W3 /MP)
    endif()
endif()

1.3 构建和运行​

一键构建运行:

cd PCDemo_cpp
scripts\build-and-run.bat

分步操作:

scripts\build.bat      # 构建（自动解压 SDK）
scripts\run.bat        # 运行
scripts\clean.bat      # 清理

手动构建:

mkdir build && cd build
cmake .. -G "Visual Studio 16 2019" -A x64
cmake --build . --config Release

1.4 部署结构​

YourApp/
├── YourApp.exe
├── host/
│   └── webglhost_export.dll
└── runtime/
    ├── webglhost-runtime.exe
    ├── icudtl.dat
    ├── v8_context_snapshot.bin
    ├── *.pak
    └── locales/

打包建议: 使用 NSIS 或 Inno Setup 创建安装程序，包含 Visual C++ 可再发行组件。

2. macOS 平台​

2.1 开发环境​

必需工具:

  • Xcode Command Line Tools
  • CMake 3.15+

系统库 (自带):

  • libcurl - HTTP 请求
  • libdl - 动态库加载

2.2 CMake 配置​

elseif(APPLE)
    find_package(CURL REQUIRED)
    target_include_directories(demo PRIVATE ${CURL_INCLUDE_DIRS})
    target_link_libraries(demo PRIVATE ${CURL_LIBRARIES})
    
    target_compile_options(demo PRIVATE -Wall -Wextra)
    
    set_target_properties(demo PROPERTIES
        BUILD_RPATH "@executable_path"
        INSTALL_RPATH "@executable_path"
    )
endif()

2.3 构建和运行​

一键构建运行:

cd PCDemo_cpp
chmod +x scripts/*.sh
./scripts/build-and-run.sh

分步操作:

./scripts/build.sh     # 构建（自动解压 SDK）
./scripts/run.sh       # 运行
./scripts/clean.sh     # 清理

架构选项:

./scripts/build.sh --arch arm64    # ARM64
./scripts/build.sh --arch x64      # x64

手动构建:

# 解压运行时
cd native_sdk/mac
cat runtime-arm64.tar.gz.* | tar -xzf - -C ../../runtime/
cd ../..

# 构建
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make

2.4 部署结构​

YourApp.app/
└── Contents/
    ├── MacOS/
    │   └── YourApp
    ├── Resources/
    │   ├── host/
    │   │   └── libwebglhost_export.dylib
    │   └── runtime/
    │       └── webglhost-runtime.app/
    └── Info.plist

代码签名:

codesign --force --sign "Developer ID Application: Your Name" YourApp.app
codesign --verify --verbose YourApp.app

3. 跨平台代码​

3.1 平台检测​

#ifdef _WIN32
    #define PLATFORM_WINDOWS
    #include <windows.h>
    #include <winhttp.h>
#elif defined(__APPLE__)
    #define PLATFORM_MACOS
    #include <dlfcn.h>
    #include <curl/curl.h>
#endif

3.2 库加载抽象​

#ifdef _WIN32
    typedef HMODULE LibHandle;
#else
    typedef void* LibHandle;
#endif

class LibraryLoader {
public:
    static LibHandle LoadLib(const char* path) {
#ifdef _WIN32
        return LoadLibraryA(path);
#else
        return dlopen(path, RTLD_NOW | RTLD_LOCAL);
#endif
    }
    
    static void* GetFunction(LibHandle lib, const char* name) {
#ifdef _WIN32
        return (void*)GetProcAddress(lib, name);
#else
        return dlsym(lib, name);
#endif
    }
    
    static void UnloadLib(LibHandle lib) {
#ifdef _WIN32
        FreeLibrary(lib);
#else
        dlclose(lib);
#endif
    }
};

3.3 运行时路径​

#ifdef _WIN32
const char* runtimePath = "runtime\\webglhost-runtime.exe";
#else
const char* runtimePath = "runtime/webglhost-runtime.app/Contents/MacOS/webglhost-runtime";
#endif

service->InitializeBrowsingCore(config, runtimePath, &handler);

4. SDK 文件组织​

SDK 文件以分卷压缩包形式存储，构建脚本会自动解压。

Windows (native_sdk/windows/):

host.zip                    # SDK DLL
runtime.z01/z02/z03         # 运行时分卷
version.json

macOS (native_sdk/mac/):

runtime-arm64.tar.gz.01/02/03   # ARM64 运行时
runtime-x64.tar.gz.01/02/03     # x64 运行时
version.json

5. 故障排查​

5.1 构建问题​

问题解决方案
CMake 找不到Windows: 下载安装 cmake.org; macOS: brew install cmake
VS 版本不匹配修改生成器: cmake -G "Visual Studio 17 2022" -A x64 ..
libcurl 未找到macOS: brew install curl

5.2 运行时问题​

Windows:

  • DLL 加载失败: 检查 host/webglhost_export.dll 是否存在
  • 运行时未找到: 确认 runtime/ 目录完整
  • 使用 dumpbin /DEPENDENTS demo.exe 检查依赖

macOS:

  • dylib 加载失败: 使用 otool -L 检查依赖
  • 架构不匹配: 使用 file demo 检查架构
  • 权限问题: 检查文件权限和代码签名

5.3 解压问题​

Windows:

# 手动解压
7z x native_sdk\windows\runtime.z01

macOS:

# 手动合并解压
cat native_sdk/mac/runtime-arm64.tar.gz.* | tar -xzf - -C runtime/

6. 相关文档​