NIH-log

A logger for the log crate made specifically to cater to the needs of the NIH-plug plugin framework.

Features

• Log messages are formatted similarly to simplelog. Because simplelog is great.
• By default the log output goes to STDERR, unless a Windows debugger is attached. In that case the output is sent to the Windows debugger using the OutputDebugString() function. This check is performed at runtime to accommodate debuggers being attached to already running processes.

• The log's output target can be changed by setting the NIH_LOG environment variable:

  • A value of stderr causes the log to be printed to STDERR.
  • A value of windbg causes the log to be output to the Windows debugger.
  • Anything else is interpreted as a file name, which causes the log to be written to that file instead.

  The latter two options are useful on Windows where accessing the standard IO streams may be difficult.

• If NIH_LOG is not set, then a dynamic logging output target is used instead. On Windows this causes log messages to be sent to the Windows debugger when one is attached. This check is done just before printing the message to make it possible to attach a debugger to a running process. When the debugger is not attached the output goes directly to STDERR. On non-Windows platforms STDERR is always used.

• (not yet implemented) The logger's output can be changed to output to a custom function after the logger has been created. This makes it possible to integrate with external logging APIs that are not yet available when the logger is first initialized, like the CLAP plugin API's logging extension.
  • This API can be used multiple times, for instance by multiple CLAP plugin instances that have all received their own logger instance from the host. In that case all registered loggers are kept track of in a queue, and the first still active one is used.
  • If NIH_LOG was set explicitly, then this is honored and the regular behavior won't be overridden.
• Because NIH-log is opinionated for use with NIH-plug, it only exposes the bare minimum of settings by design. The only configuration options are to control the output target and to filter out log messages based on the crate and module they're sent from.
• The logger itself does not try to be realtime-safe. It does however try use buffered IO with small pre-allocated buffers for to avoid tripping assert_no_alloc when performing debug prints from a realtime context.