Mars iOS／OS X 接入指南

所有的编译脚本都在mars/mars目录, 目前脚本只生成 arm64 和 x86_64的库。

环境

安装 cmake 和 XCode 以及 python2.7

编译

python build_ios.py 

or

python build_osx.py

编译成功后，输出文件详细介绍如下：

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

以下接入部分可参考 mars/samples/iOS 和 mars/samples/Mac。 强调：所有直接调用 C/C++接口的 Objc 源文件必须是 .mm 后缀，不能是.m 后缀。 默认是关闭 bitcode 的，如需打开请自行build_ios.py/build_osx.py 中的 IOS_BUILD_SIMULATOR_CMD和IOS_BUILD_OS_CMD 中的-DENABLE_BITCODE=1

链接

其中红色部分为 mars 提供的部分，黄色部分是使用 mars 需要的系统库，绿色部分为需要开发者自行实现的 callback 部分。注意：链接的时候要把生成的 framework 移到别的位置再链接，不要直接用mars/mars/cmake_build/iOS/Darwin.out 目录。因为如果再次执行编译脚本会进行一次 clean, 会删除此目录下的文件。

使用

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. 先按照上述步骤中的链接(因为编译的时候需要这一步的头文件)部分编译通过
2. 移除 "Link Binary With Libraries" 中的 mars.framework
3. 通过python build_ios.py 中的选项生成iOS项目，把项目文件 "cmake_build/mars.xcodeproj" 拖到项目中，以子项目的方式存在
4. 把 相关.a 添加到 "Link Binary With Libraries" 中
5. 加断点，编译调试

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