Skip to content

Developer Guide

Jump to bottom
pzheng edited this page Dec 24, 2021 · 19 revisions

CLI 指南

项目的命令行工具（CLI）是 ./main.swift，也可直接在 *.xcodeproj 中查阅 CLI Target。

CLI 依赖安装

  1. 安装 brew，参考官网
  2. （强烈推荐）通过 brew 安装 ruby
    1. 运行命令 brew install ruby，安装完成后，terminal 会有如下信息： 
      ==> Caveats
By default, binaries installed by gem will be placed into:
  /usr/local/lib/ruby/gems/3.0.0/bin

You may want to add this to your PATH.

ruby is keg-only, which means it was not symlinked into /usr/local,
because macOS already provides this software and installing another version in
parallel can cause all kinds of trouble.

If you need to have ruby first in your PATH, run:
  echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc

For compilers to find ruby you may need to set:
  export LDFLAGS="-L/usr/local/opt/ruby/lib"
  export CPPFLAGS="-I/usr/local/opt/ruby/include"

For pkg-config to find ruby you may need to set:
  export PKG_CONFIG_PATH="/usr/local/opt/ruby/lib/pkgconfig"
    2. 按照上述提示，继续运行如下两条命令： 
      echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc
// **注意**，需把 `{binaries installed by gem path}` 替换为 terminal 显示的信息中的 `By default, binaries installed by gem will be placed into:` 对应的值。
// 例如上述信息中是 `/usr/local/lib/ruby/gems/3.0.0/bin`，那么下面这行命令就应该是 `echo 'export PATH="/usr/local/lib/ruby/gems/3.0.0/bin:$PATH"' >> ~/.zshrc`
echo 'export PATH="{binaries installed by gem path}:$PATH"' >> ~/.zshrc
  3. 运行命令 gem install bundler 安装 bundler
  4. 在项目的根目录 ./ 下运行两条命令 bundle install 和 brew bundle install 安装相关依赖

CLI 使用

在项目的根目录 ./ 下运行 ./main.swift h，可以看到 CLI 的帮助文档。

build

运行 ./main.swift b 可以在全平台编译 LeanCloudObjc 库。

version-update

运行 ./main.swift vu 可以更新项目中和版本号有关的文件，一般在正式发布前做更新，版本号更新遵循 Semantic Versioning 2.0.0 协议。

pull-request

运行 ./main.swift pr 可以通过 hub 来提交当前分支的 PR，第一次通过 hub 提交 PR 时，一般需要配置 personal access token。

pod-trunk

运行 ./main.swift pt 将新版本正式推到 pod 上，发布前的人工检查项如下：

  • 相关 PR 是否已经合并到了主分支
  • LeanCloudObjc 在全平台编译是否通过
  • LeanCloudObjc 单元测试是否全部通过
  • 版本号更新是否正确
  • tags 页面是否存在对应的 tag

api-docs-update

运行 ./main.swift adu 可以更新 LeanCloudObjc 的 API 文档，需将 api-docs 项目 clone 到 objc-sdk 项目所在的目录下，例如 xxx/api-docs 和 xxx/objc-sdk。

之后浏览器会自动打开部署页面（需要企业微信认证），点击 Build 按钮发布 API 文档，发布成功后，等一会儿，可在官网看到更新。

third-party-library-upgrade

运行 ./main.swift tplu 可以看到更新第三方库的帮助文档，目前仅支持更新 protobuf 库，一般流程如下：

  1. 将第三方库 clone 到 objc-sdk 项目所在的目录下，例如 xxx/third-party-library 和 xxx/objc-sdk
  2. 将 clone 下来的第三方库 checkout 到想使用的版本，例如 git checkout v3.19.1
  3. 回到 objc-sdk/ 目录，运行对应的命令更新第三方库，以 protobuf 为例：./main.swift tplu protobuf

PR 流程

commit

遵循 LeanCloud Git Commit 日志风格指南。

通过命令行工具 ./main.swift 提交 PR 时，会自动检测最近的 commits 并给 PR 贴上 label，检测规则依据上述风格指南，不一定完全准确，偶尔需要人工修改 PR 的标题以及 label。

给 PR 贴上 label，是为了在合并时触发 release-drafter，自动生成 Release Notes。

PR 时机

一般在完成一个 feat 或 fix 的 commit 后，全量编译以及单元测试都通过了，那么就可以提交 PR。

（⚠️已废弃⚠️）更新 IM 协议

目前 IM 采用 Protobuf 作为数据交换格式。Protobuf 需要一个文件来定义数据结构，通常该文件的后缀名为 .proto。目前 IM 协议的 .proto 文件在 avoscloud-push 仓库中维护。当 IM 协议有新的数据结构引入时，SDK 需要将 .proto 文件编译成目标平台的源文件。对于 Objective-C SDK，步骤如下：

  1. 确保当前系统安装了 Protobuf "~> 3.3.0"（macOS 推荐使用 brew 安装）；
  2. 下载 .proto 文件，将其重命名为 messages.proto.orig；
  3. 在 messages.proto.orig 文件的目录，执行命令 mkdir objc && protoc --proto_path=. --objc_out=objc messages.proto.orig；
  4. 将 objc 目录下的源文件拷贝到 SDK 的 AVOS/AVOSCloudIM/Commands 目录下；
  5. 执行 AVOS/AVOSCloudIM/Commands/subst.tcl 来修改代码中的符号前缀；
  6. 编译 IM 模块，确认是否一切正常。

IM 协议文档

实时消息协议

LiveQuery 文档

登录是 {"cmd":"login","appId":"nWV9ebO1JMUIE5K4gBS1i1MA","installationId":"w3", "i": 111, "service":1}，登出是 {"cmd":"logout","appId":"nWV9ebO1JMUIE5K4gBS1i1MA","installationId":"w3", "i": 111, "service":1}
消息是 {"cmd":"data","msg":[{"alert":"test","_expiration_time":"2016-08-02T08:28:23.426Z","_channel":"push-tester"}],"ids":["WoT00LD7jLr6q9ET"],"appId":"d6xq05dmb08j5z9jjawnl88ns0072uwubvnzfha3nw1xojbr","installationId":"_push-tester"}
就这三种消息
消息中 msg 和 ids 都是数组，他们俩按数组内顺序一一对应

先占位，后面再规范化。

Clone this wiki locally