Kurento Developer Guide -Kurento 开发人员指南

开发人员指南

本节是对库兰托自身发展的全面指导。本文的目标读者是任何想参与为Kurento项目编写代码，或想了解该项目的源代码是如何构造的人。

如果您希望编写使用Kurento的应用程序，那么您应该阅读Writing Kurento应用程序。

目录

• 开发人员指南
  • 介绍
  • 代码库
  • 开发101
    • Libraries
    • Debian软件包
    • Build Tools
  • Build from sources
    • Install required tools
    • Add Kurento repository
    • Download KMS
    • Install build dependencies
    • Build and run KMS
    • KMS Unit Tests
    • Clean up your system
  • Install debugging symbols
  • Working on a forked library
    • Full cycle
    • In-place linking
  • Debian packaging
    • Dependency resolution: to repo or not to repo
    • Package generation script
  • How-To
    • How to add or update external libraries
    • How to add new fork libraries
    • How to work with API changes
    • Known problems

Introduction-介绍

这是KMS使用的工具和技术的概述：

• 代码是用C语言和C++语言编写的。
• 代码风格深受Gtk和GStreamer项目的影响。
• CMake是首选的构建工具，用于构建所有模块。
• 源代码在几个GitHub存储库中进行版本控制。
• 官方支持的平台是Ubuntu的长期支持（LTS）版本：Ubuntu 16.04（Xenial）和Ubuntu 18.04（Bionic）（仅64位）。
• GStreamer多媒体框架位于Kurento媒体服务器的核心。
• 除了GStreamer，KMS还使用其他库，如boost、jsoncpp、libnice等。

Code repositories-代码库

Kurento源代码存储在几个GitHub存储库中，网址为https://GitHub.com/Kurento。这些存储库中的每一个都有特定的用途，通常包含构建同名共享库所需的代码。

构成Kurento媒体服务器的所有回购之间关系的概述：

所有向图依赖项

由于依赖关系图不是严格的线性关系，因此有多种可能的方法将所有模块排序到线性依赖关系列表中；本节提供了一个可能的排序列表，该列表将在所有Kurento文档中一致使用。

Fork repositories-分叉存储库：

KMS依赖于几个开源库，其中主要的库是GStreamer。有时，这些库显示需要调整的特定行为，以便对KMS有用；有时，存在已修复的错误，但由于任何原因，上游源代码不接受修补程序。在这些情况下，虽然功能请求和/或补丁提交的正式路径仍在尝试中，但我们已经创建了受影响库的分支。

• jsoncpp
• libsrtp
• openh264
• usrsctp
• gstreamer (produces libgstreamer1.5)
• gst-plugins-base
• gst-plugins-good
• gst-plugins-bad
• gst-plugins-ugly
• gst-libav
• openwebrtc-gst-plugins
• libnice (produces gstreamer1.0-nice, gstreamer1.5-nice)

Main repositories-主要存储库

• kurento-module-creator：它是一个代码生成工具，用于生成插件的代码脚手架。此代码包括KMS代码和Kurento客户端代码。它主要有Java代码。
• kms-cmake-utils：包含一组用于使用cmake构建kms的实用程序。
• kms jsonrpc:Kurento协议是基于jsonrpc的，它使用了这个存储库中包含的jsonrpc库。它有C++代码。
• kms core：包含核心GStreamer代码。这是其他库所需的基本库。它有80%个C代码和20%个C++代码。
• kms-elements：包含提供WebRtc、Rtp、播放器、记录器等流水线功能的主要元素。它有80%个C代码和20%个C++代码。
• kms-filters：包含kms中包含的基本视频过滤器。它有65%个C代码和35%个C++代码。
• kurento-media-server：包含KMS的主要入口点。也就是说，服务器可执行代码的main（）函数。此程序依赖于位于上述存储库中的库。它主要有C++代码。

Extra repositories-分叉存储库：

KMS依赖于几个开源库，其中主要的库是GStreamer。有时，这些库显示需要调整的特定行为，以便对KMS有用；有时，存在已修复的错误，但由于任何原因，上游源代码不接受修补程序。在这些情况下，虽然功能请求和/或补丁提交的正式路径仍在尝试中，但我们已经创建了受影响库的分支。

• kms-chroma
• kms-crowddetector
• kms-platedetector
• kms-pointerdetecto

Omni-Build repository-构建存储库

这个储存库是一个特殊的项目，因为它被设计成从一个入口点构建所有KMS主储存库。此repo将其他KMS主存储库作为Git子模块：它使KMS开发更容易，因为如果您构建此项目，则不需要手动安装其他KMS主存储库的库。但是，所有其他开发和支持库仍必须手动安装。

