Speed

SURF algorithm’s target is speeding up SIFT via 4 methods

• METHOD1 : Use Integral-Image(积分图像) replace DoG
• METHOD2 : Use box filter replace resize layer in octave
• METHOD3 : Use Haar-Wavelet replace histogram during orientation block
• METHOD4 : Reduce descriptor dimension, using flag to give up rotation invariance

Source Code

here we can get more information from source code

https://github.com/opencv/opencv_contrib/blob/master/modules/xfeatures2d/src/surf.cpp

Essential

Here we pickup some essential verbose of the official document

• Essential 1:

  “ “SURF: Speeded Up Robust Features” introduced a new algorithm called SURF. As name suggests, it is a speeded-up version of SIFT.”

• Essential 2:

  “In SIFT, Lowe approximated Laplacian of Gaussian with Difference of Gaussian for finding scale-space. SURF goes a little further and approximates LoG with Box Filter”

• Essential 3:

  “For many applications, rotation invariance is not required, so no need of finding this orientation, which will speed up the process.”

Then compare SURF with SIFT step by step

1. Prepare images & search extrema

1-1. Prepare Integral-Image

• Source Code Hint: SURF_Impl::detectAndCompute()

Compare With SIFT:

same:

None, SIFT does not contain this step

differ:

SIFT will first resize the input image to multiples, then apply gauss blur

SURF use “integral(img, sum, CV_32S);” at line 938 get Integral-Image at first, then use fastHessianDetector() create Prymaids & Octaves

1-2. Fill up Prymaids & Octaves

• Source Code Hint: fastHessianDetector() & calcLayerDetAndTrace()

Compare With SIFT:

• same:

turn single input image to Prymaids count * Octaves count images

• differ:

In SIFT the size of different octaves not equal

In SURF the size of each images equals to original image size

SIFT use gauss blur (differnet sigma) & substract to get DoG

SURF use Hessian Matrix (differnet step) as kernel do convolution

• Speed Up Reason: (METHOD1 METHOD2)

Hessian Matrix computer is faster than gauss blur during convolute
caused by the help of Integral-Image

1-3. Find extrema point

• Source Code Hint: SURFFindInvoker::findMaximaInLayer()

Compare With SIFT:

almost same, use 26 pixels around in space

2. Keypoint Localization

2-1. Non-maxima suppression

• Source Code Hint: SURFFindInvoker::findMaximaInLayer() - Line417

Compare With SIFT:

• same:

just like the SIFT refines the potential points to keypoint

• differ:

SIFT need to flatten the keypoints to origin coordinate

SURF did not resize the images, alternate with different step box filter, no need the flatten step

3. Orientation Assignment

3-1. Statistics wavelet value in 6 area of 360 degree

• Source Code Hint: SURFInvoker() + ORI_RADIUS

Compare With SIFT:

• same:

this step aims for making sure the orientation

• differ:

SIFT use histogram with 36bins

SURF use the sum of wavelet value of area

SIFT has a main orientation and multiple associate orientations with 80% threshold

SURF just precision in a radius area with max sum value in 6bins

SURF can use upright flag for giving up this step

• Speed Up Reason: (METHOD3)

addition runs faster than histogram compare, flag can skip this step

4. Keypoint Descriptor

4-1. Neighborhood pixels & Rotate

• Source Code Hint: SURFInvoker()-operator()-PATCH_SZ

Compare With SIFT:

• same:

select an area around the keypoint, then divide to block

• differ:

SIFT select fix area by pixel size 16 * 16 , block size is 4 * 4

SURF use dynamic area by window via “int win_size = (int)((PATCH_SZ+1)*s);”, then divide the window area to 4 * 4 = 16 sub-region (same as block), not depend on the pixels number

4-2. Represent sub-region with 4 length vector

• Source Code Hint: SURFInvoker()-operator()-Line780

Compare With SIFT:

• same:

each block/sub-region has own vector

• differ:

SIFT use a small histogram with 8bins representing block

SURF use a sub region accumulate v=(∑dx,∑dy,∑|dx|,∑|dy|)

SURF can use flag extend the vector size to 8, by divide the dx and |dx| in dy<0 and dy≥0

4-3. Assembly to descriptor

• Source Code Hint: SURFInvoker()-operator()-Line850

Compare With SIFT:

• same:

descriptor consist of block/sub-region vector

• differ:

SIFT descriptor size is fix 16 sub 4*4 block * 8bins = 128

SURF can use flag switch between 16 sub-region * 4 vector = 64 and 16 sub-region * 8 vector divide by zero = 128

• Speed Up Reason: (METHOD4)

addition of intergal-image value run faster

Refer:

https://zzzzzch.github.io/2017/12/23/Surf/

https://www.cnblogs.com/gfgwxw/p/9415218.html

Notes

comment phase of the algorithm for official document

Source Code

here can get more information from source code

https://github.com/opencv/opencv_contrib/blob/master/modules/xfeatures2d/src/sift.cpp

1. Scale-space Extrema Detection

1-1. Pyramids & Octaves

• Source Code Hint: buildGaussianPyramid()

process the input image to a scale Pyramids then in each scale layer, multiple the image with GaussBlur in different sigma

the group of the same scale including different GaussBlur result is called “octave”

in this step algorithm transform a single image to Pyramids layer count * Octaves count images

1-2. Create DoG(Difference of Gaussian) in octaves

• Source Code Hint: buildDoGPyramid()

the algorithm use DoG to replace LoG(Laplacian of Gaussian) to save time

in step 1-1, images in each octave are GaussBlur result the algorithm need is “Difference of Gaussian” to make the different gauss image need subtract adjacent GaussBlur image

in the document illustrated, each octave count from 5 to 4 after subtract

in the source code , nOctaveLayers+3 become nOctaveLayers+2 in function buildDoGPyramidComputer

1-3. Find extreme point from multiple layer space

