竞赛指南: ncnn 贡献路径

检测模型部署见 跨赛道: YOLO 到 端侧 ncnn 架构精读见 精读: ncnn MNN 架构对照见 MNN 与 ncnn 对照

调研元信息

一句话定位

ncnn 是腾讯开源的极简端侧推理引擎（23K+ star），犀牛鸟备赛需理解其贡献生态——无 good-first-issue、强个人维护者模式、C++ 为主但 Python/PNNX/docs 可切入。

日常类比

想象一个手工匠人的作坊：工具极精良（elempack、Vulkan）、但师傅（nihui）只收「能看懂图纸、不改规矩」的学徒。你不必一开始就打铁（C++ 算子），可以先写使用手册（docs）、做翻译（Python bindings），让师傅看到你靠谱。

贡献环境准备

Mac 本地编译

# 前置：Xcode Command Line Tools + CMake
brew install cmake

git clone https://github.com/Tencent/ncnn.git
cd ncnn && git submodule update --init
mkdir build && cd build

# 基础构建（不含 Vulkan）
cmake -DNCNN_PYTHON=ON -DNCNN_BUILD_EXAMPLES=ON ..
make -j$(sysctl -n hw.ncpu)

# 验证
./benchncnn 4 1 0 0 0  # 跑 benchmark

Android/iOS 交叉编译（文档参考）

Android 需 NDK r21+，使用 android.toolchain.cmake；iOS 使用 ios.toolchain.cmake，指定 IOS_PLATFORM=OS64。

Python 包

pip install ncnn  # 预编译轮子，仅 Linux/macOS x86_64
# Apple Silicon 需源码编译 python/ 目录

贡献路径分级

graph TD
    A[新人入口] --> B{技术偏好?}
    B -->|Python| C[Python bindings<br/>难度: 低]
    B -->|工具链| D[PNNX 算子支持<br/>难度: 中]
    B -->|文档| E[docs 中英文<br/>难度: 低]
    B -->|C++| F[Layer 算子<br/>难度: 高]
    B -->|GPU| G[Vulkan GLSL<br/>难度: 极高]
    C --> H[nihui review]
    D --> H
    E --> H
    F --> H
    G --> H
    H --> I{通过?}
    I -->|是| J[成为 Contributor]
    I -->|否| K[根据反馈迭代]
    K --> H

路径详解

贡献流程与硬性要求

来自 docs/developer-guide/how-to-be-a-contributor.zh.md [文档]：

1. 分支模型：Fork，git remote add tencent，基于 tencent/master 建功能分支，一个分支只做一件事
2. 代码规范：不使用 C++11 特性（src/ 下避免 template）；Tab 转 4 空格；if-else 后左花括号换行
3. PR 要求：标题英文、含实现概述 + 测试结果、CI 全绿
4. CLA 签署：首次 PR 需签署 Tencent CLA
5. 格式化：CI 集成 restyled-io，自动提 formatting PR 需 merge

与 MNN 互补叙事

为什么学 MNN 的人也能做 ncnn 贡献：

• MNN Geometry Compiler 帮你理解「内存布局抽象」，ncnn elempack 是同一问题域的不同解法
• MNN 的 Op-Execution 分离思想对应 ncnn Layer 的 forward_inplace vs forward 设计
• 你在 MNN 学到的转换流程（MNNConvert）直接映射到 ncnn 的 PNNX/onnx2ncnn
• 结论：用 MNN 深度理解推理引擎原理，用 ncnn Python/PNNX/docs 低门槛产出贡献

GitHub Issue 候选分析

ncnn 有约 30 open issues，无 good-first-issue 标签。以下按可切入性筛选 [Issue]：

从用户问题反推文档 PR 策略

ncnn Issues 中大量是用户求助（转换失败、速度异常）。策略：

1. 复现用户问题
2. 找到根因 / workaround
3. 写入 docs/faq.md 或 docs/developer-guide/
4. PR 文档修复

这是最低风险、最高被合并概率的贡献路径。

第一周行动计划

环境矩阵

已知风险与边界

读完你应能

• 在 Mac 上完成 ncnn 编译并跑通 benchncnn
• 说出 ncnn 的四种贡献路径（Python bindings / PNNX 算子 / 文档 / C++ Layer）及各自门槛
• 解释 elempack 的含义及其对 Layer 实现的影响
• 描述 ncnn 的 PR 流程特点（nihui 个人 review、CI 严格、代码风格约束）
• 写出从用户 issue 反推文档 PR 的策略（至少举一个具体例子）

贡献者成长路径

graph LR
    subgraph 第1月
        A1[编译环境] --> A2[读文档]
        A2 --> A3[复现 Issue]
        A3 --> A4[文档 PR]
    end
    subgraph 第2月
        B1[Python binding 功能] --> B2[PNNX 新算子]
    end
    subgraph 第3月以上
        C1[C++ Layer 优化] --> C2[Vulkan shader]
    end
    A4 --> B1
    B2 --> C1

证据等级