1. 项目概述与背景在嵌入式开发中尤其是涉及到网络通信模块时我们常常会遇到一个典型的困境直接在资源受限的目标板比如ARM架构的开发板上进行代码的编译、调试和功能验证过程往往非常痛苦。编译速度慢调试工具链不完善一次简单的修改-编译-测试循环可能就要耗费十几分钟极大地拖慢了开发节奏。我之前在将libwebsockets这个轻量级的WebSocket库移植到ELF 1开发板时就深有体会。虽然交叉编译和部署的流程走通了但后续的协议调试、功能验证却成了效率瓶颈。这时一个更高效的策略就浮现出来了先在性能强大的x86主机环境比如我们常用的Ubuntu开发机上将库编译为原生架构并进行充分测试。libwebsockets本身提供了丰富的测试用例我们可以在主机上快速运行服务端和客户端模拟完整的通信流程验证库的核心功能、内存管理、连接稳定性等。待功能在x86环境下稳定后再通过交叉编译移植到目标板这时我们面对的主要就是平台适配性问题而非基础功能缺陷调试范围大大缩小效率自然成倍提升。这篇指南就是基于这个实战思路为你详细拆解如何在Ubuntu系统上从零开始编译、安装并深度测试x86架构的libwebsockets库。整个过程不仅是一份操作手册更会穿插我踩过的坑和总结的经验比如CMake参数的选择、测试程序的使用技巧、以及如何搭建一个简单的跨架构联调环境。无论你是刚接触嵌入式网络开发还是正在寻找提升调试效率的方法这篇文章都能提供直接的参考。2. 编译环境准备与源码获取在动手编译之前确保你的开发环境是干净且合适的能避免很多后续的奇怪问题。我强烈推荐使用Ubuntu 20.04 LTS或22.04 LTS作为编译主机这两个版本社区支持完善软件源稳定。你需要预先安装一些基础的开发工具和库这是编译几乎所有C/C项目的起点。打开终端执行以下命令来安装必备的软件包sudo apt update sudo apt install -y build-essential cmake git libssl-dev zlib1g-dev这里简单解释一下每个包的作用build-essential提供了GCC编译器、make等核心编译工具cmake是libwebsockets使用的构建系统生成器git用于克隆源码虽然我们也可以下载压缩包但git方式更便于后续更新libssl-dev是OpenSSL的开发库libwebsockets的SSL/TLS功能依赖它zlib1g-dev提供了压缩库支持某些特性会用到。如果你的项目确定不需要SSL理论上可以不装libssl-dev但为了测试的完整性建议一并安装。接下来是获取源码。官方源码托管在GitHub上。这里我提供两种方式各有优劣。方式一使用Git克隆推荐这种方式能获取到最新的代码并且包含完整的git历史方便切换分支或查看提交记录。cd ~ git clone https://github.com/warmcat/libwebsockets.git cd libwebsockets克隆完成后你可以通过git tag查看所有发布版本并使用git checkout v4.3.2这样的命令切换到某个稳定版本进行编译这对于生产环境尤为重要避免使用开发中分支可能引入的不稳定代码。方式二下载Release压缩包如果你所处的网络环境访问GitHub较慢或者只需要特定版本的源码可以去项目的 Release页面 下载对应的.zip或.tar.gz压缩包。假设你下载了libwebsockets-v4.3.2.zip并放到了~/work目录下cd ~/work unzip libwebsockets-v4.3.2.zip -d libwebsockets-src cd libwebsockets-src无论采用哪种方式最终你都需要进入解压后的源码根目录。为了保持工作区整洁我习惯在源码目录外创建独立的构建build和安装install目录这是一种被称为“外部构建Out-of-source build”的最佳实践它能保证源码树的纯净方便你随时清空构建目录重新开始而不会污染源码。3. CMake配置与编译安装详解进入源码目录后我们就可以开始配置和编译了。首先创建必要的目录结构# 假设当前在源码根目录 ~/work/libwebsockets-src mkdir -p build install这里创建了两个目录build用于存放所有编译过程中产生的中间文件install则作为我们指定的安装路径编译好的库文件、头文件和可执行程序最终会放在这里。使用自定义的安装路径而不是系统默认的/usr/local好处是绝对的隔离性。你可以同时存在多个不同版本或不同配置的libwebsockets互不干扰卸载时也只需删除整个install目录即可非常干净。接下来是核心的CMake配置步骤。进入build目录并运行cmakecd build cmake -DCMAKE_INSTALL_PREFIX../install -DLWS_WITH_SSLON -DLWS_WITHOUT_TESTAPPSOFF ..这条命令包含了几个关键参数理解它们能让你更好地控制编译结果-DCMAKE_INSTALL_PREFIX../install这是最重要的参数它指定了make install时的安装目标路径。我们将其指向上一级目录下的install文件夹。-DLWS_WITH_SSLON显式开启SSL/TLS支持。即使系统安装了OpenSSL显式开启也是个好习惯。如果你确认你的应用场景完全不需要HTTPS或WSSWebSocket Secure可以将其设为OFF以减小库体积并简化依赖。-DLWS_WITHOUT_TESTAPPSOFF确保编译生成测试应用程序。这些测试程序如libwebsockets-test-server对我们后续的功能验证至关重要所以这里必须开启或保持默认的OFF状态因为WITHOUT是双重否定OFF表示“不排除”即包含。..这个参数告诉CMakeCMakeLists.txt配置文件位于当前目录的上一级即源码根目录。执行完cmake后终端会输出一大段配置信息。请仔细浏览确认没有红色的“ERROR”字样并关注几个关键点Found OpenSSL是否显示为YES以及其版本号LWS_WITH_SSL是否显示为ONLWS_WITHOUT_TESTAPPS是否显示为OFF。这相当于一次编译前的自检。注意CMake会探测系统环境。如果遇到找不到OpenSSL的情况请再次确认libssl-dev已正确安装。有时64位系统需要额外安装libssl-dev:amd64包。配置成功后就可以开始编译了make -j$(nproc)这里-j$(nproc)参数非常实用。nproc命令会获取你CPU的核心数$(nproc)则是将其作为参数值。-j选项允许并行编译能充分利用多核CPU显著加快编译速度。例如在一个8核的机器上这相当于启动了8个编译任务同时进行。编译过程可能需要一两分钟期间终端会滚动输出编译信息。完成后执行安装命令make install这个命令会将编译好的产物静态库.a、动态库.so、头文件.h、测试程序等按照之前CMake的配置复制到../install目录下。完成后你可以查看安装目录的结构ls -la ../install/通常会看到bin/,include/,lib/,share/等子目录。bin/里就是我们需要的测试程序。4. 基础功能测试与验证编译安装成功只是万里长征第一步。库文件本身是否正常提供的功能是否可用必须通过实际运行来检验。libwebsockets自带的测试程序就是我们最好的工具。首先切换到安装目录的bin文件夹下cd ../install/bin ls -l你应该能看到几个可执行文件例如libwebsockets-test-server,libwebsockets-test-client,libwebsockets-test-server-extpoll等。这些就是官方提供的功能测试程序。我们来启动最基本的测试服务器./libwebsockets-test-server如果一切正常终端会输出类似以下的信息[2024-06-24 10:00:00] [NOTICE] Initial logging level 7 [2024-06-24 10:00:00] [NOTICE] Libwebsockets version: 4.3.2 [2024-06-24 10:00:00] [NOTICE] IPV6 not compiled in [2024-06-24 10:00:00] [NOTICE] Using non-SSL mode [2024-06-24 10:00:00] [NOTICE] Listening on port 7681 [2024-06-24 10:00:00] [NOTICE] mem: platform fd map: 8192 bytes ...最关键的一行是Listening on port 7681。这说明服务器已经成功启动并在本机的7681端口上监听普通的WebSocket连接非SSL。注意如果你的机器有防火墙如UFW需要确保7681端口是开放的或者临时关闭防火墙进行测试sudo ufw disable测试完记得重新开启sudo ufw enable。接下来进行访问测试。打开你电脑上的任何一款现代浏览器Chrome, Firefox, Edge等在地址栏输入http://你的Ubuntu主机IP地址:7681如何获取主机IP地址在Ubuntu终端里输入ip addr show或hostname -I找到类似于192.168.1.xxx或10.0.0.xxx的地址。例如如果你的IP是192.168.2.101则在浏览器输入http://192.168.2.101:7681。如果网络连通且服务器运行正常浏览器页面会显示一个简单的WebSocket测试界面通常包含一个连接状态显示和一些基础的发送/接收测试按钮。这个页面本身就是通过WebSocket与后台服务器通信的。你能看到这个页面就证明libwebsockets库的基础HTTP服务和WebSocket协议栈工作完全正常。实操心得有时候浏览器访问不了别急着怀疑库有问题。按这个顺序排查1. 确认服务器程序是否在运行检查终端输出。2. 确认IP地址是否正确在Ubuntu上用curl http://localhost:7681试试如果本机可以访问说明是网络问题。3. 确认主机和浏览器所在机器是否在同一局域网如果是虚拟机网络模式设置为“桥接”通常最省事。4. 关闭防火墙或添加端口规则。5. 进阶测试模拟客户端-服务器交互基础测试验证了服务器能跑起来但一个完整的WebSocket应用离不开客户端。我们可以在同一台机器上利用libwebsockets-test-client来模拟一个客户端与测试服务器进行交互这能更深入地测试连接建立、消息收发等核心功能。首先确保测试服务器仍在运行在第一个终端窗口。然后打开第二个终端窗口同样进入到安装目录的bin文件夹cd ~/work/libwebsockets-src/install/bin运行测试客户端连接本地服务器./libwebsockets-test-client localhost --port7681命令解析localhost指定服务器地址为本机--port7681指定端口。客户端启动后会尝试与服务器建立WebSocket连接。连接成功后客户端会打印类似以下信息[2024-06-24 10:05:01] [NOTICE] Client connecting to localhost:7681.... [2024-06-24 10:05:01] [NOTICE] mirror: LWS_CALLBACK_CLIENT_ESTABLISHEDLWS_CALLBACK_CLIENT_ESTABLISHED这个回调消息是关键信号它表明客户端视角的WebSocket连接已经成功建立。此时客户端会默认进入一个“回显echo”模式它会自动向服务器发送一些测试消息并等待服务器原样返回。你可以在运行服务器的第一个终端窗口看到相应的活动日志例如接收到连接、处理消息等记录。而在客户端窗口你会看到它发送和接收的消息内容。这是一个完整的、自包含的本地回路测试它验证了从TCP连接到WebSocket握手再到应用层数据收发的完整链路在x86原生环境下是畅通无阻的。测试扩展使用外部客户端工具除了自带的测试客户端我们还可以使用更通用的工具来测试比如websocat一个命令行WebSocket工具或者浏览器开发者工具中的WebSocket面板。这能进一步验证库的协议兼容性。例如安装websocat后# 安装websocat (需要Rust环境或直接下载二进制包) # 使用它连接测试服务器 websocat ws://localhost:7681连接成功后你可以手动输入一些字符串并按回车发送观察服务器是否能够正确接收并回应测试服务器通常也会将消息回显。这种多工具交叉验证的方式能让你对库的稳定性和兼容性更有信心。6. 构建跨架构联调测试环境将库在x86上编译测试的终极目的是为了更高效地服务嵌入式开发。因此构建一个x86服务器 ARM客户端的联调环境极具价值。这能模拟出最终产品的一部分网络交互场景在强大的主机上进行服务器端逻辑的调试和压力测试。前提条件确保你的x86主机或虚拟机和ARM开发板如ELF 1处于同一个局域网段能够互相ping通。对于虚拟机网络模式设置为“桥接Bridged”是最直接的方式这样虚拟机会从路由器获取一个和开发板同网段的IP就像一台真实的物理机。第一步在x86主机上运行服务器这一步我们已经很熟悉了。在主机上运行cd ~/work/libwebsockets-src/install/bin ./libwebsockets-test-server记下主机在当前局域网内的IP地址例如192.168.2.100。第二步在ARM开发板上运行客户端首先你需要确保libwebsockets库已经通过交叉编译并安装到了开发板上。假设交叉编译的安装路径是/usr/local/arm-libwebsockets并且测试客户端程序libwebsockets-test-client已在开发板的PATH环境变量中或者你知道其完整路径。通过串口或SSH登录到你的ELF 1开发板执行libwebsockets-test-client 192.168.2.100 --port7681请将192.168.2.100替换为你主机的实际IP地址。第三步观察与分析在主机服务器终端你会看到来自开发板IP地址的新连接日志。这证明了网络路由是通的并且ARM客户端成功发起了TCP连接并完成了WebSocket握手。在开发板客户端终端如果连接成功你应该会看到熟悉的LWS_CALLBACK_CLIENT_ESTABLISHED消息。随后客户端也会开始进行消息回显测试。这个简单的跨架构测试成功意义重大验证了网络基础证明主机与开发板之间的网络配置正确防火墙没有阻挡7681端口。验证了协议兼容性证明为ARM架构编译的libwebsockets客户端库与x86架构的服务器库在WebSocket协议通信上是完全兼容的没有因架构不同而产生协议解析错误。奠定了调试基础今后你可以将复杂的、需要频繁修改的业务逻辑放在x86服务器上开发和调试而开发板只运行相对稳定的客户端连接代码。调试效率将从“编译-部署到板子-测试”的漫长循环转变为“在主机上修改代码、快速编译、即时测试”只有最终的集成测试才需要动用开发板。注意事项在实际操作中开发板运行客户端可能会失败。常见原因有1. 开发板时间不同步导致SSL证书验证失败如果用了WSS。2. 开发板DNS配置问题无法解析主机名建议直接使用IP地址。3. 开发板上的防火墙或安全策略。4. 交叉编译时库的配置选项如SSL与服务器端不匹配。从最简单的非SSL模式开始测试是排除问题的好方法。7. 编译与测试过程中的常见问题排查即便按照步骤操作也可能会遇到各种问题。这里我整理了一份常见问题速查表涵盖了从编译到测试各个阶段可能遇到的“坑”。问题现象可能原因排查步骤与解决方案CMake配置失败报错找不到OpenSSL1.libssl-dev未安装。2. 安装了但CMake在非标准路径查找。1. 运行sudo apt install libssl-dev确认安装。2. 尝试指定OpenSSL路径cmake -DOPENSSL_ROOT_DIR/usr/lib/x86_64-linux-gnu/ ..make编译时大量报错提示函数未定义或头文件找不到1. 依赖库的头文件或库文件确实缺失。2. 之前失败的编译残留了错误缓存。1. 根据错误信息安装对应-dev包如zlib1g-dev。2.彻底删除build目录重新创建并运行CMake。这是解决许多编译怪问题的万能钥匙。make install时提示权限不足安装路径CMAKE_INSTALL_PREFIX指向了系统目录如/usr/local需要sudo。方案一使用sudo make install不推荐污染系统。方案二推荐重新配置CMake使用用户目录下的自定义路径如../install。测试服务器启动后浏览器无法访问1. 服务器IP地址输入错误。2. 主机防火墙阻止了7681端口。3. 服务器绑定到了127.0.0.1而非0.0.0.0。1. 用hostname -I确认IP。2. 临时禁用防火墙sudo ufw disable或放行端口sudo ufw allow 7681。3. libwebsockets测试服务器默认监听所有接口(0.0.0.0)一般不是此问题。可在本机用curl http://localhost:7681测试。客户端连接服务器失败提示“Connection refused”1. 服务器程序没有运行。2. 端口号错误。3. 网络不通跨设备时。1. 检查服务器进程是否在运行 ps aux客户端连接失败提示SSL相关错误1. 服务器以非SSL模式运行客户端却尝试SSL连接或反之。2. 证书问题。1. 确保两端模式一致。测试服务器默认非SSL。客户端不加--ssl参数。2. 对于自签名证书测试客户端可能需要添加-k或--no-validate参数来跳过证书验证。跨设备主机-开发板测试时开发板客户端无法连接1. 虚拟机网络模式不是桥接。2. 主机防火墙阻止了来自局域网的连接。3. 开发板与主机不在同一网段。1. 将虚拟机网络设置为“桥接模式”。2. 在主机的防火墙规则中允许7681端口的入站连接来源为局域网。3. 分别检查主机和开发板的IP地址和子网掩码确保它们在同一个子网内如都是192.168.2.x。一个我踩过的具体案例有一次在全新安装的Ubuntu虚拟机上编译make一切顺利但运行测试服务器时立刻核心转储Core Dump。经过排查发现是因为默认的编译优化级别较高-O2而虚拟机分配的CPU核心数较少某个并行编译的环节出现了极罕见的竞态条件。解决方案是在CMake时添加-DCMAKE_BUILD_TYPEDebug参数以调试模式编译问题就消失了。这提醒我们如果遇到非常诡异的运行时崩溃切换编译类型Debug/Release是一个有效的排查手段。8. 集成到自有项目与编译选项探讨当你完成了库的编译和基础测试接下来就要思考如何将它用到自己的C/C项目中了。这里主要涉及头文件包含、库文件链接以及CMake集成。手动链接适用于简单项目假设你的项目目录结构如下my_project/ ├── src/ │ └── main.c ├── libwebsockets_install/ (这是你之前编译的install目录的拷贝) │ ├── include/ │ ├── lib/ │ └── bin/ └── Makefile在你的main.c中需要包含libwebsockets的头文件#include libwebsockets.h在编译你的程序时需要指定头文件路径和链接库gcc -o my_app src/main.c -I./libwebsockets_install/include -L./libwebsockets_install/lib -lwebsockets -lssl -lcrypto -lz参数解释-I./libwebsockets_install/include告诉编译器在哪里查找libwebsockets.h。-L./libwebsockets_install/lib告诉链接器在哪里查找libwebsockets.so或libwebsockets.a。-lwebsockets链接libwebsockets动态库。-lssl -lcrypto链接OpenSSL库如果编译时开启了SSL。-lz链接压缩库。使用CMake集成推荐尤其对于复杂项目如果你的项目使用CMake集成会优雅得多。可以将libwebsockets的安装路径作为依赖引入。在你的项目CMakeLists.txt中添加# 设置libwebsockets的安装路径 set(LWS_DIR /path/to/your/libwebsockets_install/lib/cmake/libwebsockets) # 查找libwebsockets包 find_package(Libwebsockets REQUIRED HINTS ${LWS_DIR}) # 将你的目标程序与libwebsockets链接 target_include_directories(my_app PRIVATE ${LIBWEBSOCKETS_INCLUDE_DIRS}) target_link_libraries(my_app PRIVATE ${LIBWEBSOCKETS_LIBRARIES})这种方式能自动处理所有的依赖传递包括OpenSSL和zlib。关键编译选项解析在最初运行CMake时我们只用了最基础的选项。libwebsockets提供了大量选项来裁剪功能以适应不同的应用场景。了解它们可以在资源受限的嵌入式环境中有效减小库的体积-DLWS_WITH_SSLON/OFF最重要的选项。开启SSL支持会增加库大小和依赖。如果设备仅用于内网不加密通信可以关闭。-DLWS_WITHOUT_TESTAPPSON发布时建议开启。这会排除所有测试程序的编译显著减少安装包大小。-DLWS_WITHOUT_EXTENSIONSON关闭WebSocket扩展如permessage-deflate压缩。可以减小体积但可能影响与某些浏览器的兼容性。-DLWS_WITHOUT_SERVERON/-DLWS_WITHOUT_CLIENTON如果你的设备只做客户端或只做服务器可以关闭另一半功能来精简。-DLWS_MAX_SMP1如果你明确知道应用程序只会单线程运行可以将其设为1移除一些线程同步代码。-DLWS_WITH_MINIMAL_EXAMPLESON开启此选项会编译一些极简示例对于学习库的API使用非常有帮助。我的建议是在x86主机上开发调试时使用功能完整的默认配置。当需要为嵌入式设备进行最终发布版的交叉编译时再根据设备的实际角色和资源情况仔细斟酌并裁剪这些选项生成一个最精简的库。你可以通过多次编译对比install/lib目录下库文件的大小来直观感受不同选项带来的影响。这个在主机上摸索、验证再到目标板定型的流程正是“主机开发调试目标板部署运行”模式的优势所在。
Ubuntu下编译与测试libwebsockets：从x86环境验证到嵌入式移植
发布时间：2026/5/19 14:36:19
1. 项目概述与背景在嵌入式开发中尤其是涉及到网络通信模块时我们常常会遇到一个典型的困境直接在资源受限的目标板比如ARM架构的开发板上进行代码的编译、调试和功能验证过程往往非常痛苦。编译速度慢调试工具链不完善一次简单的修改-编译-测试循环可能就要耗费十几分钟极大地拖慢了开发节奏。我之前在将libwebsockets这个轻量级的WebSocket库移植到ELF 1开发板时就深有体会。虽然交叉编译和部署的流程走通了但后续的协议调试、功能验证却成了效率瓶颈。这时一个更高效的策略就浮现出来了先在性能强大的x86主机环境比如我们常用的Ubuntu开发机上将库编译为原生架构并进行充分测试。libwebsockets本身提供了丰富的测试用例我们可以在主机上快速运行服务端和客户端模拟完整的通信流程验证库的核心功能、内存管理、连接稳定性等。待功能在x86环境下稳定后再通过交叉编译移植到目标板这时我们面对的主要就是平台适配性问题而非基础功能缺陷调试范围大大缩小效率自然成倍提升。这篇指南就是基于这个实战思路为你详细拆解如何在Ubuntu系统上从零开始编译、安装并深度测试x86架构的libwebsockets库。整个过程不仅是一份操作手册更会穿插我踩过的坑和总结的经验比如CMake参数的选择、测试程序的使用技巧、以及如何搭建一个简单的跨架构联调环境。无论你是刚接触嵌入式网络开发还是正在寻找提升调试效率的方法这篇文章都能提供直接的参考。2. 编译环境准备与源码获取在动手编译之前确保你的开发环境是干净且合适的能避免很多后续的奇怪问题。我强烈推荐使用Ubuntu 20.04 LTS或22.04 LTS作为编译主机这两个版本社区支持完善软件源稳定。你需要预先安装一些基础的开发工具和库这是编译几乎所有C/C项目的起点。打开终端执行以下命令来安装必备的软件包sudo apt update sudo apt install -y build-essential cmake git libssl-dev zlib1g-dev这里简单解释一下每个包的作用build-essential提供了GCC编译器、make等核心编译工具cmake是libwebsockets使用的构建系统生成器git用于克隆源码虽然我们也可以下载压缩包但git方式更便于后续更新libssl-dev是OpenSSL的开发库libwebsockets的SSL/TLS功能依赖它zlib1g-dev提供了压缩库支持某些特性会用到。如果你的项目确定不需要SSL理论上可以不装libssl-dev但为了测试的完整性建议一并安装。接下来是获取源码。官方源码托管在GitHub上。这里我提供两种方式各有优劣。方式一使用Git克隆推荐这种方式能获取到最新的代码并且包含完整的git历史方便切换分支或查看提交记录。cd ~ git clone https://github.com/warmcat/libwebsockets.git cd libwebsockets克隆完成后你可以通过git tag查看所有发布版本并使用git checkout v4.3.2这样的命令切换到某个稳定版本进行编译这对于生产环境尤为重要避免使用开发中分支可能引入的不稳定代码。方式二下载Release压缩包如果你所处的网络环境访问GitHub较慢或者只需要特定版本的源码可以去项目的 Release页面 下载对应的.zip或.tar.gz压缩包。假设你下载了libwebsockets-v4.3.2.zip并放到了~/work目录下cd ~/work unzip libwebsockets-v4.3.2.zip -d libwebsockets-src cd libwebsockets-src无论采用哪种方式最终你都需要进入解压后的源码根目录。为了保持工作区整洁我习惯在源码目录外创建独立的构建build和安装install目录这是一种被称为“外部构建Out-of-source build”的最佳实践它能保证源码树的纯净方便你随时清空构建目录重新开始而不会污染源码。3. CMake配置与编译安装详解进入源码目录后我们就可以开始配置和编译了。首先创建必要的目录结构# 假设当前在源码根目录 ~/work/libwebsockets-src mkdir -p build install这里创建了两个目录build用于存放所有编译过程中产生的中间文件install则作为我们指定的安装路径编译好的库文件、头文件和可执行程序最终会放在这里。使用自定义的安装路径而不是系统默认的/usr/local好处是绝对的隔离性。你可以同时存在多个不同版本或不同配置的libwebsockets互不干扰卸载时也只需删除整个install目录即可非常干净。接下来是核心的CMake配置步骤。进入build目录并运行cmakecd build cmake -DCMAKE_INSTALL_PREFIX../install -DLWS_WITH_SSLON -DLWS_WITHOUT_TESTAPPSOFF ..这条命令包含了几个关键参数理解它们能让你更好地控制编译结果-DCMAKE_INSTALL_PREFIX../install这是最重要的参数它指定了make install时的安装目标路径。我们将其指向上一级目录下的install文件夹。-DLWS_WITH_SSLON显式开启SSL/TLS支持。即使系统安装了OpenSSL显式开启也是个好习惯。如果你确认你的应用场景完全不需要HTTPS或WSSWebSocket Secure可以将其设为OFF以减小库体积并简化依赖。-DLWS_WITHOUT_TESTAPPSOFF确保编译生成测试应用程序。这些测试程序如libwebsockets-test-server对我们后续的功能验证至关重要所以这里必须开启或保持默认的OFF状态因为WITHOUT是双重否定OFF表示“不排除”即包含。..这个参数告诉CMakeCMakeLists.txt配置文件位于当前目录的上一级即源码根目录。执行完cmake后终端会输出一大段配置信息。请仔细浏览确认没有红色的“ERROR”字样并关注几个关键点Found OpenSSL是否显示为YES以及其版本号LWS_WITH_SSL是否显示为ONLWS_WITHOUT_TESTAPPS是否显示为OFF。这相当于一次编译前的自检。注意CMake会探测系统环境。如果遇到找不到OpenSSL的情况请再次确认libssl-dev已正确安装。有时64位系统需要额外安装libssl-dev:amd64包。配置成功后就可以开始编译了make -j$(nproc)这里-j$(nproc)参数非常实用。nproc命令会获取你CPU的核心数$(nproc)则是将其作为参数值。-j选项允许并行编译能充分利用多核CPU显著加快编译速度。例如在一个8核的机器上这相当于启动了8个编译任务同时进行。编译过程可能需要一两分钟期间终端会滚动输出编译信息。完成后执行安装命令make install这个命令会将编译好的产物静态库.a、动态库.so、头文件.h、测试程序等按照之前CMake的配置复制到../install目录下。完成后你可以查看安装目录的结构ls -la ../install/通常会看到bin/,include/,lib/,share/等子目录。bin/里就是我们需要的测试程序。4. 基础功能测试与验证编译安装成功只是万里长征第一步。库文件本身是否正常提供的功能是否可用必须通过实际运行来检验。libwebsockets自带的测试程序就是我们最好的工具。首先切换到安装目录的bin文件夹下cd ../install/bin ls -l你应该能看到几个可执行文件例如libwebsockets-test-server,libwebsockets-test-client,libwebsockets-test-server-extpoll等。这些就是官方提供的功能测试程序。我们来启动最基本的测试服务器./libwebsockets-test-server如果一切正常终端会输出类似以下的信息[2024-06-24 10:00:00] [NOTICE] Initial logging level 7 [2024-06-24 10:00:00] [NOTICE] Libwebsockets version: 4.3.2 [2024-06-24 10:00:00] [NOTICE] IPV6 not compiled in [2024-06-24 10:00:00] [NOTICE] Using non-SSL mode [2024-06-24 10:00:00] [NOTICE] Listening on port 7681 [2024-06-24 10:00:00] [NOTICE] mem: platform fd map: 8192 bytes ...最关键的一行是Listening on port 7681。这说明服务器已经成功启动并在本机的7681端口上监听普通的WebSocket连接非SSL。注意如果你的机器有防火墙如UFW需要确保7681端口是开放的或者临时关闭防火墙进行测试sudo ufw disable测试完记得重新开启sudo ufw enable。接下来进行访问测试。打开你电脑上的任何一款现代浏览器Chrome, Firefox, Edge等在地址栏输入http://你的Ubuntu主机IP地址:7681如何获取主机IP地址在Ubuntu终端里输入ip addr show或hostname -I找到类似于192.168.1.xxx或10.0.0.xxx的地址。例如如果你的IP是192.168.2.101则在浏览器输入http://192.168.2.101:7681。如果网络连通且服务器运行正常浏览器页面会显示一个简单的WebSocket测试界面通常包含一个连接状态显示和一些基础的发送/接收测试按钮。这个页面本身就是通过WebSocket与后台服务器通信的。你能看到这个页面就证明libwebsockets库的基础HTTP服务和WebSocket协议栈工作完全正常。实操心得有时候浏览器访问不了别急着怀疑库有问题。按这个顺序排查1. 确认服务器程序是否在运行检查终端输出。2. 确认IP地址是否正确在Ubuntu上用curl http://localhost:7681试试如果本机可以访问说明是网络问题。3. 确认主机和浏览器所在机器是否在同一局域网如果是虚拟机网络模式设置为“桥接”通常最省事。4. 关闭防火墙或添加端口规则。5. 进阶测试模拟客户端-服务器交互基础测试验证了服务器能跑起来但一个完整的WebSocket应用离不开客户端。我们可以在同一台机器上利用libwebsockets-test-client来模拟一个客户端与测试服务器进行交互这能更深入地测试连接建立、消息收发等核心功能。首先确保测试服务器仍在运行在第一个终端窗口。然后打开第二个终端窗口同样进入到安装目录的bin文件夹cd ~/work/libwebsockets-src/install/bin运行测试客户端连接本地服务器./libwebsockets-test-client localhost --port7681命令解析localhost指定服务器地址为本机--port7681指定端口。客户端启动后会尝试与服务器建立WebSocket连接。连接成功后客户端会打印类似以下信息[2024-06-24 10:05:01] [NOTICE] Client connecting to localhost:7681.... [2024-06-24 10:05:01] [NOTICE] mirror: LWS_CALLBACK_CLIENT_ESTABLISHEDLWS_CALLBACK_CLIENT_ESTABLISHED这个回调消息是关键信号它表明客户端视角的WebSocket连接已经成功建立。此时客户端会默认进入一个“回显echo”模式它会自动向服务器发送一些测试消息并等待服务器原样返回。你可以在运行服务器的第一个终端窗口看到相应的活动日志例如接收到连接、处理消息等记录。而在客户端窗口你会看到它发送和接收的消息内容。这是一个完整的、自包含的本地回路测试它验证了从TCP连接到WebSocket握手再到应用层数据收发的完整链路在x86原生环境下是畅通无阻的。测试扩展使用外部客户端工具除了自带的测试客户端我们还可以使用更通用的工具来测试比如websocat一个命令行WebSocket工具或者浏览器开发者工具中的WebSocket面板。这能进一步验证库的协议兼容性。例如安装websocat后# 安装websocat (需要Rust环境或直接下载二进制包) # 使用它连接测试服务器 websocat ws://localhost:7681连接成功后你可以手动输入一些字符串并按回车发送观察服务器是否能够正确接收并回应测试服务器通常也会将消息回显。这种多工具交叉验证的方式能让你对库的稳定性和兼容性更有信心。6. 构建跨架构联调测试环境将库在x86上编译测试的终极目的是为了更高效地服务嵌入式开发。因此构建一个x86服务器 ARM客户端的联调环境极具价值。这能模拟出最终产品的一部分网络交互场景在强大的主机上进行服务器端逻辑的调试和压力测试。前提条件确保你的x86主机或虚拟机和ARM开发板如ELF 1处于同一个局域网段能够互相ping通。对于虚拟机网络模式设置为“桥接Bridged”是最直接的方式这样虚拟机会从路由器获取一个和开发板同网段的IP就像一台真实的物理机。第一步在x86主机上运行服务器这一步我们已经很熟悉了。在主机上运行cd ~/work/libwebsockets-src/install/bin ./libwebsockets-test-server记下主机在当前局域网内的IP地址例如192.168.2.100。第二步在ARM开发板上运行客户端首先你需要确保libwebsockets库已经通过交叉编译并安装到了开发板上。假设交叉编译的安装路径是/usr/local/arm-libwebsockets并且测试客户端程序libwebsockets-test-client已在开发板的PATH环境变量中或者你知道其完整路径。通过串口或SSH登录到你的ELF 1开发板执行libwebsockets-test-client 192.168.2.100 --port7681请将192.168.2.100替换为你主机的实际IP地址。第三步观察与分析在主机服务器终端你会看到来自开发板IP地址的新连接日志。这证明了网络路由是通的并且ARM客户端成功发起了TCP连接并完成了WebSocket握手。在开发板客户端终端如果连接成功你应该会看到熟悉的LWS_CALLBACK_CLIENT_ESTABLISHED消息。随后客户端也会开始进行消息回显测试。这个简单的跨架构测试成功意义重大验证了网络基础证明主机与开发板之间的网络配置正确防火墙没有阻挡7681端口。验证了协议兼容性证明为ARM架构编译的libwebsockets客户端库与x86架构的服务器库在WebSocket协议通信上是完全兼容的没有因架构不同而产生协议解析错误。奠定了调试基础今后你可以将复杂的、需要频繁修改的业务逻辑放在x86服务器上开发和调试而开发板只运行相对稳定的客户端连接代码。调试效率将从“编译-部署到板子-测试”的漫长循环转变为“在主机上修改代码、快速编译、即时测试”只有最终的集成测试才需要动用开发板。注意事项在实际操作中开发板运行客户端可能会失败。常见原因有1. 开发板时间不同步导致SSL证书验证失败如果用了WSS。2. 开发板DNS配置问题无法解析主机名建议直接使用IP地址。3. 开发板上的防火墙或安全策略。4. 交叉编译时库的配置选项如SSL与服务器端不匹配。从最简单的非SSL模式开始测试是排除问题的好方法。7. 编译与测试过程中的常见问题排查即便按照步骤操作也可能会遇到各种问题。这里我整理了一份常见问题速查表涵盖了从编译到测试各个阶段可能遇到的“坑”。问题现象可能原因排查步骤与解决方案CMake配置失败报错找不到OpenSSL1.libssl-dev未安装。2. 安装了但CMake在非标准路径查找。1. 运行sudo apt install libssl-dev确认安装。2. 尝试指定OpenSSL路径cmake -DOPENSSL_ROOT_DIR/usr/lib/x86_64-linux-gnu/ ..make编译时大量报错提示函数未定义或头文件找不到1. 依赖库的头文件或库文件确实缺失。2. 之前失败的编译残留了错误缓存。1. 根据错误信息安装对应-dev包如zlib1g-dev。2.彻底删除build目录重新创建并运行CMake。这是解决许多编译怪问题的万能钥匙。make install时提示权限不足安装路径CMAKE_INSTALL_PREFIX指向了系统目录如/usr/local需要sudo。方案一使用sudo make install不推荐污染系统。方案二推荐重新配置CMake使用用户目录下的自定义路径如../install。测试服务器启动后浏览器无法访问1. 服务器IP地址输入错误。2. 主机防火墙阻止了7681端口。3. 服务器绑定到了127.0.0.1而非0.0.0.0。1. 用hostname -I确认IP。2. 临时禁用防火墙sudo ufw disable或放行端口sudo ufw allow 7681。3. libwebsockets测试服务器默认监听所有接口(0.0.0.0)一般不是此问题。可在本机用curl http://localhost:7681测试。客户端连接服务器失败提示“Connection refused”1. 服务器程序没有运行。2. 端口号错误。3. 网络不通跨设备时。1. 检查服务器进程是否在运行 ps aux客户端连接失败提示SSL相关错误1. 服务器以非SSL模式运行客户端却尝试SSL连接或反之。2. 证书问题。1. 确保两端模式一致。测试服务器默认非SSL。客户端不加--ssl参数。2. 对于自签名证书测试客户端可能需要添加-k或--no-validate参数来跳过证书验证。跨设备主机-开发板测试时开发板客户端无法连接1. 虚拟机网络模式不是桥接。2. 主机防火墙阻止了来自局域网的连接。3. 开发板与主机不在同一网段。1. 将虚拟机网络设置为“桥接模式”。2. 在主机的防火墙规则中允许7681端口的入站连接来源为局域网。3. 分别检查主机和开发板的IP地址和子网掩码确保它们在同一个子网内如都是192.168.2.x。一个我踩过的具体案例有一次在全新安装的Ubuntu虚拟机上编译make一切顺利但运行测试服务器时立刻核心转储Core Dump。经过排查发现是因为默认的编译优化级别较高-O2而虚拟机分配的CPU核心数较少某个并行编译的环节出现了极罕见的竞态条件。解决方案是在CMake时添加-DCMAKE_BUILD_TYPEDebug参数以调试模式编译问题就消失了。这提醒我们如果遇到非常诡异的运行时崩溃切换编译类型Debug/Release是一个有效的排查手段。8. 集成到自有项目与编译选项探讨当你完成了库的编译和基础测试接下来就要思考如何将它用到自己的C/C项目中了。这里主要涉及头文件包含、库文件链接以及CMake集成。手动链接适用于简单项目假设你的项目目录结构如下my_project/ ├── src/ │ └── main.c ├── libwebsockets_install/ (这是你之前编译的install目录的拷贝) │ ├── include/ │ ├── lib/ │ └── bin/ └── Makefile在你的main.c中需要包含libwebsockets的头文件#include libwebsockets.h在编译你的程序时需要指定头文件路径和链接库gcc -o my_app src/main.c -I./libwebsockets_install/include -L./libwebsockets_install/lib -lwebsockets -lssl -lcrypto -lz参数解释-I./libwebsockets_install/include告诉编译器在哪里查找libwebsockets.h。-L./libwebsockets_install/lib告诉链接器在哪里查找libwebsockets.so或libwebsockets.a。-lwebsockets链接libwebsockets动态库。-lssl -lcrypto链接OpenSSL库如果编译时开启了SSL。-lz链接压缩库。使用CMake集成推荐尤其对于复杂项目如果你的项目使用CMake集成会优雅得多。可以将libwebsockets的安装路径作为依赖引入。在你的项目CMakeLists.txt中添加# 设置libwebsockets的安装路径 set(LWS_DIR /path/to/your/libwebsockets_install/lib/cmake/libwebsockets) # 查找libwebsockets包 find_package(Libwebsockets REQUIRED HINTS ${LWS_DIR}) # 将你的目标程序与libwebsockets链接 target_include_directories(my_app PRIVATE ${LIBWEBSOCKETS_INCLUDE_DIRS}) target_link_libraries(my_app PRIVATE ${LIBWEBSOCKETS_LIBRARIES})这种方式能自动处理所有的依赖传递包括OpenSSL和zlib。关键编译选项解析在最初运行CMake时我们只用了最基础的选项。libwebsockets提供了大量选项来裁剪功能以适应不同的应用场景。了解它们可以在资源受限的嵌入式环境中有效减小库的体积-DLWS_WITH_SSLON/OFF最重要的选项。开启SSL支持会增加库大小和依赖。如果设备仅用于内网不加密通信可以关闭。-DLWS_WITHOUT_TESTAPPSON发布时建议开启。这会排除所有测试程序的编译显著减少安装包大小。-DLWS_WITHOUT_EXTENSIONSON关闭WebSocket扩展如permessage-deflate压缩。可以减小体积但可能影响与某些浏览器的兼容性。-DLWS_WITHOUT_SERVERON/-DLWS_WITHOUT_CLIENTON如果你的设备只做客户端或只做服务器可以关闭另一半功能来精简。-DLWS_MAX_SMP1如果你明确知道应用程序只会单线程运行可以将其设为1移除一些线程同步代码。-DLWS_WITH_MINIMAL_EXAMPLESON开启此选项会编译一些极简示例对于学习库的API使用非常有帮助。我的建议是在x86主机上开发调试时使用功能完整的默认配置。当需要为嵌入式设备进行最终发布版的交叉编译时再根据设备的实际角色和资源情况仔细斟酌并裁剪这些选项生成一个最精简的库。你可以通过多次编译对比install/lib目录下库文件的大小来直观感受不同选项带来的影响。这个在主机上摸索、验证再到目标板定型的流程正是“主机开发调试目标板部署运行”模式的优势所在。
相关文章
避坑指南：STM32CubeMX生成SSD1306 DMA驱动代码，SysTick中断记得手动加！
STM32CubeMX实战避坑：SSD1306 DMA驱动中SysTick中断的隐秘陷阱 当你信心满满地用STM32CubeMX配置好I2C/SPI接口，导入精心挑选的开源SSD1306驱动库，烧录程序后却发现OLED屏幕永远定格在初始画面——这种挫败感恐怕每个STM32开发者都经历过。本…
拆解一个LDO芯片的内部“黑盒”：从分压电阻R1/R2到运放，手把手画图理解它的稳压闭环
拆解LDO芯片的稳压闭环：从分压电阻到运放的工程实践 LDO（低压差线性稳压器）是电子设计中不可或缺的电源管理元件，但大多数工程师仅停留在"知其然"的层面。本文将带您深入芯片内部，通过可视化拆解和数学推导&…
告别MRT拼接缝隙：实测对比MCTK 2.0.0在MODIS条带与网格产品投影上的优势与实战
MCTK 2.0.0实战：如何彻底解决MODIS数据处理中的拼接缝隙问题 在遥感数据处理领域，MODIS（中分辨率成像光谱仪）数据因其全球覆盖、高时间分辨率和多光谱特性，成为环境监测、气候变化研究等领域的重要数据源。然而&#x…
从‘混乱与扩散’到一行代码：用Python和cryptography库快速上手AES/CBC加密
从理论到实践：用Python cryptography库实现AES/CBC加密的完整指南 密码学初学者常面临一个困境：理解了AES加密的基本原理，却不知如何将其转化为可运行的代码。本文将手把手带你用Python的cryptography库，实现一个完整的AES-CBC加密…
力扣17，电话号码的字母组合
class Solution { public: //设置一个map，用来数字与字母比对unordered_map<char, string> _mp{{2,"abc"},{3,"def"},{4,"ghi"},{5,"jkl"},{6,"mno"},{7,"pqrs"},{8,"tuv"},{9,"…
你的旧安卓手机别扔！用Termux改造成随身Kali渗透测试仪（含VNC远程桌面）
旧安卓手机变身便携式安全实验室：TermuxKali全攻略 每次换新手机后，抽屉里总会多出一台积灰的旧设备。与其让这些性能尚可的硬件沦为电子垃圾，不如将它们改造成随身携带的网络安全实验平台。本文将详细介绍如何通过Termux在非Root安卓设备上部…
curatedMetagenomicData深度解析：人类微生物组标准化数据分析实战指南
curatedMetagenomicData深度解析：人类微生物组标准化数据分析实战指南 【免费下载链接】curatedMetagenomicData Curated Metagenomic Data of the Human Microbiome 项目地址: https://gitcode.com/gh_mirrors/cu/curatedMetagenomicData curatedMetagenomi…
从放大镜到光盘：揭秘身边光学仪器的原理与应用
1. 项目概述：重新认识身边的“光学仪器” 提起光学仪器，很多人脑海里浮现的可能是实验室里昂贵精密的显微镜、天文台上巨大的望远镜，或者是医院里复杂的检查设备。这些“高大上”的设备固然是光学技术的结晶，但它们似乎离我们的日…
MPC-BE：Windows平台终极开源多媒体播放器架构深度解析与实战指南
MPC-BE：Windows平台终极开源多媒体播放器架构深度解析与实战指南 【免费下载链接】MPC-BE MPC-BE – универсальный проигрыватель аудио и видеофайлов для операционной системы Windows. 项…
5分钟快速上手：biliTickerBuy开源工具助你轻松抢购B站会员购热门票务
5分钟快速上手：biliTickerBuy开源工具助你轻松抢购B站会员购热门票务 【免费下载链接】biliTickerBuy b站会员购购票辅助工具 项目地址: https://gitcode.com/GitHub_Trending/bi/biliTickerBuy biliTickerBuy是一款专为B站会员购平台设计的开源辅助工具&…
一口气讲清楚 Monorepo、Turborepo、pnpm、Changesets 到底是什么？
你肯定遇到过这种情况：项目里同时有前端、后端、公共组件，放在一个仓库嫌乱，拆成多个仓库又改一个公共函数要在五个项目里各改一遍。于是出现了 Monorepo、Turborepo、pnpm、Changesets 这四个词。它们不是互相替代，而是分别解决工…
从ok-skills项目解析技能树：设计理念、技术实现与工程实践
1. 项目概述与核心价值最近在GitHub上看到一个挺有意思的项目，叫“ok-skills”。光看这个名字，可能有点摸不着头脑，但点进去一看，发现这是一个关于“技能树”或“知识图谱”的开源项目。简单来说，它试图用一种结构化的…
【实用小程序】超轻量级文件上传下载中心 (File Download Server)
站内源码及jar包下载 一、项目概述 文件下载中心一个基于 Java 内置 HTTP 服务器（com.sun.net.httpserver）构建的轻量级文件管理服务。它零第三方依赖，单 JAR 包即可运行，适合在内网环境或临时场景中快速搭建文件共享站点。 你的团队需要临时共享一批日志文件或交付物，…
py每日spider案例之某website之xin东方选课搜索接口(难度一般 扣取代码即可)
加密位置: 逆向接口参数: 逆向接口: const g = globalThis; g.window = g; g.self = g; g.location = {<
终极轻量级Android文本编辑器Markor：多格式笔记应用完全指南
终极轻量级Android文本编辑器Markor：多格式笔记应用完全指南 【免费下载链接】markor Text editor - Notes & ToDo (for Android) - Markdown, todo.txt, plaintext, math, .. 项目地址: https://gitcode.com/gh_mirrors/ma/markor 在移动设备上寻找一款…
MPC-BE：基于DirectShow架构的专业级开源媒体播放解决方案
MPC-BE：基于DirectShow架构的专业级开源媒体播放解决方案 【免费下载链接】MPC-BE MPC-BE – универсальный проигрыватель аудио и видеофайлов для операционной системы Windows. 项目地址:…
如何快速计算3D模型体积和重量：STL-Volume-Model-Calculator终极指南
如何快速计算3D模型体积和重量：STL-Volume-Model-Calculator终极指南 【免费下载链接】STL-Volume-Model-Calculator STL Volume Model Calculator Python 项目地址: https://gitcode.com/gh_mirrors/st/STL-Volume-Model-Calculator 你是否曾经为3D打印项目…
通过Taotoken CLI工具一键配置团队开发环境与模型密钥
通过Taotoken CLI工具一键配置团队开发环境与模型密钥 1. CLI工具安装与基本使用 Taotoken提供的CLI工具可通过npm全局安装或直接使用npx运行。对于需要频繁使用CLI的团队，推荐全局安装： npm install -g taotoken/taotoken对于临时使用或项目级配置&a…