• Source Code Hint: findScaleSpaceExtremaComputer()-operator()
• Key Role: make the SIFT get Scale Invariable ability

after preparing the DoG images in an octave of one scale, search the extreme point of local comparing the pixel near the target point to find the extreme value

near area means the 8 neighbor pixels, the 9 pixels above, and the 9 pixels underneath

which means 1 pixel should compare with 8+9+9 = 26 pixels in close space from source code you can see a huge if condition near the line 635 then take a threshold to filter the potential points with extrema value

2. Key point Localization

2-1. Refine the potential points to keypoint

• Source Code Hint: adjustLocalExtrema()

the step 1-3 extreme points are not the keypoints, because of edges effect we need to refine the keypoints to get more accurate points.

the method is to use Taylor series expansion (to understand this, we need more mathematic knowledge) then pick up a threshold to filter the result.

the result of stage1 is the keypoint in the Pyramids * Octaves space, not a flat image

2-2. Flatten the keypoints to origin size coordinate

• Source Code Hint: adjustLocalExtrema()

the stage2 is flattening those points to the origin image coordinate, so that we can do the “Orientation Assignment” step, near line 569, you can examine assigning of point (x, y)

3. Orientation Assignment

3-1. Use 36 bins histogram to calculate the main direction

• Source Code Hint: calcOrientationHist()
• Key Role: make the SIFT get Rotate Invariable ability

loop the keypoint, remove the duplicate point.

A neighborhood is taken around the keypoint, calculate the gradient, divide 360 degrees to 36 bins to generate a histogram.

1. take the max value as the main direction
2. keep the 80% value of max as an associate direction

then whatever the image rotate, the same area main orientation will not change

4. Keypoint Descriptor

4-1. Neighborhood pixels & Rotate

• Source Code Hint: calcOrientationHist()

once the orientation is made, use the 16*16 pixel square with the keypoint as center calculate descriptor.

divide the 16*16 square to 16 small square (call it “block”) with 4*4 size, each pixel in the block calculate the gradient, then 16 gradient number is token at one block

4-2. The second histogram with 8 bins

• Source Code Hint: calcSIFTDescriptor() + SIFT_DESCR_HIST_BINS

now we need a new histogram to represent the block, not the same histogram in step 3-1

block histogram use 8 bins represent 360 degree, the reason using 8 bins is there are only 16 candidate gradient in a block

4-3. Assemble the block histogram to the descriptor

• Source Code Hint: calcSIFTDescriptor() + float* dst

calculate each block histogram with 8 bins, store the 8 bins value to last parameter dst, 16 * 16 divided to 16 blocks

the final descriptor is a vector with 16 * 8 = 128 size, every 8 elements of this vector represent a block histogram

5. Keypoint Matching

this step is not the SIFT algorithm itself

it emphasizes algorithm is used for stitching images, should pick an appropriate threshold to get a better result.

sometimes the closet-distance is not as good as the second candidate

Refer:

https://blog.csdn.net/zddblog/article/details/7521424

记

2017年的文章吐槽加班加到吐血，2018年被公司教育了什么才是真的吐血

其实钱越来越少才是主要的

工作越来越久，感觉能写Blog的时间反而越来越少，才导致两年都没更新

CMake

我一直希望能做一个真正的Full Stack Engineer，而不是JS Stack Engineer

2019年也意识到C++是每个工程师的必修课，无论你工作中用不用他

这是一系列根据团队经验总结的跨平台生产环境多人协作情况下CMake从零到一的构建文章，配合源代码cmake-tutorial-sample可以查看详细细节

鸣谢

鸣谢2019年在卢协某和卢某棠为主的众多同事引导下，学习了这样那样许多许多C++的姿势，终于知道自己并不能21天精通C++了

鸣谢优秀的东京帝国大学毕业生沈同学和东京知名小V雪月秋水@acgotaku311的谆谆教导，帮我完成这个系列

序

CMake00编译的基本概念

源代码开始

CMake01构建HelloWorld

CMake02编译配置DebugRelease

CMake03添加文件和产物

CMake04添加第三方库

CMake05函数和宏的对比

CMake06加载文件进行复用

CMake07多工程协作

CMake08跨平台编译最佳实践：跨平台的最佳实践在这一节

CMake08跨平台编译iOS细节

CMake08跨平台编译Android细节

CMake08跨平台编译WebAssembly细节

后记

CMake09如何读懂复杂文档

CMake10不同IDE的差别和选择： 这个章节讲了如何用VSCode

在一个多人的团队中，技术栈不同，知识面不同、经验不同、上下文不同的情况下，协作起来难度十分的高，根据个人经验这是最无障碍的实践了，希望可以帮助到别的跨平台团队

Script

为什么投入了这么多时间在脚本相关的知识上

因为在加班的过程中，终于意识到工程师的最大价值就是自动化，自动化才能带来生产力提升，生产力才是商业中最核心的竞争力。

那么为了提高生产力，应该投入多少就会困扰很多人，根据个人经验总结

• 如果能花20倍的时间，把一个手动的工作变成自动，那么就应该去花这20倍的代价

所以说日常你有什么十分钟的操作，就值得花上一下午让他变成脚本

Python三连01脚本参数设定和解析

Python三连02如何使用正则获取变量

Python三连03Json的读写

Python三连04获取键盘输入到变量

Python三连05相等和类型判断的细节

Shell三连01脚本参数设定和解析

Shell三连02如何使用正则获取变量

Shell三连03文件的读写和重定向

Shell三连04条件命令和管线Pipe命令

Shell三连05递归遍历目录处理文件

Shell三连06如何读懂shell说明书man

Shell三连07STDIN重定向执行字符串

Shell三连08键盘输入到变量

Shell三连09获取shell命令的返回值

Shell三连10字符串转数字

Shell三连11内置函数字符串处理

Shell三连12开启后台任务

Shell三连13指令sed

Shell三连14指令grep

Shell三连15自动补全Framework的头文件

