Mars

licenseRelease VersionPRs WelcomeWeChat ApprovedWeChat Approved

Mars 是微信官方的跨平台跨业务的终端基础组件。

mars

  • comm:可以独立使用的公共库,包括 socket、线程、消息队列、协程等;
  • xlog:高可靠性高性能的运行期日志组件;
  • SDT: 网络诊断组件;
  • STN: 信令分发网络模块,也是 Mars 最主要的部分。

Samples

sample 的使用请参考这里

Getting started

接入 Android 或者 iOS/OS X 或者 Windows

Android

gradle 接入我们提供了两种接入方式:mars-wrapper 或者 mars-core。如果你只是想做个 sample 推荐使用 mars-wrapper,可以快速开发;但是如果你想把 mars 用到你的 app 中的话,推荐使用 mars-core,可定制性更高。

mars-wrapper

在 app/build.gradle 中添加 mars-wrapper 的依赖:

  1. dependencies {
  2. compile 'com.tencent.mars:mars-wrapper:1.2.0'
  3. }

或者

mars-core

在 app/build.gradle 中添加 mars-core 的依赖:

  1. dependencies {
  2. compile 'com.tencent.mars:mars-core:1.2.2'
  3. }

或者

mars-xlog

如果只想使用 xlog,可以只加 xlog 的依赖(mars-core,mars-wrapper 中都已经包括 xlog):

  1. dependencies {
  2. compile 'com.tencent.mars:mars-xlog:1.0.7'
  3. }

接着往下操作之前,请先确保你已经添加了 mars-wrapper 或者 mars-core 或者 mars-xlog 的依赖

Xlog Init

在程序启动加载 Xlog 后紧接着初始化 Xlog。但要注意如果你的程序使用了多进程,不要把多个进程的日志输出到同一个文件中,保证每个进程独享一个日志文件。而且保存 log 的目录请使用单独的目录,不要存放任何其他文件防止被 xlog 自动清理功能误删。

  1. System.loadLibrary("c++_shared");
  2. System.loadLibrary("marsxlog");
  3.  
  4. final String SDCARD = Environment.getExternalStorageDirectory().getAbsolutePath();
  5. final String logPath = SDCARD + "/marssample/log";
  6.  
  7. // this is necessary, or may crash for SIGBUS
  8. final String cachePath = this.getFilesDir() + "/xlog"
  9.  
  10. //init xlog
  11. if (BuildConfig.DEBUG) {
  12. Xlog.appenderOpen(Xlog.LEVEL_DEBUG, Xlog.AppenderModeAsync, cachePath, logPath, "MarsSample", 0, "");
  13. Xlog.setConsoleLogOpen(true);
  14.  
  15. } else {
  16. Xlog.appenderOpen(Xlog.LEVEL_INFO, Xlog.AppenderModeAsync, cachePath, logPath, "MarsSample", 0, "");
  17. Xlog.setConsoleLogOpen(false);
  18. }
  19.  
  20. Log.setLogImp(new Xlog());

程序退出时关闭日志:

  1. Log.appenderClose();

STN Init

如果你是把 mars-core 作为依赖加入到你的项目中的话,你需要显式的初始化和反初始化 STN

在使用 STN 之前进行初始化

  1. // set callback
  2. AppLogic.setCallBack(stub);
  3. StnLogic.setCallBack(stub);
  4. SdtLogic.setCallBack(stub);
  5.  
  6. // Initialize the Mars PlatformComm
  7. Mars.init(getApplicationContext(), new Handler(Looper.getMainLooper()));
  8.  
  9. // Initialize the Mars
  10. StnLogic.setLonglinkSvrAddr(profile.longLinkHost(), profile.longLinkPorts());
  11. StnLogic.setShortlinkSvrAddr(profile.shortLinkPort());
  12. StnLogic.setClientVersion(profile.productID());
  13. Mars.onCreate(true);
  14. BaseEvent.onForeground(true);
  15.  
  16. StnLogic.makesureLongLinkConnected();

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

需要释放 STN 或者退出程序时:

  1. Mars.onDestroy();

Event Change

网络切换时:

  1. BaseEvent.onNetworkChange()