• kms-omni-build

Client repositories-客户端代码仓库

应用服务器可以用Java开发，JavaScript可以用Node.js开发，JavaScript可以直接在浏览器中开发。每种语言都在各自的存储库中提供了支持工具。

• kurento-client-js (Node.js Application Servers, browser JavaScript)
• kurento-java (Java Application Servers)

Tutorial or demo repositories - 教程或演示代码仓库

有几个存储库包含使用Kurento或希望开发自定义Kurento模块的开发人员的示例代码。目前这些是：

• kms-datachannelexample
• kms-opencv-plugin-sample
• kms-plugin-sample
• kurento-tutorial-java
• kurento-tutorial-js
• kurento-tutorial-node

KMS开发人员必须知道如何使用KMS Fork和主存储库，并了解每个存储库都有不同的开发生命周期。KMS的大部分开发将在KMS主存储库中进行，而在Fork存储库中进行更改是不寻常的，除了更新其上游版本。

Development 101 - 开发

KMS是以Ubuntu系统为主要目标开发的C/C++项目，其依赖性管理和分发是基于Debian软件包系统。

Libraries-依赖库

将编译器配置为使用一组库并不是一项简单的任务，因为库可以由多个.so和.h文件组成。为了简化此任务，编译程序和库时使用pkg config。简而言之：当一个库安装在一个系统中时，它会在pkg配置数据库中注册它自己以及它所需的所有文件，这样以后就可以查询这些值，以便用这个库进行编译。
例如，如果要编译依赖于GLib 2.0的C程序，可以运行：

gcc -o program program.c $(pkg-config --libs --cflags glib-2.0)

Debain packages-Debian软件包

在Debian/Ubuntu系统中，开发库作为Debian包分发，这些包在公共包存储库中可用。在这些系统中开发C或C++项目时，通常也将其分发到Debian软件包中。然后可以使用命令apt get install安装它们，该命令将自动处理包的所有依赖项。
当一个库打包时，结果通常由几个包组成。这些是关于包的最常见命名约定的一些指针，尽管它们并不总是由Debian或Ubuntu维护者严格执行：

• bin packages：包含库本身的二进制文件的包。程序在开发过程中与它们相关联，它们也被加载到生产中。包名称以lib开头，后跟库的名称。
• dev packages：包含开发期间与库链接所需的文件。包名以lib开头，以-dev结尾。例如：libboost dev或libglib2.0-dev。
• dbg packages：包含调试符号以简化开发期间的错误调试。包名以lib开头，以-dbg结尾。例如：libboost dbg。
• doc packages：包含库的文档。用于开发。包名以lib开头，以-doc结尾。例如：libboost doc。
• src packages：包含库的源代码的包。它使用与bin版本相同的包名，但使用命令apt get source而不是
  apt-get install访问它。

Build tools-生成工具

有几个用于构建C/C++项目的工具：AutoTooSo、Sub、CMake、Gradle等。最重要的工具是构建文件，而所有其他工具都是围绕这个的简单包装。KMS使用CMake生成本地makefile来构建和打包项目。有一些ide可以直接识别CMake项目，比如JetBrains-CLion或Qt-Creator。

CMake项目由几个CMakeLists.txt文件组成，这些文件定义如何编译本机代码并将其打包到二进制文件和共享库中。这些文件还包含生成代码所需的库（依赖项）的列表。

要指定依赖项，必须知道如何在编译器中配置此库。已经提到的pkg-config工具是这个任务的标准事实，因此
CMake具有使用pkg-config的能力。还有一些使用CMake构建的库使用一些特定的CMake专用工具。

Building from source-源码构建项目

要直接使用KMS源代码，或者仅从源代码构建KMS，最简单的方法是使用模块KMS omni build。只需遵循以下步骤：

1、Install required tools, like Git.
2、Add the Kurento repository to your system configuration.
3、Clone kms-omni-build.
4、Install build dependencies: tools like GCC, CMake, etc., and KMS development libraries.
5、Build with CMake and Make.
6、Run the newly compiled KMS.
7、Run KMS tests
.
安装所需工具
此命令将安装下一步所需的基本工具集：

Install requied tools-安装工具

sudo apt-get update && sudo apt-get install --no-install-recommends --yes \
    build-essential \
    ca-certificates \
    cmake \
    git \
    gnupg

Add Kurento repository 添加代码仓库

这些命令将添加要由apt-get访问的Kurento存储库。在同一终端内运行：

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 5AFA7A83