Shell三连16查询本机的Xcode证书

HTTPS

我觉得这个章节需要好好看看，因为面试最容易出现

当然更多是因为一直在读一本书 Computer Networking: A Top-Down Approach Featuring the Internet 但是一直读的很慢，愁人

因为日常工作，需要对传输控制层有足够对了解，应用层里大家最关心的就是HTTPS咯

HTTPS协议从顶至底解析

Layout

因为一直在做跨平台的工作，和设计交流的时候每个工程师思考布局的方式都不太一样，看看不同布局思维还蛮有意思的

不过最近又出了Flutter、SwiftUI等等，我觉得兜兜转转最终大家还会走到Web的布局思路上吧

Android、iOS、Web布局对比解析

源代码仓库LayoutSample

iOS

其实这两年iOS工作做的比较少，大部分也都是一些刁钻古怪的问题，真希望能快点在生产上写Swift啊

判断是否使用了模拟器

iOS8旋转动画禁止的更新

iOS11可用容量读取的改变

CollectionView常见Crash处理

保存媒体到相册的一些问题

ImageView模仿系统相册缩放

NSOperation和NSOperationQueue的基础用法

iOS储存自定义类进入UserDefaults

CMTime的含义和取值方法

OC实现链式调用

iOS崩溃闪退Crash分析原因

IPA安装包下载和重签名

DSYM符号文件的相关配置

C语言位域和字节对齐相关问题

C语言高级宏定义关键字和操作符

结语

2019年有机缘巧合来到了东京分公司，希望可以在2020年多认识 JK (许愿…)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

/* 
 * For the brave souls who get this far: You are the chosen ones,
 * 对那些耐下心思看到这里的哥们，容我说一句您真不容易
 * 
 * the valiant knights of programming who toil away, without rest,
 * 想必您不是东哥的兄弟，就是修过马老师的福报，或说带过牢厂的手环，也许在猪厂写着公众号
 * 
 * fixing our most awful code. To you, true saviors, kings of men,
 * 能看完我啰哩啰嗦的博客，对于你，小马哥的氪金之王，比特蹦迪的大帝
 * 
 * I say this: 
 * 我想问：
 * 
 * "Old brother，does your company have any head count to hire me？"
 * “大兄弟，贵厂还要人吗？”
 */

好想有机会去东京谷歌或者巨硬工作啊。。听说又闲钱又多。。。

IDE如何选择

IDE的概念是集成开发环境（Integrated Development Environment）

所谓集成就是集中了编译配置、编译、调试等功能，例如Xcode、Android Studio、CLion等

方便开发者专注于代码逻、快速实现功能或者减少指令输入

不过随着集成开发环境加入了越来越多的东西，变得越来越卡，现在也出现了简化的趋势，例如VSCode的流行

CLion如何工作

使用 CLion 创建一个 “New Project —— C++ Executable” 的工程，可以发现其根目录为

1
2
3
4

----Project
    --cmake-build-debug
    --CMakeLists.txt
    --main.cpp

对应该系列的第一篇文章HelloWorld可以发现 CLion也是使用CMake来组织工程

点击菜单栏 “Run” 存在 “Build、Run、Debug” 三个选项，指定一个断点，然后点击Debug就可以进行调试

操作工程你会发现以下几个重点

• “cmake .” 产生的一系列文件被放在了 cmake-build-debug
• 在根本的任何改动，都会使得CMakeLists.txt变化，并且刷新工程
• 和Xcode不一样，CLion没有模糊编译、运行、调试的概念
• CLion中 Build不会执行程序、Run的话断点不会停止、Debug才是Xcode的 Command+R

由于CLion 变的越来越卡了（2018年6月——2019年9月），导致很多人选择使用更加轻量级的VSCode来开发

VSCode的配置、编译、调试

VSCode就对程序员的专业程度要求比较高了，下载官方的C/C++插件之后

根据官方教程可以完成配置、编译、调试三个步骤

命令台（Command Palette）和命令行（Shell Command）工具code

命令台有两种打开方法

• 点击菜单栏 “View —— Command Palette”
• 使用组合键 Shift + Command + P

打开 “Command Palette” 可以执行 “Shell command: Install ‘code’ command in PATH” 来安装code指令

code指令把一个空文件夹配置成C/C++工程的基本命令，在完成配置后存在三个文件，目录结构如下

1
2
3
4
5

----HelloWorld
    --.vscode
        --c_cpp_properties.json
        --tasks.json
        --launch.json

工程配置文件 c_cpp_properties.json

打开 “Command Palette” 执行以下任意一个指令来配置基本的Workspace或Project的能力

• “C/C++: Edit Configurations (UI)” 可以使用可视化界面配置
• “C/C++: Edit Configurations (JSON)” 可以使用JSON文件配置

注意如上篇文章所陈述，工程和编译的概念很模糊，不同平台和语言的定义不完全一致，所以职责划分并不是绝对的

如果采用可视化界面配置，最终生效的还是 “.vscode/c_cpp_properties.json” 文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

//这个文件是不能加注释的，不然VSCode会报解析失败，这里加注释只是为了讲解
{
    //配置的数组，成员是字典
    "configurations": [
        {
            // 配置名称
            "name": "Mac",
            // 头文件目录 （重要）
            // 1. 当人为引用HelloWorld目录以外的头文件时需要自己新增配置
            // 2. 当引用第三方库时需要自己新增配置，例如OpenCV的 ${OpenCV_INCLUDE_DIRS}
            "includePath": [
                "${workspaceFolder}/**"
            ],
            // 本地变量
            "defines": [],
            // Mac系统的系统库
            "macFrameworkPath": [
                "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.14.sdk/System/Library/Frameworks"
            ],
            // 编译器的路径
            "compilerPath": "/usr/bin/clang",
            // 编译器的C语言版本 （重要）
            "cStandard": "c11",
            // 编译器的C++版本 （重要）
            "cppStandard": "c++17",
            // 自动补全和智能提示使用哪个
            "intelliSenseMode": "clang-x64"
        }
    ],
    //c_cpp_properties 配置的版本
    "version": 4
}

