NWLogging 1.2.6

NWLogging 1.2.6

×

测试已测试✓
Lang语言 Obj-CObjective C
许可证 BSD
发布最新发布2014年12月

由 Leo Vandriel 维护。

NWLogging 1.2.6

  • 由
  • Leonard van Driel

Cocoa的极简主义日志框架。

关于

NWLogging是一个Cocoa日志框架，它提供了类似于NSLog的日志功能。它由一个轻量级的C语言核心组成，配置简单，并且包含一套便于配置和日志访问的工具。

使它特别有用的是日志可以灵活地过滤并指向不同的输出，无论是在源代码中还是在运行时。这使得NWLogging成为一种既能调试又能报告错误的工具，避免了随着项目增长而产生的日志冗余。

入门

您可以在Cocoa或Cocoa Touch应用程序中只需几个步骤就开始使用NWLogging。假设您想将您的应用程序启动时的事件记录下来，在AppDelegate.m文件中

  1. 将NWLCore.h和NWLCore.m添加到您的应用程序目标。

  2. 在您的源文件（在这种情况下为AppDelegate.m）的顶部包含NWLCore.h

    #include "NWLCore.h"

  3. 将日志语句添加到您的代码（在这种情况下为applicationDidFinishLaunching:）

    NWLog(@"Application did finish launching");

  4. 启动您的应用程序（以调试模式）并关注控制台输出

    [12:34:56.789000 AppDelegate.m:123] Application did finish launching

这只是一个最小设置，以演示将NWLogging运行所需的步骤。请参阅项目设置部分以获取详细说明。有关更多示例代码，请查看源代码并查看TouchDemo和MacDemo应用程序。

功能

  • 类似于NSLog的日志功能。

    尽管NWLogging提供了可配置的过滤器和输出，但默认情况下，它只是打印您告诉它的内容。只需将`NSLog`替换为`NWLog`。

  • 基于目标、文件、函数和自定义标签的日志过滤。

    没有无用的日志消息泛滥，而是精确过滤，使您只获取所需的日志。

  • 将日志输出到控制台、文件和自定义打印器。

    默认情况下，所有日志都打印到stderr，但您也可以将其重定向到文件、流或用于应用内显示的文本视图。

  • 其他日志操作，如暂停调试或抛出异常。

    使用日志来处理您的断言和异常。配置应为断言错误触发调试器中断的行。只需将`NSAssert`替换为`NWAssert`。

  • 静态和运行时动态配置

    配置方法在源代码和调试器中都可用。这允许您运行标准配置并在调试期间进一步配置。

  • 支持纯C和C++项目。

    NWLogging的核心不受Objective-C或Cocoa的约束。它只需要标准C和Core Foundation库。

  • 并发，但不锁定。

    为了对应用程序运行时的影响降到最低，NWLogging避免使用线程锁定、堆分配和消息发送。

项目配置

将NWLogging添加到项目配置有多种方式。最适合的方法取决于目标配置、您想使用的组件，以及您的代码与框架的交互程度。本节介绍两种常见的配置：最小核心和静态集成。

最小配置已在入门部分中介绍。简而言之：将NWLCore文件添加到您的项目中，并在需要的地方包含NWLCore头文件。为了避免与其他项目使用冲突，建议不要将NWLCore.m编译到任何共享库中，而只编译到最终的应用程序二进制文件中。

大多数类都是松散耦合的，允许您按需添加组件。或者，您还可以通过CocoaPods包含完整的框架。

pod 'NWLogging', '~> 1.2.6'

要按日志出现的库进行过滤，您应通过定义NWL_LIB预处理器变量来设置库名称，例如，通过将NWL_LIB=$(TARGET_NAME)添加到目标的“预处理器宏”参数中的构建设置。

 Debug    DEBUG=1 NWL_LIB=$(TARGET_NAME)

默认情况下，NWLogging仅在DEBUG配置中启用。要确保在其他配置中也能进行记录，您必须在预处理器中显式设置NWL_LIB。

 Release  NWL_LIB=$(TARGET_NAME)