如果你是把 mars-wrapper 作为依赖加入到你的项目中,你只需要显式的初始化 STN,不需要反初始化(因为 mars-wrapper 会进行反初始化)

  1. MarsServiceProxy.init(this, getMainLooper(),null);

不管你是使用 mars-wrapper 还是 mars-core,你都需要特别注意以下事件:

前后台切换:

  1. BaseEvent.onForeground(boolean);

应用的账号信息更改:

  1. StnLogic.reset();

如果你想修改 Xlog 的加密算法或者长短连的加解包部分甚至更改组件的其他部分,可以参考这里

iOS/OS X

编译

  1. python build_ios.py

or

  1. python build_osx.py

把 mars.framework 作为依赖加入到你的项目中,把mars/libraries/mars_android_sdk/jni 目录的后缀名为 rewriteme 的文件名删掉".rewriteme"和头文件一起加入到你的项目中。

Xlog Init

在程序启动加载 Xlog 后紧接着初始化 Xlog。但要注意保存 log 的目录请使用单独的目录,不要存放任何其他文件防止被 xlog 自动清理功能误删。

  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 xlogger
  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", 0, "");

在函数 "applicationWillTerminate" 中反初始化 Xlog

  1. appender_close();

STN Init

在你用 STN 之前初始化:

  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(isForground);
  40. }
  41.  
  42. - (void)makesureLongLinkConnect {
  43. mars::stn::MakesureLonglinkConnected();
  44. }

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

需要释放 STN 或者退出程序时:

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

Event Change

前后台切换时:

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

网络切换时:

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

Windows

安装Visual Studio 2015

编译

  1. python build_windows.py

把 mars.lib作为依赖加入到你的项目中,把mars/libraries/mars_android_sdk/jni 目录的后缀名为 rewriteme 的文件名删掉".rewriteme"和头文件一起加入到你的项目中。

Xlog Init

在程序启动加载 Xlog 后紧接着初始化 Xlog。但要注意保存 log 的目录请使用单独的目录,不要存放任何其他文件防止被 xlog 自动清理功能误删。

  1. std::string logPath = ""; //use your log path
  2. std::string pubKey = ""; //use you pubkey for log encrypt
  3.  
  4. // init xlog
  5. #if DEBUG
  6. xlogger_SetLevel(kLevelDebug);
  7. appender_set_console_log(true);
  8. #else
  9. xlogger_SetLevel(kLevelInfo);
  10. appender_set_console_log(false);
  11. #endif
  12. appender_open(kAppednerAsync, logPath.c_str(), "Test", 0, pubKey.c_str());

在程序退出前反初始化 Xlog

  1. appender_close();

STN Init

在你用 STN 之前初始化:

  1. void setShortLinkDebugIP(const std::string& _ip, unsigned short _port)
  2. {
  3. mars::stn::SetShortlinkSvrAddr(_port, _ip);
  4. }
  5. void setShortLinkPort(unsigned short _port)
  6. {
  7. mars::stn::SetShortlinkSvrAddr(_port, "");
  8. }
  9. void setLongLinkAddress(const std::string& _ip, unsigned short _port, const std::string& _debug_ip)
  10. {
  11. vector<uint16_t> ports;
  12. ports.push_back(_port);
  13. mars::stn::SetLonglinkSvrAddr(_ip, ports, _debug_ip);
  14. }
  15.  
  16. void Init()
  17. {
  18. mars::stn::SetCallback(mars::stn::StnCallBack::Instance());
  19. mars::app::SetCallback(mars::app::AppCallBack::Instance());
  20. mars::baseevent::OnCreate();
  21.  
  22. //todo
  23. //mars::stn::SetClientVersion(version);
  24. //setShortLinkDebugIP(...)
  25. //setLongLinkAddress(...)
  26.  
  27. mars::baseevent::OnForeground(true);
  28. mars::stn::MakesureLonglinkConnected();
  29. }

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

需要释放 STN 或者退出程序时:

  1. mars::baseevent::OnDestroy();

Support

还有其他问题?

Contributing

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

License

Mars 使用的 MIT 协议,详细请参考 LICENSE