编译任务文件 tasks.json

打开 “Command Palette” 执行 “Tasks: Configure Default Build Task”

然后选择“Create tasks.json file from template —— Others” 来配置默认的编译任务 “.vscode/tasks.json”

编译的配置就没有UI界面了（怀疑是懒得做），为了体现VSCode的高自由度（对新人不友好）

这里举例了官方文档的配置示例、CMake的HelloWorld、模仿CLion指令三种配置，说明了不同指令之间的关系

其中CLion的作法才是比较成熟的作法，这里仅仅是举例整个演进的过程

官方配置示例（不重要）

官方配置是使用最基本的clang指令，完成文件编译

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

//这个文件是不能加注释的，不然VSCode会报解析失败，这里加注释只是为了讲解
{
  "version": "2.0.0",
  "tasks": [
    {
      // 任务名称
      "label": "Build with Clang",
      // 任务是一个Shell命令
      "type": "shell",
      // 使用 clang++ 命令
      "command": "clang++",
      // 对命令传入的参数 “clang++ -std=c++17 ....”
      "args": [
        "-std=c++17",
        "-stdlib=libc++",
        "main.cpp",
        "-o",
        "main",
        "--debug"
      ],
      // 设置这个任务是默认的任务，可以被快捷键直接启动
      "group": {
        "kind": "build",
        "isDefault": true
      }
    },
    //此处可以添加别的Task
    ....
  ]
}

CMake和Make指令分别使用 （不重要）

当文件结构足够多以及目录结构十分复杂的情况的时候，使用一条clang编译指令的参数就过于复杂

可以使用make文件来调度clang，可以参考 CMake配置完成后的 CMakeFiles/HelloWorld.dir/build.make 文件

1
2
3
4
5
6
7
8
9
10

{
  // 任务名称
  "label": "Build with CMake & Make",
  // 任务是一个Shell命令
  "type": "shell",
  // 1. 使用 cmake 进行配置
  // 2. 使用 make 指令进行编译
  "command": "cmake . && make",
  "args": [ ]
}

文件中使用的指令是 XcodeDefault.xctoolchain/usr/bin/c++ ，使用man之后可以看到是clang的一个别名指令

1
2
3
4

CMakeFiles/HelloWorld.dir/main.cpp.o: ../main.cpp
	.......
	/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/c++  .....
  ......

CLion的CMake流程（成熟工程的作法）

由于CMake本身就是对make的包装，那么可以把make指令本身也对大家隐藏起来，只使用cmake

例如CLion 就是仅使用 cmake 组织工程，可以分为配置和编译两步

配置过程在 New Project的过程中已经完成，我们没有抓到日志但是可以模拟出来

1
2
3
4
5
6
7
8
9
10
11
12

{
  // 任务名称
  "label": "Configure with CLion CMake",
  // 任务是一个Shell命令
  "type": "shell",
  // 模拟 CLion 新建工程文件
  // 1. 创建 cmake-build-debug 用于存放CMake的临时文件
  // 2. 切换到 cmake-build-debug
  // 3. 使用 cmake 指令配置 CMakeLists.txt 所在目录
  "command": "mkdir \"${workspaceFolder}/cmake-build-debug\" || cd \"${workspaceFolder}/cmake-build-debug\" && cmake ../.",
  "args": [ ]
}

而在编译阶段可以看到编译指令

1

"~/Library/Application Support/JetBrains/Toolbox/apps/CLion/ch-0/192.6262.62/CLion.app/Contents/bin/cmake/mac/bin/cmake" --build ~/Desktop/HelloWorld/cmake-build-debug --target main -- -j 2

我们在VSCode中使用Task来模拟，配置如下

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

{
  // 任务名称
  "label": "Build with CLion CMake",
  // 任务是一个Shell命令
  "type": "shell",
  // 模拟 CLion 编译工程目标
  // 1. 使用 cmake 指令替代 make 进行编译，底层还是调用的make
  "command": "cmake",
  // 2. 给 cmake 传入参数
  "args": [
      // 3-1. 指定编译配置所在目录 cmake参数
      "--build",
      // 3-2. 编译配置所在的目录取决于 CLion 生成时指定的目录
      "${workspaceFolder}/cmake-build-debug",
      // 4-1. 指定编译目标 cmake参数 
      "--target",
      // 4-2. 编译目标由 CMakeLists.txt 内 add_executable 决定
      "main",
      // 5-1. 透传参数给底层make
      "--",
      // 5-2. jobs 任务数 make参数
      "-j",
      // 5-3. 最多并发2个job
      "2"
  ]
}

调试启动文件 launch.json

打开 “Command Palette” 执行 “Debug: Open launch.json”

选择 “C++(GDB/LLDB)” 就是生成文件 “.vscode/launch.json” 可以用来调试采用Debug编译的可执行程序

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

//这个文件是不能加注释的，不然VSCode会报解析失败，这里加注释只是为了讲解
{
  // 版本号
  "version": "0.2.0",
  "configurations": [
    {
      // 名称
      "name": "(lldb) Launch",
      // 调试类型 cpp debug 
      "type": "cppdbg",
      // 请求分为 launch 和 attach，后者是附着到已经运行的程序上
      "request": "launch",
      // 被调试的程序（重要）
      // 程序所在的位置，根据tasks编译的结果决定
      // 如果采用上述的 cmake 和 clion 的指令就会和官方的有区别
      "program": "${workspaceFolder}/helloworld.out",
      // 启动时传入的参数
      "args": [],
      // 是否在入口的默认启动一个断点
      "stopAtEntry": true,
      // 工作目录，即 program 的io时的根目录
      "cwd": "${workspaceFolder}",
      // 环境变量
      "environment": [],
      // 是否启动额外的窗口
      "externalConsole": true,
      // 微软调试引擎 microsoft/MIEngine 接入的模式
      "MIMode": "lldb",
      // 日志输出
      "logging": {
        "trace": true,
        "traceResponse": true,
        "engineLogging": true
      },
      // 调试前重新编译（重要）
      // 因为调试（Debug）是启动已经编译好（Build Success）的程序
      // 如果想类似IDE CLion和Xcode 每次调试改动前都重新编译
      // 可以将编译任务放在Launch之前
      "preLaunchTask": {
        "task": "echo",
        "type": ""
      }
    }
  ]
}