要检查NWLogging是否设置正确，请在其应用程序的主方法或启动方法中添加以下内容：

NWLog(@"Works like a charm");

运行时，应输出类似于以下内容的信息

[12:34:56.789000 MyApp main.c:012] Works like a charm

完成设置后，现在是时候在如何使用部分进行一些操作了。如果您想获得更深入的概念性理解，请参阅设计部分。

如何使用

如何将文本记录到控制台输出？

NWLog(@"some text");

如何格式化日志语句？

NWLogInfo(@"Works just like %@.", @"NSLog(..)");

如何记录可以稍后过滤的调试文本？

NWLPrintDbug();  // turn on printing of 'dbug' tag
NWLogDbug(@"debug text that is printed");
NWLClearDbug();  // turn off printing of 'dbug' tag
NWLogDbug(@"debug text that is not shown");

如何记录警告文本？

NWLogWarn(@"warning text!");

当条件失败时，如何记录一些警告文本？

NWAssert(1 != 1); // '1 != 1' is printed
NWLBreakWarn();   // turn on breaking of 'warn' tag
NWAssert(1 != 1); // '1 != 1' is printed and the debugger is paused

如何记录NSError？

NSError *error = nil;
[moc executeFetchRequest:request error:&error];
NWError(error);  // if error then print description

如何打印“info”级别的文本？

NWLPrintInfo();  // turn on 'info' tag
NWLogInfo(@"some info");

如何记录与文件I/O相关的文件？

NWLPrintTag("fileio");
NWLogTag(fileio, @"Reading from file: %@", filename);
NWLogTag(fileio, @"Writing to file: %@", filename);

如何查看哪些过滤器和打印程序是激活的？

NWLDump();

设计

概念

NWLogging的三个主要概念是过滤器、动作和打印程序。当执行日志语句时，它首先通过一系列过滤器。匹配日志语句属性的最佳过滤器决定应执行哪种动作。打印程序是一个格式化和输出日志文本及其属性的函数。

过滤器是对日志语句属性的约束集。例如：“应位于X.m文件中”或“应在库Y中，并具有标记Z”。过滤器具有固定的格式，这使它们能够高效地匹配。对于日志语句的每个属性，它要么指定其值，要么不关心该属性。可用的属性有

  • 标签 - 在日志语句中指定的短字符串，例如info或warn。
  • lib - 执行此日志调用的库。
  • 文件 - 执行此日志调用所在文件的名称。
  • 函数 - 执行此日志调用所在函数的名称。

每个过滤器都与其相关联的动作。找到最佳匹配的过滤器后，将日志文本传递给该动作。可用的动作包括

  • 打印 - 将此日志语句转发到所有打印程序。
  • break - 将日志发送到所有打印机并发送SIGINT信号，以便调试器中断。
  • raise - 根据日志文本的理由引发异常。
  • assert - 使用日志文本作为描述断言假。

在大多数情况下，与打印操作相关联的过滤器会将日志文本及其属性传递到打印机函数集。默认打印机方便地格式化日志属性，附加日志文本，并输出到STDERR。与过滤器不同，打印机旨在开放式设计，允许任何格式化和输出，例如文件、流、UI视图等。

之前简短提到的一个重要概念是 标签 的概念。标签提供了一种灵活的方式来控制日志语句的过滤。通过将标签与每个日志语句相关联，也可以根据这些标签控制日志文本的打印，而不仅仅是它们所在的函数、文件或库。默认情况下，NWLogging使用 warn、info 和 dbug 标签，这些标签模仿了在日志框架中经常使用的日志 级别。然而，您可以定义新的标签，以适应不同的模块或代码截面。

核心

NWLogging 由一个用C编写的简单核心和一系列用Objective-C编写的工具组成。核心的设计重点在于简洁性和性能。它有三个主要部分

  1. 通用日志方法用于直接日志和过滤日志。`NWLLogWithoutFilter` 简单地将日志消息转发到所有打印机。`NWLog` 方法基于此。`NWLLogWithFilter` 首先匹配属性（如标签、文件和函数）与可用过滤器，以查看该消息是否需要打印。

  2. 配置方法用于管理过滤器、打印机和时钟。Th

  3. 一系列方便的方法用于一般用途。这些定义了标准的 'Dbug'、'Info' 和 'Warn' 标签，而这些标签在前两个部分中不存在。

