Mars iOS/OS X 接入指南

garryyan edited this page Sep 12, 2017 · 13 revisions

所有的编译脚本都在libraries目录

编译

python build_apple.py

编译成功后,输出文件详细介绍如下:

文件名 描述
mars.framework mars framework
log_crypt.cc.rewriteme 最新版本已不再需要
log_crypt.h 最新版本已不再需要
longlink_packer.cc.rewriteme 长连接协议可扩展部分,使用前请先改名为 longlink_packer.cc,如若想自定义长连接包头以及加解包,重写该文件。
longlink_packer.h 编译 longlink_packer.cc 需要使用的头文件,请勿修改。
stnproto_logic.h longlink_packer.cc 中 SetClientVersion 函数的声明。如若删除 SetClientVersion 函数,请同时删除该文件。
shortlink_packer.cc.rewriteme 短连接协议可扩展部分,使用前请先改名为 shortlink_packer.cc,如若想自定义短连接包头(HTTP Head),重写该文件。
shortlink_packer.h 编译 shortlink_packer.cc 需要使用的头文件,请勿修改。

以下接入部分可参考 mars/samples/iOS 和 mars/samples/Mac。 强调:所有直接调用 C/C++接口的 Objc 源文件必须是 .mm 后缀,不能是.m 后缀。

链接

其中红色部分为 mars 提供的部分,黄色部分是使用 mars 需要的系统库,绿色部分为需要开发者自行实现的 callback 部分。

使用

xlog

推荐在 main.mm 的 main 函数里初始化:

NSString* logPath = [[NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) objectAtIndex:0] stringByAppendingString:@"/log"];
        
// set do not backup for logpath
const char* attrName = "com.apple.MobileBackup";
u_int8_t attrValue = 1;
setxattr([logPath UTF8String], attrName, &attrValue, sizeof(attrValue), 0, 0);
        
// init xlog
#if DEBUG
xlogger_SetLevel(kLevelDebug);
appender_set_console_log(true);
#else
xlogger_SetLevel(kLevelInfo);
appender_set_console_log(false);
#endif
appender_open(kAppednerAsync, [logPath UTF8String], "Test");

在 applicationWillTerminate 函数中反初始化:

appender_close();

上面的步骤介绍了在iOS/OSX中如何在进程启动和退出时打开关闭xlog,下面还需要讲一下xlog的使用方法,我们可以看到上图中Component部分有

LogUtil.h

这是我们为objc开发者提供的上层应用封装,开发者可将Component中的代码全部复制到自己的代码中进行修改或直接使用,日志打印宏支持可变参数。

LOG_DEBUG(TAG, @"I wanna say: %@", @"hello mars!");

LOG_INFO(TAG, @"I wanna say: %@", @"hello mars!");

LOG_WARNING(TAG, @"I wanna say: %@", @"hello mars!");

LOG_ERROR(TAG, @"I wanna say: %@", @"hello mars!");

TAG请自行定义

需要注意:

  • 保存 log 的目录请使用单独的目录,不要存放任何其他文件防止被 xlog 自动清理功能误删。
  • 请把 log 目录设上不备份的标识。
  • debug 版本下建议把控制台日志打开,日志级别设为 Debug, release 版本建议把控制台日志关闭,日志级别使用 Info.
  • 直接include xlog头文件的 oc 文件名后缀一定要是 .mm 不要使用 .m

stn

建议在 didFinishLaunchingWithOptions 函数中或者使用网络之前进行初始化:

- (void)setCallBack {
    mars::stn::SetCallback(mars::stn::StnCallBack::Instance());
    mars::app::SetCallback(mars::app::AppCallBack::Instance());
}

- (void) createMars {
    mars::baseevent::OnCreate();
}

- (void)setClientVersion:(UInt32)clientVersion {
    mars::stn::SetClientVersion(clientVersion);
}

- (void)setShortLinkDebugIP:(NSString *)IP port:(const unsigned short)port {
    std::string ipAddress([IP UTF8String]);
    mars::stn::SetShortlinkSvrAddr(port, ipAddress);
}

- (void)setShortLinkPort:(const unsigned short)port {
    mars::stn::SetShortlinkSvrAddr(port);
}

- (void)setLongLinkAddress:(NSString *)string port:(const unsigned short)port debugIP:(NSString *)IP {
    std::string ipAddress([string UTF8String]);
    std::string debugIP([IP UTF8String]);
    std::vector<uint16_t> ports;
    ports.push_back(port);
    mars::stn::SetLonglinkSvrAddr(ipAddress,ports,debugIP);
}

- (void)setLongLinkAddress:(NSString *)string port:(const unsigned short)port {
    std::string ipAddress([string UTF8String]);
    std::vector<uint16_t> ports;
    ports.push_back(port);
    mars::stn::SetLonglinkSvrAddr(ipAddress,ports);
}

- (void)reportEvent_OnForeground:(BOOL)isForeground {
    mars::baseevent::OnForeground(isForeground);
}

- (void)makesureLongLinkConnect {
    mars::stn::MakesureLonglinkConnected();
}

初始化顺序不一定要严格遵守上述代码的顺序,但在初始化时首先要调用 setCallBack 接口(callback 文件的编写可以参考 demo ),最后再调用 onForeground 和 makesureLongLinkConnect,中间顺序可以随意更改。注意:STN 默认是后台,所以初始化 STN 后需要主动调用一次BaseEvent.onForeground(true)

在程序退出时或需要释放 stn 时调用:

- (void)destroyMars {
    mars::baseevent::OnDestroy();
}

当发生前后台切换时调用:

- (void)reportEvent_OnForeground:(BOOL)isForeground {
    mars::baseevent::OnForeground(isForeground);
}

发生网络切换时调用:

- (void)reportEvent_OnNetworkChange {
    mars::baseevent::OnNetworkChange();
}

调试

github/Mars 的默认分支为 master 分支,几个含义的含义分别是:

  • master 分支;最近一次 release 的稳定代码,我们在 master 分支打 tag,所有 master 上的代码都应是经过微信全量验证过;
  • dev 分支;开发分支,这里会包含下一个版本的代码,我们只能给 dev 分支提 pr 以及验证部分已经修复的 issue;

关于 Mars 分支管理、issue 以及 pr 规范,请阅读 Mars Contributing Guide

选好一个需要调试的分支后,Mars 源码调试就很简单了,这里以 iOS 调试为例,OS X 几乎方式一样。在调试之前建议先按照上述步骤中的链接(因为编译的时候需要这一步的头文件)部分编译通过。文字描述如下:

  1. 移除 "Link Binary With Libraries" 中的 mars.framework
  2. 把 Mars 的项目文件 "mars-open-iphone.xcodeproj" 拖到项目中,以子项目的方式存在
  3. 把 "libmars-open-iphone.a" 添加到 "Link Binary With Libraries" 中
  4. 把 "mars-open-iphone" 添加到 "Target Dependencies" 中
  5. 加断点,编译调试

更详细的的接口说明请参考 Mars iOS/OS X 接口详细说明

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.