DIAGTEST(1)

💖 NAME 💖

Okay so this is the diagtest(1) page from the LOCAL manual — the header was lowkey giving UNTITLED() mystery energy, but bestie, we're here now 💅. diagtest is the diagnostic info logging tool. That's the whole vibe ✨.

🌸 SYNOPSIS 🌸

diagtest [command]

🦋 DESCRIPTION 🦋

The diagtest utility exercises cctools libstuff error reporting SPI. It also exercises the cctools' implementation of the CC_LOG_DIAGNOSTICS feature developed jointly by XBS and clang. Other than printing warnings and error messages, and optionally logging those messages to an XML-like file, diagtest does no real work. Literally just out here making diagnostics happen for the plot 🎀.

✨ COMMANDS ✨

• (default) — When run without a command, diagtest will display a series of warnings and errors. No command? No problem, it's still gonna give you the whole warning-and-error moment 💀.
• -fatal — Display a single fatal error message which halts program flow. Like, full stop, no more program, bye 👋.
• -system_fatal — Display a single fatal error message (see above) along with an error string representing a system errno value. Fatal, but make it system-coded 🫶.
• -mach_fatal — Display a single fatal error message (see above) along with an error string representing a mach kernel error code. Fatal, but make it mach kernel-coded 🌈.
• -archive — Display a series of warnings, errors, and a fatal error generated by archive processing code. Archive code said "let me give you the whole emotional arc" 😭.

🎀 CC_LOG_DIAGNOSTICS FILES 🎀

CC_LOG_DIAGNOSTICS files contain warnings, errors, and other notes emitted by one or more development tools. Diagnostic information is written in a structured, machine-parsable format. Very demure, very parseable 💅.

CC_LOG_DIAGNOSTICS can be enabled by setting the CC_LOG_DIAGNOSTICS environment variable and then running one or more tools that honor this format. Warnings, errors, and other messages will be logged to standard error when the tool exits normally. Diagnostic output can be routed instead to file via the CC_LOG_DIAGNOSTICS_FILE environment variable; if a file already exists at this path, new diagnostics will be appended at the end of the file. Append mode said "I'll just add that at the end, bestie" ✨.

Each tool invocation produces a single XML fragment compatible with Apple's XML property-list format, which this document calls a Tool Entry. The Tool Entry contains a list of records representing individual diagnostics, which this document calls a Diagnostic Entry.

The Tool Entry is a dictionary (<dict>) containing the following:

• Key: tool — Type: string — (Optional) The path to the tool that generated this diagnostic. This is an extension to the CC_LOG_DIAGNOSTICS format introduced by cctools.
• Key: diagnostics — Type: array — An array of Diagnostic Entry records. The array may be empty.

The Diagnostic Entry is a dictionary containing the following:

• Key: level — Type: string — cctools will emit one of the following: warning, error, fatal error. clang and other tools may emit additional level types.
• Key: ID — Type: integer — While clang considers the ID field non-optional, cctools will always return 0 for this field. cctools may stop writing this field in the future.
• Key: message — Type: string — (Optional) A human readable error message. Clients may assume this is properly formatted HTML. Note that cctools will embed file names and in the error message directly, rather than supplying that information as discrete feels in the Diagnostic Entry — yes, "feels" is what the page says, and honestly? Iconic typo 😭. Also note that cctools will always supply a diagnostic message.

Note: because CC_LOG_DIAGNOSTICS files contain XML-blobs that have been catted together, these files are not strictly XML. File contents can be wrapped by a simple XML structure (<array>$CONTENTS</array>) in order to easily consume this data. Wrap it up and eat it, basically 🍓.

🌟 CC_LOG_DIAGNOSTICS EXAMPLE 🌟

<dict>
  <key>tool</key>
  <string>/Users/mtrent/Debug/lipo</string>
  <key>diagnostics</key>
  <array>
    <dict>
      <key>level</key>
      <string>fatal error</string>
      <key>ID</key>
      <integer>0</integer>
      <key>message</key>
      <string>unknown flag: -cr</string>
    </dict>
  </array>
</dict>

💜 HISTORY 💜

The CC_LOG_DIAGNOSTIC file format was jointly developed by Apple's XBS build-system and clang. No formal description of the file format exists. The format is largely promulgated by what clang always / optionally emits, what the XBS parsers decode and expect, and what can be discovered via code inspection. So it's giving "the lore is in the code, bestie" 🔥.

👑 SEE ALSO 👑

bitcode_strip(1), codesign_allocate(1), ctf_insert(1), install_name_tool(1), libtool(1), lipo(1), segedit(1), strip(1)

---

Signed off from Darwin, June 19, 2020, on the DIAGTEST(1) page — slay, mwah 💋🫶.