结语

在对配置、编译、调试的整个流程熟悉了之后，如果选择 “VSCode + CMake” 进行开发可以总结为以下流程图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

+--------------------------------------------------------------------------+
|                                                                          |
|                             Source Code                                  |
|                                                                          |
+--------------------------------------------------------------------------+

+--------------------------------------------------------------------------+
|                                 VSCode                                   |
+--------------------------------------------------------------------------+

+------------+ +--------------------------------------------+ +------------+
|            | |                                            | |            |
| c_cpp_     | |                tasks.json                  | |   launch   |
| properties | |                                            | |   .json    |
| .json      | |                                            | |            |
|            | |                                            | |            |
|------------+ +--------------------------------------------+ +------+-----+
                                                                    |
              +--------------------------------------------+        |
              |                                            |        |
              |                  CMake                     |        |
              |                                            |        |
              | +----------------------------------------+ |        |
              | |                                        | |        |
              | |                 make                   | |        |
              | |                                        | |        |
              | |    +------------------------------+    | |      Debug
              | |    |                              |    | |        |
              | |    |           clang              |    | |        |
              | |    |                              |    | |        |
              | |    +------------------------------+    | |        |
              | +----------------------------------------+ |        |
              |                                            |        |
              +--------------------+-----------------------+        |
                                   |                                |
                                   v  Build                         |
               +-------------------+---------------------+          |
               |                                         |          |
               |             Executable(Target)          |          |
               |                                         | <--------+
               |                                         |
               +-----------------------------------------+

如何读懂复杂的文档

CMake的官方文档一直都以晦涩著称，学习曲线比较陡峭，仅有指令的手册没有完善的入门指导

这里补充一些入门提示，帮助新手理解

1
2
3
4