工具

NWLogging 工具集重点在于扩展核心到 Cocoa。它提供了 Objective-C 接口到核心功能，使其可以轻松集成到 Cocoa 或 Cocoa Touch 应用程序中。

常见问题解答（FAQ）

为什么我的日志消息没有出现在输出中？

首先确保你的控制台 确实显示了stderr输出，例如，通过使用 NSLog(@"some text") 打印一些文本。现在假设你的控制台已正确设置，以下是一些原因：

  1. 你正在使用一个非活动的标签进行日志记录。例如，要在 'info' 标签上记录，您需要首先激活它

    NWLPrintInfo();  // activate all logging of info tag
NWLogInfo(@"This line should be logged");

    如果您想查看哪些过滤器有效，请使用 NWLDump() 方法，它应该给出类似以下的内容：

    action       : print tag:warn
action       : print tag:info
printer      : default
time-offset  : 0.000000

    可选地，您可以将 NWLogInfo(..) 调用替换为 NWLog(..)，不要 'info'。`NWLog` 总是记录日志，忽略所有过滤器，就像 `NSLog` 一样。

  2. 另一个可能的原因是默认（stderr）打印机未激活。使用以下方法激活默认打印机：

    NWLRestoreDefaultPrinters();

  3. 您可能运行了复杂的过滤器配置，但却不知道哪个过滤器做什么。使用以下方法重置所有过滤器操作：

    NWLRestoreDefaultFilters();

  4. 可能您没有做所有必要的设置。如果您以发布配置运行，则需要显式定义 NWL_LIB。请确保您遵循了项目设置部分中描述的步骤。

    仍然不起作用？给我发一封电子邮件：leonardvandriel at gmail。

有哪些日志级别？

从技术上讲，NWLogging没有日志级别。相反，它提供了标签，与级别提供相同的功能，但更加灵活。有三种默认标签（读取级别）：warn、info、dbug，但你可以使用任何你想要的标签。例如，如果你想在跟踪级别上进行非常细粒度的日志记录，你可以使用

NWLogTag(trace, @"Lots of stuff happening here");

你可以使用以下方式激活跟踪日志：

NWLPrintTag("trace");

请注意，标签没有自然的顺序。激活`dbug`标签并不会自动激活`info`标签。

NWLDump()打印的这些东西是什么意思？

NWLDump()函数在代码和执行的具体点上打印NWLogging配置的内部信息。它可以从调试器和源代码中调用。从源代码调用NWLDump通常提供以下信息

file         : MyClass.m:88
function     : -[MyClass myMethod]

执行特定NWLDump();语句的源代码位置。

DEBUG        : YES

指示此NWLDump调用是否以调试配置编译。默认情况下，NWLogging在调试模式下开启，但在发布模式下禁用。

NWL_LIB      : MyLibName

编译此NWLDump调用的库的名称。此值可以通过在预处理器中设置NWL_LIB=$(TARGET_NAME)来配置。

NWLog macros : YES

如果YES，则NWLogging调用（如NWLog(..)和NWLogInfo(..)）编译到二进制文件中。如果NO，则所有日志调用都被剥离。此值由NWL_LIB宏产生。

action       : print tag=warn

一个活动过滤器列表，格式为：<action> <property>=<value>。可以使用NWLAddFilter(..)添加过滤器。

printer      : default

打印机列表，其中default指stderr打印机。可以使用NWLAddPrinter(..)添加打印机。

time-offset  : 0.000000

应用于所有时间戳的偏移量。可以通过NWLOffsetPrintClock(..)配置。

授权协议

NWLogging根据BSD 2-Clause License的条款进行授权，请参阅所包含的LICENSE文件。

贡献者