LidarView 开发手册

1. LidarView 编译概览

本文档收集了构建基于 LidarView 的应用程序所需的所有信息。部分内容与安装指南中的信息类似。

LidarView 主要依赖于 CMake 和 superbuild 系统，它处理大多数（不是全部）必要依赖项的下载和编译。

但是由于各种原因，superbuild 可能会（或可能不会）提供某些依赖项，并且必须在某些平台上从外部获取，请参阅以下部分了解每个平台的说明。

LidarView 目前在 Windows、Ubuntu 18.04、Ubuntu 20.04 和 OSX 上积极维护。

2. 配置和构建说明

2.1 跨平台说明

跨平台依赖和工具

以下工具的特定版本可能在你的操作系统包管理器中可用，也可能不可用。

[必需] CMake 3.20.3+，下载地址：https://cmake.org/
[推荐] Ninja 1.8.2+，下载地址：https://ninja-build.org/

强烈建议在所有平台上使用 Ninja 以加快编译速度，如果你不想使用它，请确保从配置命令中删除 -GNinja 选项。

2.2 Windows 说明

2.2.1 Windows 特定依赖

Microsoft Visual Studio 14/17/19 为支持新旧版本做出了巨大努力。

如果你对向后兼容性或许可有疑虑，可能更倾向于使用 MSVC 14 (2015)，请参阅附加说明
Qt 5.15.2 你必须自己构建它并在配置时指定 Qt 的目录。

更多信息，请参阅附加说明。
[仅用于打包] NSIS version 3.04 及以上版本，下载地址：https://nsis.sourceforge.io/Download

2.2.2 Windows 注意事项

必须使用 MSVC 构建环境命令提示符（随 MSVC 一起安装）

打开位置 Windows Start Menu > Visual Studio 20XX > "VS20XX x64 Native Tools Command Prompt"

提示：如果你不熟悉 Windows 开发，建议使用该提示（Prompt）进行构建，因为与常规 cmd.exe 提示相比，它设置了适当的构建环境。
工作目录、源（src）和构建（build）路径必须短且靠近根（root）驱动器

这些目录的路径必须很短，因为 Windows 对文件路径和命令的最大长度有限制。

提示：这些路径在构建过程中会出现无数次，可能会不小心达到最大限制。
源目录不得位于 LidarView 源代码目录中

建议使用如下目录结构：

位置	工作目录
C:\src	源代码目录
C:\build	构建目录

注意：在配置或编译后移动这些目录，将破坏所有构建环境并需要完全重建。

2.2.3 Windows 构建说明

请注意，配置命令提到了源目录中的子目录“Superbuild”目录，而不是源目录本身。
请注意，CMake 变量，如 Qt5_DIR 路径参数，必须在所有平台（Unix PATH 格式）上使用正斜杠（/），否则 MSVC 将使用 \\Q 作为构建选项。
如果你更改了默认的 Qt 安装路径，则必须调整配置命令。
从头开始构建可能需要 20 分钟到 2 小时，具体取决于你的硬件性能。

默认情况下，添加 -j 选项将使用机器上所有的核进行编译，你也可以使用 -j N 指定要使用的内核数。

cd <work-directory>
git clone <git url to LidarView-based app repository> --recurse-submodules src
mkdir <work-directory>\build
cd <work-directory>\build
cmake <work-directory>\src\Superbuild -GNinja -DCMAKE_BUILD_TYPE=Release -DUSE_SYSTEM_qt5=True -DQt5_DIR="C:/Qt/Qt5.15.2/5.15.2/msvc2015_64/lib/cmake/Qt5"
cmake --build . -j
install\bin\<LidarView-based app name>

2.3 Linux 构建说明

2.3.1 Linux 特定依赖

显卡驱动

确保显卡驱动程序是最新的，确保安装了必要的图形软件包。

提示：如果你没有显卡，则需要安装 mesa 驱动程序。

软件包/库

在 Ubuntu 18.04 及更高版本上构建，需要安装以下软件包：

sudo apt-get install build-essential byacc flex freeglut3-dev libbz2-dev libffi-dev \
    libfontconfig1-dev libfreetype6-dev libnl-genl-3-dev libopengl0 libprotobuf-dev \
    libx11-dev libx11-xcb-dev libx11-xcb-dev libxcb-glx0-dev libxcb-glx0-dev \
    libxcb-icccm4-dev libxcb-image0-dev libxcb-keysyms1-dev libxcb-randr0-dev \
    libxcb-render-util0-dev libxcb-shape0-dev libxcb-shm0-dev libxcb-sync-dev \
    libxcb-util-dev libxcb-xfixes0-dev libxcb-xinerama0-dev libxcb-xkb-dev libxcb1-dev \
    libxext-dev libxext-dev libxfixes-dev libxi-dev libxkbcommon-dev libxkbcommon-dev \
    libxkbcommon-x11-dev libxkbcommon-x11-dev libxrender-dev libxt-dev pkg-config \
    protobuf-compiler zlib1g-dev

如果是 Ubuntu 20，还需要额外安装：
```
sudo apt-get install libglx-dev
```

[可选] Qt5

Qt5 由 Superbuild 自动构建，但是为了加快构建过程，你可以选择使用内置的二进制文件，选项参数如下：