file(GLOB <variable>
     [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
     [<globbing-expressions>...])

符号的含义

这些符号规则和Shell的说明文档十分类似，如果有Linux相关经验的人应该不难理解

解析举例

根据符号分析，我们可以拆分解析指令

1. file是指令本身
2. 第一个固定参数 GLOB 代表Action
3. 第二个参数代表传入一个变量用于储存结果
4. 第三、四个参数一起作为可选输入参数，参数名 LIST_DIRECTORIES 参数值 true 或 false
5. 第五、六个参数一起作为可选输入参数，但是如果第四个存在，则第五个必须存在，参数名 RELATIVE 参数值为一个路径
6. 第七个参数参数为可选参数，本身不附带输入，为标记位，参数名 CONFIGURE_DEPENDS
7. 其八个参数为可选参数，该参数为变长参数，且必须使用 globbing-expressions

1
2
3
4
5
6
7
8

# file : 固定命令
# GLOB : 固定一个参数
# CPP_FILES : 第二个参数
# 3 - 7 个参数均被省略
# ..../*.cpp : 第八个参数

file(GLOB CPP_FILES ${CMAKE_CURRENT_LIST_DIR}/source/*.cpp)

WebAssembly实践细节

编译成WebAssembly需要使用Emscripten作为编译器，官方网站为emscripten.org

推荐实践路线

1. application: 推荐手动建立工程，给出sdk文件位置
2. sdk: 使用cmake生成，编译完成后拷贝至application应用文件夹
3. c++: 使用cmake管理，并通过sdk层引用

下载emsdk

官方文档Emscripten Toolchain Requirements指出Emscripten依赖的库包括

• Node.js、Python、Java、Git client、LLVM、Binaryen

你可以手动安装这些库，但是更加推荐的用法是根据官方文档Download and install直接下载SDK，其内部包含完整的工具链。

emsdk使用CMake

如果想让CMake使用emcc命令作为Compiler和LinkTool, 需要使用官方提供的工具链文件Emscripten.cmake

1
2
3
4
5
6

# To use this toolchain file with CMake, invoke CMake with the following command line parameters
# cmake -DCMAKE_TOOLCHAIN_FILE=<EmscriptenRoot>/cmake/Modules/Platform/Emscripten.cmake
#       -DCMAKE_BUILD_TYPE=<Debug|RelWithDebInfo|Release|MinSizeRel>
#       -G "Unix Makefiles" (Linux and OSX)
#       -G "MinGW Makefiles" (Windows)
#       <path/to/CMakeLists.txt> # Note, pass in here ONLY the path to the file, not the filename 'CMakeLists.txt' itself.

根据官方文档提示，只需要在cmake generate的过程中指定CMAKE_TOOLCHAIN_FILE即可

映射C++方法的方式

映射C++的方式分为两种 Embind 和 WebIDL Binder，参考博客使用WebAssembly编译C++到JS更加推荐 Embind的方式因为其丰富的数据结构映射

其中最重要的是 emscripten::val 可以映射任何东西

自然也包括了std::function，可以将C++的lambda转化为js的callback, 详见StackOverflow的回答

编译同步版本

根据官方文档Building to WebAssembly的章节 .wasm files and compilation 提出

1. WebAssembly默认编译结果是异步加载
2. 可以在onRuntimeInitialized中确定何时加载完毕
3. 加载完毕后才能访问C++代码

1
2

Another noticeable effect is that WebAssembly is compiled asynchronously by default, which means you must wait for compilation to complete before calling compiled code (by waiting for main(), or the onRuntimeInitialized callback......)

如果想要同步加载C++ Port的结果，可以选择在编译时设置 WASM_ASYNC_COMPILATION=0

需要注意的是这个参数并没有在编译配置的源代码中出现，应该是文档不够严谨导致的

常见的错误

• CMake中 target_compile_options 和 COMPILE_FLAGS 无效

在编译WebAssembly的过程中使用 –bind 参数无法通过以下两个CMake指令传入

1. target_compile_options
2. set_target_properties(<target> PROPERTIES COMPILE_FLAGS “–bind”)

而只能使用对应Link属性，可以通过 cmake –build path –verbose 查看调用的指令区别

具体原因不详，猜测和Emscripten的Compiler与Link为同一个指令相关

• Electron报错unsafe-eval

因为Electron内部的Content-Security-Policy的安全策略问题，使用WASM可能会报错

1

'unsafe-eval' is required because of a Chrome bug(?) that disallows loading WASM from 'self'.

参考开源工程electron-wasm-rust-example修改策略

1
2
3
4
5
6

<!--
  https://github.com/anderejd/electron-wasm-rust-example/issues/6
  https://github.com/WebAssembly/content-security-policy/issues/7
  https://bugs.chromium.org/p/chromium/issues/detail?id=948834&can=1&q=wasm-eval
-->
<meta http-equiv="Content-Security-Policy" content="script-src 'self' app: 'unsafe-eval'; object-src 'self' app:;">

Android平台实践细节

推荐实践路线

1. application: 推荐手动建立工程，方便团队里Android工程师使用
2. sdk: 手工创建工程，并通过build.gradle引用cmake，方便application工程师开箱即用
3. c++: 使用cmake管理，并通sdk层的CMakeLists.txt引用

Java怎么创建库Module

Android平台的Wrapper与通过CMake generate 出来的Xcode不同，需要自己手工建立

最重要的逻辑区别在于AndroidStudio自己调用CMakeLists.txt本身，过程分为

1. 创建空的Activity，增加 AndroidLibrary Module
2. 对AndroidLibrary 添加CMake的配置文件
3. 下载AndroidStudio读取C++必须的工具NDK、Ninjia

上述步骤可以按照Google官方文档的指导方案配置

Android配置中常见错误

• 现象：提示无Ninjia

1

CMake was unable to find a build program corresponding to "Ninja".  CMAKE_MAKE_PROGRAM is not set.

解决方案：通过Homebrew 或者 AndroidStudio安装Ninjia工具，Ninjia是一个Google的编译工具

• 现象：Sync不成功，提示找不到SDK

1
2
3

ERROR: Unable to resolve dependency for ':app@debug/compileClasspath': Failed to transform artifact 'sdk.aar (project :sdk)' to match attributes {artifactType=jar}.
Show Details
Affected Modules: app

解决方案： App使用了错误的build.gradle

setting.gradle应该加载正确的工程路径

1
2
3
4

include ':app', ':sdk'
rootProject.name='Render'

project(':sdk').projectDir = new File(rootDir.path, "../../wrapper/JNI/sdk")

build.gradle 需要使用正确的依赖方式

1
2
3
4

dependencies {
    ......
    implementation project(path: ':sdk')
}

• 现象：AndroidStudio未能加载CPP文件

解决方案：在安装Ninjia之后，点击”Build-Refresh Link C++ Project”

JNI中的Env问题

JNI接口中有一个最重要的概念是JNIEnv，作为每一个方法的第一个参数代表着Java环境的全部上下文

根据JNI官方文档原文指出

• 每一次Java虚拟机调用JNI接口，保证同一个线程传入同一个地址的JNIEnv

1

Native methods receive the JNI interface pointer as an argument. The VM is guaranteed to pass the same interface pointer to a native method when it makes multiple calls to the native method from the same Java thread. 

• JNIEnv和线程强相关，不能够在一个线程访问另一个线程的JNIEnv

1

The JNI interface pointer is only valid in the current thread. A native method, therefore, must not pass the interface pointer from one thread to another.

根据以上描述，如果开发者选择在C++开启一个线程，并且使用lambda进行回调的话，则需要注意

1. 两个Scope中的JNIEnv并不一致
2. 一般使用静态Map，以线程ID为Key值储存JNIEnv的指针
3. C++线程需要手动Attach到Java虚拟机上

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

//保留Java虚拟机
static JavaVM *java_vm = nullptr;
//创建容器
static std::unordered_map<std::thread::id, JNIEnv *> jni_env_map;

//在C++线程中获取线程Env并执行Attach
void* JNI_AttachCppThread() {
    JNIEnv *env;
    if (java_vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6) != JNI_OK) {
        return JNI_ERR;
    }
    if （java_vm->AttachCurrentThread(&env, NULL) != JNI_OK） {
        return JNI_ERR;
    }
    jni_env_map[std::this_thread::get_id()] = env;
}

//切换ENV
void JNI_method(JNIEnv *env, jobject thiz) {
    //Java方法调用
    auto java_thread_id = std::this_thread::get_id();
    auto java_env = jni_env_map.at(thread_id)
    if (env == java_env) {
        std::cout << "Some JNIEnv * passed by JavaVM" << std::endl;
    }
    //进入C++方法
    cpp::method_with_callback([]() {
        //通过C++线程获得Env
        //此处如果访问java_env则会造成JavaVM Crash
        auto cpp_thread_id = std::this_thread::get_id();
        auto cpp_env = jni_env_map.at(thread_id)
    });
}

iOS平台实践细节

推荐实践路线

1. application: 推荐手动建立工程，方便团队里iOS工程师使用
2. sdk: 使用cmake生成，并设置成同手动工程配置，方便application工程师开箱即用
3. c++: 使用cmake管理，并通过sdk层引用

iOS的Info.plist如何处理

iOS平台上的Product常见一个Info.plist文件用于描述基本信息

CMake提供了两个基本模版

1. MacOSXFrameworkInfo.plist.in
2. MacOSXBundleInfo.plist.in

并且可以通过设置一些环境变量填入这个模版, 参考官方文档

1
2
3
4

set(MACOSX_FRAMEWORK_IDENTIFIER "demo.alanli")    
set(MACOSX_FRAMEWORK_NAME "AlgorithmSDK")    
set(MACOSX_FRAMEWORK_BUNDLE_VERSION "1.0.0")    
set(MACOSX_FRAMEWORK_SHORT_VERSION_STRING "1.0.0")

也可以用户模仿官方模版自己指定模版，并且指定路径

1
2
3
4
5

set_target_properties(
    ....
    MACOSX_FRAMEWORK_INFO_PLIST ${CMAKE_CURRENT_LIST_DIR}/Info.plist.in
    ....
)

Xcode Generate 生成的工程和手工不一致

在使用Xcode Genreate的时候生成的工程有些选项和手工是不一致的，导致不能当成一个正常的Project来用

两个主要的问题

• Framework不能进行Archive操作
• Dependency和LinkLibrary的关系

解决方案分别是

• 手工生成的Project的Build Setting - SKIP_INSTALL 是YES， 而CMake生成的是 NO
• Xcode的Run指令会自动link已经dependency的target，不需要CMake的指令再link一遍，如果不是Xcode Generate则需要CMake进行Link

列出一份基本的配置表，帮助我们可以还原Xcode11 手动创建的工程配置, 更多细节可以参考源代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

set_target_properties(
    AlgorithmSDK PROPERTIES
    # Make target is framework
    FRAMEWORK TRUE
    FRAMEWORK_VERSION C
    MACOSX_FRAMEWORK_IDENTIFIER ${MACOSX_FRAMEWORK_IDENTIFIER}
    MACOSX_FRAMEWORK_INFO_PLIST ${CMAKE_CURRENT_LIST_DIR}/Info.plist.in
    # Mark which headers should public
    PUBLIC_HEADER ${TARGET_HEADERS}
    ## ----------------------------------
    ## Architecture
    ## ----------------------------------
    XCODE_ATTRIBUTE_ONLY_ACTIVE_ARCH[variant=Debug] "YES"
    XCODE_ATTRIBUTE_ONLY_ACTIVE_ARCH[variant=Release] "NO"
    ## ----------------------------------
    ## Build Location
    ## ----------------------------------
    XCODE_ATTRIBUTE_SYMROOT "build"
    ## ----------------------------------
    ## Build Option
    ## ----------------------------------
    XCODE_ATTRIBUTE_DEBUG_INFORMATION_FORMAT[variant=Debug] "dwarf"
    XCODE_ATTRIBUTE_DEBUG_INFORMATION_FORMAT[variant=Release] "dwarf-with-dsym"
    ## ----------------------------------
    ## Deployment
    ## ----------------------------------
    # Enable iPhone,iPad, cmake default is iPhone
    XCODE_ATTRIBUTE_TARGETED_DEVICE_FAMILY "1,2"
    # Enable framework can archive, cmake default is NO
    XCODE_ATTRIBUTE_SKIP_INSTALL "YES"
    XCODE_ATTRIBUTE_INSTALL_PATH "$(LOCAL_LIBRARY_DIR)/Frameworks"
    ## ----------------------------------
    ## Link
    ## ----------------------------------
    XCODE_ATTRIBUTE_DYLIB_INSTALL_NAME_BASE "@rpath"
    XCODE_ATTRIBUTE_LD_DYLIB_INSTALL_NAME "$(DYLIB_INSTALL_NAME_BASE:standardizepath)/$(EXECUTABLE_PATH)"
    XCODE_ATTRIBUTE_LD_RUNPATH_SEARCH_PATHS "$(inherited) @executable_path/Frameworks @loader_path/Frameworks"
    XCODE_ATTRIBUTE_DYLIB_COMPATIBILITY_VERSION "1"
    XCODE_ATTRIBUTE_DYLIB_CURRENT_VERSION "1"
    ## ----------------------------------
    ## Packaging
    ## ----------------------------------
    XCODE_ATTRIBUTE_PRODUCT_BUNDLE_IDENTIFIER ${MACOSX_FRAMEWORK_IDENTIFIER}
    ## ----------------------------------
    ## Apple Clang - Language - C++
    ## ----------------------------------
    XCODE_ATTRIBUTE_CLANG_CXX_LANGUAGE_STANDARD "gnu++14"
    XCODE_ATTRIBUTE_CLANG_CXX_LIBRARY "libc++"
    ## ----------------------------------
    ## Apple Clang - Language - Modules
    ## ----------------------------------
    XCODE_ATTRIBUTE_CLANG_ENABLE_MODULES "YES"
    ## ----------------------------------
    ## Apple Clang - Language - Objective-C
    ## ----------------------------------
    # Enable ARC, cmake default is MRC
    XCODE_ATTRIBUTE_CLANG_ENABLE_OBJC_ARC "YES"
    XCODE_ATTRIBUTE_CLANG_ENABLE_OBJC_WEAK "YES"
    ## ----------------------------------
    ## Apple Clang - Language - Code Generation
    ## ----------------------------------
    XCODE_ATTRIBUTE_GCC_GENERATE_DEBUGGING_SYMBOLS "YES"
)

默认是MAC 要设置成iOS

已知的错误实践

由于CMake可以使用Xcode作为Generator，所以大部分开发者会有生成一个TestApp的想法，及通过

1

add_executable(test_app ${Headers} ${Sources})

虽然CMake支持这个功能，但是对于一些细节问题处理的不够好，有三个问题会依次出现

1. 通过 cmake –build . 指令编译失败
2. 签名问题比较复杂，如果多团队使用不同的证书，通用性比较差
3. 无法生成Asset.xcassets 文件，可以通过Resource管理图片，不方便不懂CMake的开发队友

解决这三个问题引入的方法复杂度远高于三个问题本身，所以不推荐使用CMake生成测试用App，尽量采用示例代码的结构

签名问题

根据CMake文档FRAMEWORK的示例代码

1
2
3
4

set_target_properties(dynamicFramework PROPERTIES
  ........
  XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY "iPhone Developer"
)

使用”iPhone Developer”的原因是因为Xcode会自动寻找合适的证书，如果不使用这种通用字符串，可以指定具体的签名文件

根据经验推荐以下两点

1. 如果你有App需要源码依赖Framework，不推荐对Framework进行签名，而统一交给App进行签名
2. 如果发布的Release产品就是一个Framework必须签名，推荐使用 “iPhone Distribution”，并设置CMAKE_XCODE_ATTRIBUTE_DEVELOPMENT_TEAM

Swift启用

如果想启用Swift需要使用的CMake指令

1
2

# 注意要在写add_library add_execute 之前
enable_language(Swift)

并且Swift因为更新的原因常常会找不到Compiler，需要更新至最新CMake，例如No CMAKE_Swift_COMPILER could be found

目标

CMake最大的作用之一就是整合各个平台的工具链来管理共享的代码

本文根据实际工作给出一份最佳实践源代码cmake-tutorial-sample，所要达成的目标

1. 一个可以共享的C++算法库
2. 代码逻辑可以应用于 Mobile、Desktop、Web 三种环境
3. 一份对应平台的中间层SDK Wrapper

在真正的团队合作中，还需要补充的最重要的两点

• 不给业务开发者带来额外的负担，因为不同平台业务开发者可能不了解cmake运作机制
• 中间层SDK可以通过IDE进行源代码引用提供调试能力，因为SDK的UnitTest无法达到100%覆盖，方便出现问题时定位原因位于业务层还是SDK层

基本的目录结构包括

1
2
3
4
5
6

#根目录
--root
  --application #可以运行的App，包含iOS、Android、Electron、Web
  --cmake #使用cmake编译的库，包含共享的C++库、iOS的framework、Android的aar，WebAssembly的wasm
  --wrapper #中间层工程，包含cmake生成的Xcode工程、WebAssembly的Make工程，手工建立的Android中间层

路线

根据不同的平台提供不同的Target，并且产生Wrapper工程的方式不同

已知的关键点

不同的平台细节上会有一些需要注意的地方，大致包含以下几个方面，会在后续的文章中进行详解

工作台的问题

在编译的基本概念里有提到一个管理器空间，iOS叫Workspace，Android叫Project

CMake本身使用Directory作为管理器空间的组织者，通过SubDirectory来组织不同的CMake项目

子目录

1
2
3
4
5
6
7
8
9

——root
    ——build
    ——main
        ——CMakeLists.txt
    ——hello
        ——CMakeLists.txt
    ——world
        ——CMakeLists.txt
    ——CMakeLists.txt

目录helloworld - CMakeLists.txt

“helloworld”这个顶级文件夹作为协调不同工程的工作空间

1
2
3
4
5
6
7
8
9
10
11

# 指定CMake最小版本
cmake_minimum_required(VERSION 3.14)

# 该工程为Workspace，不包含任何 target，仅起协调作用
project(HelloWorld)

# 内部协调的工程分别位于文件夹 hello、world、main
add_subdirectory(${CMAKE_CURRENT_LIST_DIR}/hello)
add_subdirectory(${CMAKE_CURRENT_LIST_DIR}/world)
add_subdirectory(${CMAKE_CURRENT_LIST_DIR}/main)

目录main - CMakeLists.txt

“main”工程为主程序，其依赖两个子工程分别是 hello 和 world

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

# 指定CMake最小版本
cmake_minimum_required(VERSION 3.14)

# hello_world内包含一个可执行文件的target
# target 的名称为 main
# 对比：
# iOS的习惯里 一般project名和target同名
# Android的习惯里 module名下可以有多个package名
add_executable(main main.cpp)

# 依赖关系为 main 依赖 hello、world两个项目产生的库
add_dependencies(
    main  # 名称来自 main - CMakeLists.txt 的 add_executable
    hello # 名称来自 hello - CMakeLists.txt 的 add_library
    world # 名称来自 world - CMakeLists.txt 的 add_library
    )

# 给main target添加头文件目录
# 帮助我们寻找头文件 #include<.h>
# CMAKE_SOURCE_DIR 指的是顶级目录 helloworld
target_include_directories(
    main
    PUBLIC ${CMAKE_SOURCE_DIR}/hello
    PUBLIC ${CMAKE_SOURCE_DIR}/world
)

# 给main target添加依赖库
# 帮助调用库中的函数
target_link_libraries(
    main
    hello
    world
)

目录依赖库 - CMakeLists.txt

其中 “hello” 和 “world” 均为我们的依赖库，使用的CMakeLists.txt文件主体结构十分类似

1
2
3
4
5
6

# 指定CMake最小版本
cmake_minimum_required(VERSION 3.14)

# 一个静态库的target 名称为 hello
# 经过workspace协调后可以被main引用
add_library(hello hello.cpp)

更多的源代码可以参考CMake07的源代码

目录并不在文件系统子目录内

在当前的举例中 hello 和 world 都在文件系统内实际为子目录，如果存在不为文件系统子目录的情况, 根据文档描述

1

If binary_dir is not specified, the value of source_dir, before expanding any relative path, will be used (the typical usage).

所以如果我们想使用相对路径的 source_dir，可以通过以下方式指定 binary_dir

1
2
3
4

# 相当于 add_subdirectory(${CMAKE_CURRENT_LIST_DIR}/hello  ${CMAKE_CURRENT_BINARY_DIR}/hello)
add_subdirectory(${CMAKE_CURRENT_LIST_DIR}/hello)
# 参数1不为实际的子目录，只需要指定 BINARY_DIR 即可
add_subdirectory(${CMAKE_CURRENT_LIST_DIR}/../outside/world ${CMAKE_CURRENT_BINARY_DIR}/world)