# Run *ONLY ONE* of these lines:
DISTRO="xenial"  # KMS for Ubuntu 16.04 (Xenial)
DISTRO="bionic"  # KMS for Ubuntu 18.04 (Bionic)

sudo tee "/etc/apt/sources.list.d/kurento.list" >/dev/null <<EOF
# Kurento Media Server - Nightly packages
deb [arch=amd64] http://ubuntu.openvidu.io/dev $DISTRO kms6
EOF

sudo apt-get update

Download KMS-下载KMS

Run:

git clone https://github.com/Kurento/kms-omni-build.git
cd kms-omni-build
git submodule update --init --recursive
git submodule update --remote

注释
–recursive and --remote 不一起使用，因为每个单独的子模块可能都有自己的子模块，这些子模块可能需要签出一些特定的提交，我们不想更新这些子模块。

可选：如果要使用最新版本的代码，请更改为每个子模块的主分支：

REF=master
git checkout "$REF"
git submodule foreach "git checkout $REF || true"

也可以将REF设置为任何其他分支或标记，例如REF=6.12.0。这将使代码达到该版本中的状态。

Install build dependencies-安装依赖项

Run:

sudo apt-get update && sudo apt-get install --no-install-recommends --yes \
    kurento-media-server-dev

Build and run KMS

确保当前目录已经是kms omni build，然后运行以下命令：

在这里插入代码片

export MAKEFLAGS="-j$(nproc)"
./bin/kms-build-run.sh

默认情况下，脚本kms-build-run.sh将设置环境和设置以对kms进行调试生成。您可以检查该脚本以了解它提供的所有其他选项，包括用于AddressSanitizer的构建、GCC和Clang编译器之间的选择以及其他模式。

注释
如果cmake命令失败，请确保在kms-omni-build或其任何子目录下没有多个生成目录。我们已经看到有多个构建dir会导致问题，因此最好只有一个。
如果您想同时使用多个构建目录，最好在kms-omni-build目录之外的单独Git克隆上工作。

可以通过导出环境变量GST_DEBUG来设置特定类别的日志记录级别（请参见调试日志记录）。

您还可以根据脚本中的启动行手动启动KMS。在这种情况下，其他可能有用的启动选项包括：

--logs-path, -d <Path> : Path where rotating log files will be stored
--log-file-size, -s <Number> : Maximum file size for log files, in MB
--number-log-files, -n <Number> : Maximum number of log files to keep

More launch options, handled by GStreamer: https://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gst-running.html

KMS Unit Tests-KMS 单元测试

KMS使用C的检查单元测试框架（https://libcheck.github.io/Check/）。若要生成并运行所有测试，请将最后一个生成命令从make更改为make check。所有可用的测试都将运行，并在最后显示摘要报告。

