所有的编译脚本都在mars/mars目录

环境

安装 cmake 和 XCode 以及 python2.7

编译

  1. python build_ios.py

or

  1. python build_osx.py

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

文件名描述
cmake_build/Darwin.out/mars.frameworkmars 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.hlonglink_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 后缀。

链接

Mars iOS/OS X 接入指南 - 图1

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

使用

xlog

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

  1. NSString* logPath = [[NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) objectAtIndex:0] stringByAppendingString:@"/log"];
  2.  
  3. // set do not backup for logpath
  4. const char* attrName = "com.apple.MobileBackup";
  5. u_int8_t attrValue = 1;
  6. setxattr([logPath UTF8String], attrName, &attrValue, sizeof(attrValue), 0, 0);
  7.  
  8. // init xlog
  9. #if DEBUG
  10. xlogger_SetLevel(kLevelDebug);
  11. appender_set_console_log(true);
  12. #else
  13. xlogger_SetLevel(kLevelInfo);
  14. appender_set_console_log(false);
  15. #endif
  16. appender_open(kAppednerAsync, [logPath UTF8String], "Test");

在 applicationWillTerminate 函数中反初始化：

  1. appender_close();

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

  1. LogUtil.h

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

  1. LOG_DEBUG(TAG, @"I wanna say: %@", @"hello mars!");
  3. LOG_INFO(TAG, @"I wanna say: %@", @"hello mars!");
  5. LOG_WARNING(TAG, @"I wanna say: %@", @"hello mars!");
  7. LOG_ERROR(TAG, @"I wanna say: %@", @"hello mars!");
  9. TAG请自行定义

需要注意：

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

stn

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

  1. - (void)setCallBack {
  2.     mars::stn::SetCallback(mars::stn::StnCallBack::Instance());
  3.     mars::app::SetCallback(mars::app::AppCallBack::Instance());
  4. }
  5.  
  6. - (void) createMars {
  7.     mars::baseevent::OnCreate();
  8. }
  9.  
  10. - (void)setClientVersion:(UInt32)clientVersion {
  11.     mars::stn::SetClientVersion(clientVersion);
  12. }
  13.  
  14. - (void)setShortLinkDebugIP:(NSString *)IP port:(const unsigned short)port {
  15.     std::string ipAddress([IP UTF8String]);
  16.     mars::stn::SetShortlinkSvrAddr(port, ipAddress);
  17. }
  18.  
  19. - (void)setShortLinkPort:(const unsigned short)port {
  20.     mars::stn::SetShortlinkSvrAddr(port);
  21. }
  22.  
  23. - (void)setLongLinkAddress:(NSString *)string port:(const unsigned short)port debugIP:(NSString *)IP {
  24.     std::string ipAddress([string UTF8String]);
  25.     std::string debugIP([IP UTF8String]);
  26.     std::vector<uint16_t> ports;
  27.     ports.push_back(port);
  28.     mars::stn::SetLonglinkSvrAddr(ipAddress,ports,debugIP);
  29. }
  30.  
  31. - (void)setLongLinkAddress:(NSString *)string port:(const unsigned short)port {
  32.     std::string ipAddress([string UTF8String]);
  33.     std::vector<uint16_t> ports;
  34.     ports.push_back(port);
  35.     mars::stn::SetLonglinkSvrAddr(ipAddress,ports);
  36. }
  37.  
  38. - (void)reportEvent_OnForeground:(BOOL)isForeground {
  39.     mars::baseevent::OnForeground(isForeground);
  40. }
  41.  
  42. - (void)makesureLongLinkConnect {
  43.     mars::stn::MakesureLonglinkConnected();
  44. }

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

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

  1. - (void)destroyMars {
  2.     mars::baseevent::OnDestroy();
  3. }

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

  1. - (void)reportEvent_OnForeground:(BOOL)isForeground {
  2.     mars::baseevent::OnForeground(isForeground);
  3. }

发生网络切换时调用：

  1. - (void)reportEvent_OnNetworkChange {
  2.     mars::baseevent::OnNetworkChange();
  3. }

调试

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

  • master 分支；最近一次 release 的稳定代码，我们在 master 分支打 tag，所有 master 上的代码都应是经过微信全量验证过;
  • dev 分支；开发分支，这里会包含下一个版本的代码，我们只能给 dev 分支提 pr 以及验证部分已经修复的 issue;关于 Mars 分支管理、issue 以及 pr 规范，请阅读 Mars Contributing Guide。

选好一个需要调试的分支后，Mars 源码调试就很简单了，这里以 iOS 调试为例，OS X 几乎方式一样。文字描述如下：

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

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