做控制、做机器人、做运筹优化的人早晚要跟二次规划QP打交道。OSQPOperator Splitting QP是这一卦里口碑不错的开源求解器——用ADMM迭代解稀疏二次规划对大规模、结构稀疏的问题内存占用低、速度可观MPC模型预测控制场景里尤其常见很多论文和开源项目拿它当默认的QP求解器。问题是你从仓库拉下来的是源码官方并不直接给Windows下的二进制包。在Linux上还好一条build命令一步到位到了Windows Visual Studio 2019这个组合非得自己用CMake过一遍生成工程、选配置、编译出库再接进自己的C/C项目里调用。这篇就是把这一整套流程串起来CMake怎么生成VS2019工程、怎么编出静态库、C/C侧怎么链接、怎么写第一个求解程序以及我在实际工程里踩过的几个坑。1. 为什么要在VS2019下自己编译OSQP1.1 OSQP是谁解决什么问题二次规划的标准形式长这样minimize 1/2 xᵀP x qᵀx subject to l ≤ Ax ≤ u其中P是目标函数二次项的系数矩阵要求半正定q是一次项系数A是线性约束矩阵l和u是约束的上下界。等式约束就是把l和u设成同一个值。大量工程问题最后都能落到这个形式最小二乘回归加约束、投资组合优化、支持向量机的对偶问题、模型预测控制MPC里的滚动优化等等。OSQP的做法是把原问题拆成两个更简单的子问题来回迭代算法叫ADMM交替方向乘子法。它不需要对P做复杂的矩阵分解不要求P严格正定半正定就够用而且能主动检测原问题不可行primal infeasible和对偶不可行dual infeasible。对中等规模、稀疏的问题它比很多通用内点法求解器更省内存还能通过设置最大迭代次数来硬性控制求解耗时——这一点对实时控制特别重要。1.2 拿来主义行不通的几个理由你可能觉得开源库嘛网上找个编译好的包装上不就完了我帮你把常见的几条路都试过vcpkg一条命令vcpkg install osqp:x64-windows确实能装上但版本相对滞后而且它把CMake配置写死在了一套默认参数里你想换浮点类型、想开Intel MKL的PARDISO后端、想改编译器的运行时库vcpkg的口子很难撬开。condaPython侧很舒服conda install osqp装完import osqp就能用。但C/C侧要的头文件和.lib文件藏在conda的pkgs目录里找起来费劲而且混用不同来源编译的CRT runtime迟早出事。官方releaseGitHub的release页面给的是源码包没有现成的Windows二进制。所以自己编译不是折腾而是用OSQP做C/C工程的基本功。一旦编过一次后面想给OSQP加打印、加计时、改迭代策略改完重新编也就是几分钟的事。1.3 这一趟要完成的四件事本文按实际操作的顺序分四步准备好工具链和源码、用CMake生成VS2019工程并编译出库、把库接进自己的C/C工程、写一个能验算的求解Demo。最后再讲几个真正干活时才会碰到的进阶问题。第一次走通整个过程预留一个小时比较从容之后每次换版本编译就是复制粘贴三条命令的事。2. 编译前的工具链与源码准备2.1 VS2019与CMake版本检查先把底子打好。我默认你已经在用Visual Studio 2019做C/C开发但有几个关键点需要确认VS2019的安装组件打开Visual Studio Installer确认安装了使用C的桌面开发工作负载里面包含MSVC v142编译器工具集和Windows 10 SDK。只装了C#或者只装了Python组件的VS2019是编不了C的。CMake版本OSQP的CMakeLists要求最低3.10我建议用3.15以上后面设置MSVC运行时库选项时会用到新特性。在命令行里敲cmake --version确认一下。Git有最好没有的话直接下载源码zip包也没问题。确认完毕后在开始菜单里打开x64 Native Tools Command Prompt for VS 2019。注意是x64开头的那个不是x86的。这个终端会把MSVC编译器、Windows SDK和CMake的路径都配好后面编译省很多事。2.2 拉取源码与版本选择源码从官方GitHub仓库拉我建议拉带版本号的稳定tag而不是master分支毕竟master可能处于开发状态git clone --depth 1 --branch v0.6.3 https://github.com/osqp/osqp.git--depth 1只拉最新一版历史省时间省磁盘。v0.6.3这个版本我在多个项目里用过稳如果你手头项目需要某个新特性也可以直接clone master分支编译流程完全一样。如果没有Git就在仓库页面选对应tag下载zip包解压效果相同。2.3 目录结构与关键文件源码解压后长这样osqp/ ├── include/ # 公共头文件核心是 osqp.h ├── src/ # 求解器实现代码 ├── cmake/ # CMake辅助模块 ├── tests/ # 单元测试 ├── examples/ # C语言示例 ├── CMakeLists.txt └── README.md重点记两个地方include/osqp.h是唯一的公共头文件所有API声明、数据结构定义都在里面后续你的工程只要包含这一个目录就行examples/里有现成的求解示例第一次接触API时是最好的参考读物。tests/需要额外拉Catch2依赖日常编译建议关掉后面会说怎么关。3. CMake生成工程与编译全过程3.1 生成VS2019解决方案在源码根目录下新建一个build目录把CMake的中间产物和最终库文件都隔离在里面这样源码目录保持干净想换配置删掉build重建就行cd osqp mkdir build cd build cmake .. -G Visual Studio 16 2019 -A x64这行命令干了两件事-G Visual Studio 16 2019告诉CMake生成VS2019格式的解决方案不是Makefile-A x64指定目标平台是64位。然后编译Release版本cmake --build . --config ReleaseVS2019的生成器是多配置生成器multi-config编译时用--config Release显式指定配置。这点和Linux下完全不同——Linux下用-DCMAKE_BUILD_TYPERelease在配置阶段就定死了Windows下配置阶段的CMAKE_BUILD_TYPE是不生效的必须在构建阶段选。如果直接双击生成的osqp.sln在IDE里编译也要记得把顶部的配置从Debug切到Release。3.2 常用的CMake开关OSQP的CMake配置有几个开关值得提前了解我用得最多的是这组参数cmake .. -G Visual Studio 16 2019 -A x64 ^ -DBUILD_SHARED_LIBSOFF ^ -DOSQP_EXAMPLESOFF ^ -DOSQP_TESTINGOFF选项默认值作用BUILD_SHARED_LIBSOFF关掉生成静态库打开则生成osqp.dll动态库ENABLE_OPENMPOFF开启后利用OpenMP并行加速需VS支持ENABLE_MKL_PARDISOOFF用Intel MKL的PARDISO做后端线性求解器需额外装MKLOSQP_EXAMPLESON编译examples示例不需要可以关OSQP_TESTINGON编译单元测试依赖Catch2日常强烈建议关掉大部分场景用BUILD_SHARED_LIBSOFF的静态库就够了部署时不需要带dll。如果追求极致性能且机器上有Intel MKL可以研究ENABLE_MKL_PARDISO它对病态问题有明显加速但前提是你能接受MKL的依赖体积。3.3 编译产物在哪里编译完成后产物默认输出在build/out目录下。VS多配置构建有时会再按Release/Debug分一层子目录不同版本行为略有差异找不到的话在build目录下直接搜索*.lib最靠谱。静态库模式下你最终会得到文件说明osqp.libRelease版静态库osqpd.libDebug版静态库多了一个d后缀OSQPConfig.cmakeCMake包配置文件后续find_package要用动态库模式下则多出osqp.dll、osqp.exp和导入库osqp.lib。我一般只用静态库省去dll拷贝环节。3.4 初次编译最容易翻车的三个点说几个我亲眼见过、自己也踩过的坑第一忘记-A x64。生成器默认平台有时候是Win32编出来一个32位库你外面64位的工程一链接报LNK1112计算机类型冲突查半天才反应过来是架构不匹配。这属于最冤的一类错误所以每次敲cmake命令都养成检查-A x64的习惯。第二开关开太多。OSQP_TESTING默认是开的它会尝试去拉Catch2依赖国内网络环境下经常卡住。只要不是想跑官方测试尽量关掉。第三在普通cmd里跑cmake。如果MSVC环境变量没配好cmake生成工程时可能找不到编译器报CMAKE_C_COMPILER not set。用VS自带的x64 Native Tools Command Prompt就完全没有这个问题。当然如果你在CMake GUI里选对了编译器路径普通终端也没事但我懒得折腾。4. 在自己的C/C工程里接入OSQP4.1 方案AVS属性页直接配置如果你是在VS2019里建了一个普通控制台工程不想动CMake那就用属性页配置。在解决方案资源管理器里右键项目 → 属性依次设置C/C → 常规 → 附加包含目录加上D:\dev\libs\osqp\include换成你的实际路径链接器 → 常规 → 附加库目录加上D:\dev\libs\osqp\build\out\Release链接器 → 输入 → 附加依赖项填osqp.lib然后在代码里直接#include osqp.h就能用。如果你写的是.cpp文件也不用担心C/C混链的问题——OSQP的osqp.h内部已经用extern C包好了C工程直接调用。4.2 方案BCMake的find_package如果你的工程本身就是CMake管理的用find_package更优雅。这里我踩过一个小坑不同版本OSQP导出的CMake目标名不完全一致有的版本叫osqp有的版本叫OSQP::osqp。最稳妥的办法是打开build/out/OSQPConfig.cmake看一眼里面定义了哪个目标。大多数情况下这样写没什么问题cmake_minimum_required(VERSION 3.15) project(osqp_demo C CXX) find_package(OSQP REQUIRED) add_executable(osqp_demo main.cpp) target_link_libraries(osqp_demo PRIVATE osqp)配置时指定OSQP包的位置cmake .. -Dosqp_DIRD:/dev/libs/osqp/build/outosqp_DIR指向包含OSQPConfig.cmake的目录。find_package找到后会自动带上头文件路径和库路径比手工配置省心得多。4.3 运行库匹配是链接成败的生死线这是Windows下链接静态库最经典也最恶心的坑——MSVC运行库设置必须一致。MSVC的C/C运行库有四种模式/MT静态多线程、/MTd静态多线程调试、/MD动态多线程、/MDd动态多线程调试。VS2019里Release默认是/MDDebug默认是/MDd。如果OSQP是用/MD编出来的你的工程却用了/MT链接时就会报LNK2038RuntimeLibrary不匹配。解法有两个改你的工程把运行库调成和OSQP一致的/MDRelease或/MDdDebug。重新编OSQP在cmake配置时加-DCMAKE_MSVC_RUNTIME_LIBRARYMultiThreaded对应/MT或MultiThreadedDLL对应/MD。我的建议是如果OSQP不是性能瓶颈就让它和你的主工程统一成/MD如果OSQP要做极致性能优化想用/MT那就提前把所有依赖库全部用/MT编一遍。混合CRT在简单场景下可能跑得欢一旦涉及跨模块malloc/free或异常处理崩溃随机出现非常难查。5. 写一个能验算的QP求解Demo5.1 问题设计一眼能看懂解先选一道不需要计算器就能验算的题minimize 1/2(x₁² x₂²) subject to x₁ x₂ 1用拉格朗日乘子法手算目标函数对x₁和x₂求导等于零得到x₁ λ、x₂ λ代入等式约束得2λ 1所以x₁ x₂ 0.5最优目标值0.25。这个结果干净利落正好用来验证OSQP有没有算对。对应标准形式P是2×2单位阵q是零向量A是[1, 1]l和u都等于1等式约束。5.2 CSC矩阵存储把稀疏结构写对OSQP使用的矩阵存储格式是CSC压缩列存储理解它是一切的基础。CSC由三个数组组成p列指针数组长度n1。第j列的元素在后续数组中的范围是p[j]到p[j1]-1。i行号数组长度nnz记录每个非零元素所在的行。x数值数组长度nnz按列存放非零元素。关键点P矩阵只存上三角部分。OSQP假设P是对称矩阵只读上三角你如果把下三角也塞进去它要么报错要么算错这是新手最容易踩的。对单位阵P2×2第0列只有一个非零元位于行0所以i[0]0, x[0]1第1列只有一个非零元位于行1所以i[1]1, x[1]1列指针p[0]0, p[1]1, p[2]2对A[1, 1]一行两列第0列非零元在行0i[0]0, x[0]1第1列非零元在行0i[1]0, x[1]1列指针p[0]0, p[1]1, p[2]2注意A两列的行号都是0因为约束矩阵只有一行。5.3 完整求解代码与输出完整代码贴在下面我直接在注释里标注了每一步的作用#include stdio.h #include osqp.h int main(void) { c_int n 2; /* 变量个数 */ c_int m 1; /* 约束个数 */ /* P I (上三角CSC存储) */ c_float P_x[2] {1.0, 1.0}; /* 非零数值 */ c_int P_i[2] {0, 1}; /* 行号 */ c_int P_p[3] {0, 1, 2}; /* 列指针 */ /* A [1, 1] */ c_float A_x[2] {1.0, 1.0}; c_int A_i[2] {0, 0}; c_int A_p[3] {0, 1, 2}; /* 组装csc结构体 */ csc P; P.nzmax 2; P.m n; P.n n; P.p P_p; P.i P_i; P.x P_x; csc A; A.nzmax 2; A.m m; A.n n; A.p A_p; A.i A_i; A.x A_x; /* 目标一次项和约束边界 */ c_float q[2] {0.0, 0.0}; c_float l[1] {1.0}; c_float u[1] {1.0}; /* 组装OSQP数据 */ OSQPData data; data.n n; data.m m; data.P P; data.q q; data.A A; data.l l; data.u u; /* 默认设置只把打印打开 */ OSQPSettings settings; osqp_set_default_settings(settings); settings.verbose 1; /* 建模并求解 */ OSQPWorkspace *work NULL; c_int ret osqp_setup(work, data, settings); if (ret ! 0) { fprintf(stderr, osqp_setup failed, code %d\n, (int)ret); return 1; } osqp_solve(work); /* 结果输出 */ if (work-info-status_val OSQP_SOLVED) { printf(status: %s\n, work-info-status); printf(x [%.6f, %.6f]\n, work-solution-x[0], work-solution-x[1]); printf(objective %.6f\n, work-info-obj_val); } else { printf(not solved: %s\n, work-info-status); } osqp_cleanup(work); return 0; }编译链接跑起来输出末尾应该能看到status: solved x [0.500000, 0.500000] objective 0.250000和手算结果完全一致。第一次跑通这个Demo后续换自己的问题就只是换P、q、A、l、u的问题。5.4 状态码与失败排查求解完成后work-info-status会给出字符串状态work-info-status_val给出对应的数值需要关注这几种status_val含义应对OSQP_SOLVED (1)收敛到最优解直接用结果OSQP_SOLVED_INACCURATE (2)解出来了但不满足精度收紧eps或打开polishOSQP_PRIMAL_INFEASIBLE (3)原问题无可行解检查约束是否矛盾OSQP_DUAL_INFEASIBLE (4)对偶不可行原问题无界或松弛检查P是否半正定OSQP_MAX_ITER_REACHED (-2)迭代次数用尽增大max_iter、调rho我在一开始就栽过明明数学上无解却期待有解的坑——约束条件本身矛盾时OSQP会诚实地报PRIMAL_INFEASIBLE。遇到这种情况先回头检查l和u有没有设反A的行号列号有没有对应错多半是建模问题。6. 工程化使用中常见的进阶问题6.1 矩阵构造比求解更贵很多人以为用OSQP的瓶颈在求解器本身用多了才发现把业务数据转换成CSC格式的过程往往才是耗时大户。尤其做MPC这类滚动优化每步都要构造一次P和A如果每次都用malloc重新分配再逐个填非零元光矩阵组装就能吃掉大半预算。我的做法是确定问题规模后一次性分配好CSC三个数组的最大空间后续每步只更新数值数组x行号i和列指针p基本不变除非约束结构动态变化。配合OSQP提供的更新接口能省掉整个osqp_setup的开销osqp_update_lin_cost(work, q_new)只更新目标一次项osqp_update_bounds(work, l_new, u_new)只更新约束边界osqp_update_A(work, A_new_x, OSQP_NULL, 0)只更新A的数值osqp_update_P(work, P_new_x, OSQP_NULL, 0)只更新P的数值这些接口比每次重建workspace快一个量级是我实际优化效果最明显的一处。6.2 设置项调参与warm startOSQP默认设置对大多数问题够用但碰到收敛慢或精度不足的情况重点看这几个参数参数默认值说明rho0.1ADMM步长直接影响收敛速度sigma1e-6增广拉格朗日正则项alpha1.6松弛因子max_iter4000最大迭代次数eps_abs1e-3绝对终止容差eps_rel1e-3相对终止容差polish0是否在迭代后做抛光能显著提升精度实践经验如果追求高精度解把polish设为1通常比单纯把eps_abs、eps_rel调到1e-6更划算抛光是额外解一次KKT系统小规模问题开销不大。如果发现到了max_iter还没收敛先别急着加大迭代次数试着手动把rho调大或调小一个数量级经常立竿见影。warm start是MPC场景的杀手锏。OSQP的workspace可以在一次求解后直接复用把上一时刻的解作为当前时刻的初值迭代起点离最优解很近收敛极快。我实际测试过MPC滚动优化里启用warm start后单步求解耗时能降一半以上。这是OSQP这类ADMM求解器相对内点法的最大优势之一。6.3 多实例、线程与内存边界OSQP的workspace不是线程安全的同一个workspace不能同时被两个线程调用来求解否则迭代数据互相污染结果一塌糊涂。但不同线程各自独立创建独立的workspace来求解是没问题的因为OSQP本身没有全局状态。内存方面有一个容易误解的点osqp_setup内部会把问题数据复制进workspace所以setup之后你原来那个csc数组理论上可以释放。但我个人的习惯是让数据数组的生命周期覆盖到solve结束——少写一个free多一份安心尤其是在团队维护的项目里别人不一定清楚这个拷贝语义。记得善用osqp_cleanup释放workspace只调osqp_solve不调osqp_cleanup的话内存泄漏会随时间累积长驻服务上特别明显。6.4 从C到其他语言的扩展路径OSQP编出来的库不只服务C/C。我见过有人把编译好的osqp.dll用ctypes在Python里直接调绕开Python包装层的开销也有人通过C接口把OSQP嵌进实时控制器的C代码里配合共享内存和外部仿真环境做闭环。如果后续要接入Eigen这类矩阵库可以借助Eigen的SparseMatrix直接把innerIndexPtr()、outerIndexPtr()和valuePtr()指针喂给OSQP的csc结构体零拷贝转换非常干净。将来要是换了VS2022CMake的generator字符串改成Visual Studio 17 2022其余流程一字不改。我在实际项目里用OSQP做过一个带约束的轨迹规划Demo最开始每次求解都重建矩阵、重建workspace单步要七八毫秒后来改成warm start加只更新q和边界直接降到一两毫秒。如果你也是拿它跑MPC这类滚动优化这条经验比任何编译技巧都值钱。编译那点事跟着这篇踩一遍之后换版本、换平台基本就是复制粘贴命令的问题了。