注释
建议首先禁用GStreamer日志颜色，这样生成的日志文件就不会包含无关的转义序列，如^[[31；01m[[00m]等。此外，指定比默认值更高的日志级别可能会有用；设置环境变量GST_DEBUG，如日志级别和组件中所述。
完整的命令如下：

export GST_DEBUG_NO_COLOR=1
export GST_DEBUG="3,check:5"
make check

整个测试套件的日志输出将保存到文件./Testing/Temporary/lastest.log中。要查找此日志文件中每个单独测试的起点，请搜索单词“test start”。对于特定测试的开始，请搜索“{TestName}：test start”。例如：

webrtcendpoint.c:1848:test_vp8_sendrecv: test start

要生成并运行一个特定的测试，请使用make{TestName}.check。例如：

make test_agnosticbin.check

如果要分析Valgrind的内存使用情况，请使用make{TestName}.Valgrind。例如：

make test_agnosticbin.valgrind

清理你的系统

要使系统保持干净状态，请删除所有KMS包和相关的开发库。运行此命令，对于每个提示的问题，可视化将要卸载的软件包，如果您同意，请按回车键。Kurento的开发团队每天都会使用这个命令，并且可以选择——yes（这会使进程自动且无人值守），因此使用它应该是相当安全的。但是，我们不知道您的特定系统的配置是什么，为了避免卸载任何意外的包，以手动模式运行是最安全的选择。

Run:

PACKAGES=(
    # KMS main components + extra modules
    '^(kms|kurento).*'

    # Kurento external libraries
    ffmpeg
    '^gir1.2-gst.*1.5'
    gir1.2-nice-0.1
    '^(lib)?gstreamer.*1.5.*'
    '^lib(nice|s3-2|srtp|usrsctp).*'
    '^srtp-.*'
    '^openh264(-gst-plugins-bad-1.5)?'
    '^openwebrtc-gst-plugins.*'

    # System development libraries
    '^libboost-?(filesystem|log|program-options|regex|system|test|thread)?-dev'
    '^lib(glib2.0|glibmm-2.4|opencv|sigc++-2.0|soup2.4|ssl|tesseract|vpx)-dev'
    uuid-dev
)

# Run a loop over all package names and uninstall them.
for PACKAGE in "${PACKAGES[@]}"; do
    sudo apt-get purge --auto-remove "$PACKAGE" || { echo "Skip unknown package"; }
done

Install debugging symbols-安装调试符号

无论何时使用KMS源代码本身，还是在服务器或任何第三方库中的任何崩溃分析期间，都需要安装调试符号。它们提供了有关源文件名和发生问题的行的完整信息；这些信息对于成功的调试会话至关重要，并且在请求支持或提交错误报告时还需要提供这些详细信息。
安装调试符号不会对系统施加任何额外负载。因此，即使在生产设置中安装它们也不会有任何伤害，在生产设置中，当意外的崩溃导致系统崩溃并自动生成死后堆栈跟踪时，它们将被证明是有用的。
要安装与KMS相关的所有调试符号，请运行：

sudo apt-get update && sudo apt-get install --no-install-recommends --yes \
    kurento-dbg

例如，请参见安装调试符号之前和安装符号之后生成的相同堆栈跟踪之间的区别。不要发送与此示例中的第一个堆栈跟踪类似的堆栈跟踪：

# ==== NOT USEFUL: WITHOUT debugging symbols ====

$ cat /var/log/kurento-media-server/errors.log
Segmentation fault (thread 139667051341568, pid 14132)
Stack trace:
[kurento::MediaElementImpl::mediaFlowInStateChange(int, char*, KmsElementPadType)]
/usr/lib/x86_64-linux-gnu/libkmscoreimpl.so.6:0x1025E0
[g_signal_emit]
/usr/lib/x86_64-linux-gnu/libgobject-2.0.so.0:0x2B08F
[check_if_flow_media]
/usr/lib/x86_64-linux-gnu/libkmsgstcommons.so.6:0x1F9E4
[g_hook_list_marshal]
/lib/x86_64-linux-gnu/libglib-2.0.so.0:0x3A904

# ==== USEFUL: WITH debugging symbols ====

$ cat /var/log/kurento-media-server/errors.log
Segmentation fault (thread 140672899761920, pid 15217)
Stack trace:
[kurento::MediaElementImpl::mediaFlowInStateChange(int, char*, KmsElementPadType)]
/home/kurento/kms-omni-build/kms-core/src/server/implementation/objects/MediaElementImpl.cpp:479
[g_signal_emit]
/build/glib2.0-prJhLS/glib2.0-2.48.2/./gobject/gsignal.c:3443
[cb_buffer_received]
/home/kurento/kms-omni-build/kms-core/src/gst-plugins/commons/kmselement.c:578
[g_hook_list_marshal]
/build/glib2.0-prJhLS/glib2.0-2.48.2/./glib/ghook.c:673

第二个堆栈跟踪更有用，因为它指示崩溃发生的确切文件名和行号。有了这些，开发人员将至少有一个起点，从那里开始寻找任何潜在的bug。
需要注意的是，堆栈跟踪虽然很有用，但并不能替代在调试器（GDB）或内存分析器（Valgrind）下实际运行软件。大多数撞车事故需要进一步调查才能修复。

Working on a forked library-在分支上工作

以下是使用fork库的两个典型工作流：

全周期

此工作流的设置最简单、最快，但也是最慢的。要进行更改，您需要编辑库中的代码，然后构建它，生成Debian软件包，最后在系统中已安装的软件包上安装这些软件包。然后可以运行KMS并查看库中更改的效果。
当然，这是一个极其繁琐的过程，在任何比在库代码中进行两次编辑更复杂的事情中都要遵循。

就地连接

另一个工作方法是更改系统库路径，使其指向正在修改fork库的工作副本。通常，这需要使用特定的工具（通常是Automake）构建fork，更改环境变量LD_LIBRARY_PATH，并使用这样的配置运行KMS：任何必需的共享库都将加载修改后的版本，而不是系统中安装的版本。
这允许最快的开发周期，但是具体的指令是非常依赖于项目的。例如，在使用GStreamer fork时，可能需要在不使用系统中安装的任何库的情况下运行GStreamer（请参阅https://cgit.freedesktop.org/GStreamer/GStreamer/tree/scripts/gst uninstalled）。
[待办事项：为每个分叉库添加具体说明]

以下省略