如果你的系统软件包管理器提供 Qt5 5.15.2 或以上版本（例如 Ubuntu20.04），那么使用：
```
qt5-default qtmultimedia5-dev qtbase5-private-dev libqt5x11extras5-dev libqt5svg5-dev qttools5-dev
```
并将选项参数 -DUSE_SYSTEM_qt5=ON 添加到 CMake 配置中。
自行构建：详细说明请参考附加说明

2.3.2 Linux 指导说明

源目录不得位于 LidarView 源代码目录中.

推荐的目录结构如下：

/home/username/lidarview	工作目录
/home/username/lidarview/src	源目录
/home/username/lidarview/build	构建目录

**注意：**在配置或编译后移动这些目录，将破坏所有构建环境并需要完全重建。

2.3.3 Linux 编译说明

请注意，配置命令提到了源目录中的子目录 Superbuild 目录，而不是源目录本身。
如果你更改了默认的 Qt 安装路径，则必须调整配置命令。
从头开始构建可能需要 20 分钟到 2 小时，具体取决于你的硬件性能。
默认情况下，添加 -j 选项将使用机器上所有的核进行编译，你也可以使用 -j N 指定要使用的内核数。

如果你选择使用预构建的二进制文件而不是默认的 Superbuild 编译，请不要忘记 Qt5 配置选项。

cd <work-directory>
git clone <git url to LidarView-based app repository> --recurse-submodules src
mkdir <work-directory>/build
cd <work-directory>/build
cmake <work-directory>/src/Superbuild -GNinja -DCMAKE_BUILD_TYPE=Release
cmake --build . -j
./install/bin/<LidarView-based app name>

../_images/lidarview-build-done-on-ubuntu.png

3. 使能 LidarView 扩展特性

3.1 使能 SLAM 特性

在 UNIX 系统需要安装额外的软件包：
```
sudo apt-get install liblapack-dev
```

使用这些附加的选项参数，重新运行 CMake 配置命令：

-DENABLE_ceres=True -DENABLE_nanoflann=True -DENABLE_pcl=True -DLIDARVIEW_BUILD_SLAM=True

运行或重新运行 CMake 构建命令：
```
cmake --build . -j
```

有关 SLAM 的更多信息，请访问《How to SLAM with LidarView》。

3.2 使能 OpenCV 特性

安装 OpenCV

下载地址 https://opencv.org/，在 UNIX 系统中，你可以使用如下命令安装：
```
sudo apt-get install libavformat-dev libavdevice-dev libavcodec-dev
```
使用下列附加参数重新运行 CMake 配置命令：
```
-DENABLE_opencv=True
```
运行或重新运行 CMake 构建命令：
```
cmake --build . -j
```

4. 增量构建说明

如果你只修改了 LidarView 源代码，通常会希望增量构建，以缩短构建时间。命令如下：
```
cd <work-directory>\build\common-superbuild\lidarview\build
cmake --build . -j --target install
```

5. 调试构建说明

完整的 superbuild 不能在调试模式下可靠地构建，但是单个项目，如 LidarView 本身可以在 Debug 或 RelWithDebInfo 模式下构建：
```
cd <work-directory>\build\common-superbuild\lidarview\build
cmake . -DCMAKE_BUILD_TYPE=Debug
cmake --build . -j --target install
```

6. 打包说明

通过 CMake 配置激活 tests 的构建：

cd <work-directory>/build
cmake . -DBUILD_TESTING=True

使用新配置构建：
```
cmake --build . -j
```
使用 cpack 打包：
```
ctest
```

7. 测试说明

运行基于 LidarView 的应用程序测试的详细说明《LidarView Testing Guide》。

8. 附加说明

8.1 从源代码构建 Qt5.15.2 

Qt5.15.2 - Source Package

查看构建脚本 Build Script，安装位置说明：

在 Unix 系统，我们推荐安装在 /opt 目录，并使用以下命令将此目录添加到你的 ld 配置中：
```
sudo echo "/usr/local/lib" >> /etc/ld.so.conf && sudo ldconfig
```
在 Windows 系统，我们推荐安装在 C:\ 盘

* Add proper parameters to CMake configuration options: `-DUSE_SYSTEM_qt5=ON -DQt5_DIR="/path/to/install/location/lib/cmake/Qt5"`

  **Always forward slashes, UNIX style, on all platforms**

  e.g If installed in `/opt`: `-DQt5_DIR=/opt/Qt5.15.2/5.15.2/gcc_64/lib/cmake/Qt5`

  e.g If installed in `C:\` : `-DQt5_DIR=C:/Qt/Qt5.15.2/5.15.2/msvc2015_64/lib/cmake/Qt5`

8.2 Microsoft Visual Studio 14 (2015) Express 

下载地址：Microsoft Visual Studio Express 2015 for Windows Desktop - 简体中文

你也可以点击这里下载离线安装包，或者下载 ISO 镜像。

9. 疑难解答 / FAQ

9.1 UBUNTU Cannot find Qt Packages “unable to locate package qt5-default”

解决：Qt 是 community software，修改 Ubuntu 系统中的 /etc/apt/sources.list 文件，取消注释（或添加）universe PPA 源。例如，deb http://archive.ubuntu.com/ubuntu/ focal universe。

9.2 Superbuild failure with PCL enabled

由于硬件的差别，当你启用 -DENABLE_pcl=True 时，superbuild 可能会在 PCL 编译期间失败，并由于内存分配紧张而出现 Internal compiler error 错误。

要解决该问题，你可以尝试：

重新运行构建命令，因为连续的增量构建最终可能会成功。
使用 -j N 选项减少构建命令中的编译作业数量。