Add Natvis visualizations for the some widestring types

Cargo.toml

@@ -17,8 +17,20 @@ default = ["std"]
 std = ["alloc"]
 alloc = []
 
+# UNSTABLE FEATURES (requires Rust nightly)
+# Enable to use the #[debugger_visualizer] attribute.
+debugger_visualizer = ["alloc"]
+
 [dev-dependencies]
+debugger_test = "0.1"
+debugger_test_parser = "0.1"
 winapi = { version = "0.3", features = ["winbase"] }
 
 [package.metadata.docs.rs]
 rustc-args = ["--cfg", "docsrs"]
+
+[[test]]
+name = "debugger_visualizer"
+path = "tests/debugger_visualizer.rs"
+required-features = ["debugger_visualizer"]
+test = false

Makefile.toml

@@ -5,6 +5,7 @@ min_version = "0.35.0"
 CI_CARGO_TEST_FLAGS = { value = "--locked -- --nocapture", condition = { env_true = [
     "CARGO_MAKE_CI",
 ] } }
+CARGO_MAKE_CARGO_ALL_FEATURES = { source = "${CARGO_MAKE_RUST_CHANNEL}", default_value = "--features=std", mapping = { "nightly" = "--all-features" } }
 CARGO_MAKE_CLIPPY_ARGS = { value = "${CARGO_MAKE_CLIPPY_ALL_FEATURES_WARN}", condition = { env_true = [
     "CARGO_MAKE_CI",
 ] } }
@@ -42,7 +43,7 @@ args = [
 
 # Build & Test with no features enabled
 [tasks.post-ci-flow]
-run_task = [{ name = ["check-docs", "build-no-std", "test-no-std", "build-alloc", "test-alloc"] }]
+run_task = [{ name = ["check-docs", "build-no-std", "test-no-std", "build-alloc", "test-alloc", "build-debugger-visualizer", "test-debugger-visualizer"]}]
 
 [tasks.build-no-std]
 description = "Build without any features"
@@ -67,3 +68,20 @@ description = "Run tests with only the alloc feature"
 category = "Test"
 env = { CARGO_MAKE_CARGO_BUILD_TEST_FLAGS = "--no-default-features --features=alloc" }
 run_task = "test"
+
+[tasks.build-debugger-visualizer]
+condition = { channels = ["nightly"] }
+description = "Build with only the debugger_visualizer feature"
+category = "Build"
+env = { CARGO_MAKE_CARGO_BUILD_TEST_FLAGS = "--no-default-features --features=debugger_visualizer" }
+run_task = "build"
+
+# The debugger_visualizer tests rely on debug information being present.
+# Update the debuginfo level for this task only.
+[tasks.test-debugger-visualizer]
+condition = { channels = ["nightly"] }
+description = "Run tests with only the debugger_visualizer feature which includes the alloc feature"
+category = "Test"
+env = { CARGO_MAKE_CARGO_BUILD_TEST_FLAGS = "--test debugger_visualizer --no-default-features --features=debugger_visualizer", CI_CARGO_TEST_FLAGS = "--locked -- --nocapture --test-threads=1", CARGO_PROFILE_TEST_DEBUG = 2 }
+run_task = "test"
+dependencies = ["build-debugger-visualizer"]

debug_metadata/README.md

@@ -0,0 +1,111 @@
+## Debugger Visualizers
+
+Many languages and debuggers enable developers to control how a type is
+displayed in a debugger. These are called "debugger visualizations" or "debugger
+views".
+
+The Windows debuggers (WinDbg\CDB) support defining custom debugger visualizations using
+the `Natvis` framework. To use Natvis, developers write XML documents using the natvis
+schema that describe how debugger types should be displayed with the `.natvis` extension.
+(See: https://docs.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects?view=vs-2019)
+The Natvis files provide patterns which match type names a description of how to display
+those types.
+
+The Natvis schema can be found either online (See: https://code.visualstudio.com/docs/cpp/natvis#_schema)
+or locally at `<VS Installation Folder>\Xml\Schemas\1033\natvis.xsd`.
+
+The GNU debugger (GDB) supports defining custom debugger views using Pretty Printers.
+Pretty printers are written as python scripts that describe how a type should be displayed
+when loaded up in GDB/LLDB. (See: https://sourceware.org/gdb/onlinedocs/gdb/Pretty-Printing.html#Pretty-Printing)
+The pretty printers provide patterns, which match type names, and for matching
+types, descibe how to display those types. (For writing a pretty printer, see: https://sourceware.org/gdb/onlinedocs/gdb/Writing-a-Pretty_002dPrinter.html#Writing-a-Pretty_002dPrinter).
+
+### Embedding Visualizers
+
+Through the use of the currently unstable `#[debugger_visualizer]` attribute, the `widestring`
+crate can embed debugger visualizers into the crate metadata.
+
+Currently the two types of visualizers supported are Natvis and Pretty printers.
+
+For Natvis files, when linking an executable with a crate that includes Natvis files,
+the MSVC linker will embed the contents of all Natvis files into the generated `PDB`.
+
+For pretty printers, the compiler will encode the contents of the pretty printer
+in the `.debug_gdb_scripts` section of the `ELF` generated.
+
+### Testing Visualizers
+
+The `widestring` crate supports testing debugger visualizers defined for this crate. The entry point for
+these tests are `tests/test_visualizer.rs`. These tests are defined using the `debugger_test` and
+`debugger_test_parser` crates. The `debugger_test` crate is a proc macro crate which defines a
+single proc macro attribute, `#[debugger_test]`. For more detailed information about this crate,
+see https://crates.io/crates/debugger_test. The CI pipeline for the `widestring` crate has been updated
+to run the debugger visualizer tests to ensure debugger visualizers do not become broken/stale.
+
+The `#[debugger_test]` proc macro attribute may only be used on test functions and will run the
+function under the debugger specified by the `debugger` meta item.
+
+This proc macro attribute has 3 required values:
+
+1. The first required meta item, `debugger`, takes a string value which specifies the debugger to launch.
+2. The second required meta item, `commands`, takes a string of new line (`\n`) separated list of debugger
+commands to run.
+3. The third required meta item, `expected_statements`, takes a string of new line (`\n`) separated list of
+statements that must exist in the debugger output. Pattern matching through regular expressions is also
+supported by using the `pattern:` prefix for each expected statement.
+
+#### Example:
+
+```rust
+#[debugger_test(
+    debugger = "cdb",
+    commands = "command1\ncommand2\ncommand3",
+    expected_statements = "statement1\nstatement2\nstatement3")]
+fn test() {
+
+}
+```
+
+Using a multiline string is also supported, with a single debugger command/expected statement per line:
+
+```rust
+#[debugger_test(
+    debugger = "cdb",
+    commands = "
+command1
+command2
+command3",
+    expected_statements = "
+statement1
+pattern:statement[0-9]+
+statement3")]
+fn test() {
+
+}
+```
+
+In the example above, the second expected statement uses pattern matching through a regular expression
+by using the `pattern:` prefix.
+
+#### Testing Locally
+
+Currently, only Natvis visualizations have been defined for the `widestring` crate via `debug_metadata/widestring.natvis`,
+which means the `tests/debugger_visualizer.rs` tests need to be run on Windows using the `*-pc-windows-msvc` targets.
+To run these tests locally, first ensure the debugging tools for Windows are installed or install them following
+the steps listed here, [Debugging Tools for Windows](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/).
+Once the debugging tools have been installed, the tests can be run in the same manner as they are in the CI
+pipeline.
+
+#### Note
+
+When running the debugger visualizer tests, `tests/debugger_visualizer.rs`, they need to be run consecutively
+and not in parallel. This can be achieved by passing the flag `--test-threads=1` to rustc. This is due to
+how the debugger tests are run. Each test marked with the `#[debugger_test]` attribute launches a debugger
+and attaches it to the current test process. If tests are running in parallel, the test will try to attach
+a debugger to the current process which may already have a debugger attached causing the test to fail.
+
+For example:
+
+```
+cargo test --test debugger_visualizer --features debugger_visualizer -- --test-threads=1
+```

debug_metadata/widestring.natvis

@@ -0,0 +1,100 @@
+<?xml version="1.0" encoding="utf-8"?>
+<AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">
+  <Type Name="widestring::ucstr::U16CStr">
+    <DisplayString>{(char16_t*)this,su}</DisplayString>
+  </Type>
+
+  <Type Name="widestring::ucstr::U32CStr">
+    <DisplayString>{(char32_t*)this,s32}</DisplayString>
+  </Type>
+
+  <Type Name="widestring::ucstring::U16CString">
+    <DisplayString>{(char16_t*)inner.data_ptr,[inner.length]su}</DisplayString>
+    <Expand>
+      <Item Name="[len]" ExcludeView="simple">inner.length</Item>
+      <Synthetic Name="[chars]">
+        <Expand>
+          <ArrayItems>
+            <Size>inner.length</Size>
+            <ValuePointer>(char16_t*)inner.data_ptr</ValuePointer>
+          </ArrayItems>
+        </Expand>
+      </Synthetic>
+    </Expand>
+  </Type>
+
+  <Type Name="widestring::ucstring::U32CString">
+    <DisplayString>{(char32_t*)inner.data_ptr,[inner.length]s32}</DisplayString>
+    <Expand>
+      <Item Name="[len]" ExcludeView="simple">inner.length</Item>
+      <Synthetic Name="[chars]">
+        <Expand>
+          <ArrayItems>
+            <Size>inner.length</Size>
+            <ValuePointer>(char32_t*)inner.data_ptr</ValuePointer>
+          </ArrayItems>
+        </Expand>
+      </Synthetic>
+    </Expand>
+  </Type>
+
+  <Type Name="widestring::ustring::U16String">
+    <DisplayString>{(char16_t*)inner.buf.ptr.pointer.pointer,[inner.len]su}</DisplayString>
+    <Expand>
+      <Item Name="[len]" ExcludeView="simple">inner.len</Item>
+      <Synthetic Name="[chars]">
+        <Expand>
+          <ArrayItems>
+            <Size>inner.len</Size>
+            <ValuePointer>(char16_t*)inner.buf.ptr.pointer.pointer</ValuePointer>
+          </ArrayItems>
+        </Expand>
+      </Synthetic>
+    </Expand>
+  </Type>
+
+  <Type Name="widestring::ustring::U32String">
+    <DisplayString>{(char32_t*)inner.buf.ptr.pointer.pointer,[inner.len]s32}</DisplayString>
+    <Expand>
+      <Item Name="[len]" ExcludeView="simple">inner.len</Item>
+      <Synthetic Name="[chars]">
+        <Expand>
+          <ArrayItems>
+            <Size>inner.len</Size>
+            <ValuePointer>(char32_t*)inner.buf.ptr.pointer.pointer</ValuePointer>
+          </ArrayItems>
+        </Expand>
+      </Synthetic>
+    </Expand>
+  </Type>
+
+  <Type Name="widestring::utfstring::Utf16String">
+    <DisplayString>{(char16_t*)inner.buf.ptr.pointer.pointer,[inner.len]su}</DisplayString>
+    <Expand>
+      <Item Name="[len]" ExcludeView="simple">inner.len</Item>
+      <Synthetic Name="[chars]">
+        <Expand>
+          <ArrayItems>
+            <Size>inner.len</Size>
+            <ValuePointer>(char16_t*)inner.buf.ptr.pointer.pointer</ValuePointer>
+          </ArrayItems>
+        </Expand>
+      </Synthetic>
+    </Expand>
+  </Type>
+
+  <Type Name="widestring::utfstring::Utf32String">
+    <DisplayString>{(char32_t*)inner.buf.ptr.pointer.pointer,[inner.len]s32}</DisplayString>
+    <Expand>
+      <Item Name="[len]" ExcludeView="simple">inner.len</Item>
+      <Synthetic Name="[chars]">
+        <Expand>
+          <ArrayItems>
+            <Size>inner.len</Size>
+            <ValuePointer>(char32_t*)inner.buf.ptr.pointer.pointer</ValuePointer>
+          </ArrayItems>
+        </Expand>
+      </Synthetic>
+    </Expand>
+  </Type>
+</AutoVisualizer>

src/lib.rs

@@ -224,6 +224,11 @@
 #![doc(html_root_url = "https://docs.rs/widestring/1.0.2")]
 #![doc(test(attr(deny(warnings), allow(unused))))]
 #![cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(
+    feature = "debugger_visualizer",
+    feature(debugger_visualizer),
+    debugger_visualizer(natvis_file = "../debug_metadata/widestring.natvis")
+)]
 
 #[cfg(feature = "alloc")]
 extern crate alloc;

tests/debugger_visualizer.rs

@@ -0,0 +1,92 @@
+use debugger_test::debugger_test;
+use widestring::*;
+
+#[inline(never)]
+fn __break() {}
+
+#[debugger_test(
+    debugger = "cdb",
+    commands = r#"
+.nvlist
+dx u16_string
+
+dx u32_string
+
+dx u16_cstring
+
+dx u32_cstring
+
+dx utf16_string
+
+dx utf32_string
+
+dx u16_cstr
+
+dx u32_cstr
+"#,
+    expected_statements = r#"
+u16_string       : "my u16 string" [Type: widestring::ustring::U16String]
+[<Raw View>]     [Type: widestring::ustring::U16String]
+[len]            : 0xd [Type: unsigned __int64]
+[chars]
+
+u32_string       : "my u32 string" [Type: widestring::ustring::U32String]
+[<Raw View>]     [Type: widestring::ustring::U32String]
+[len]            : 0xd [Type: unsigned __int64]
+[chars]
+
+u16_cstring      : "my u16 cstring" [Type: widestring::ucstring::U16CString]
+[<Raw View>]     [Type: widestring::ucstring::U16CString]
+[len]            : 0xf [Type: unsigned __int64]
+[chars]
+
+u32_cstring      : "my u32 cstring" [Type: widestring::ucstring::U32CString]
+[<Raw View>]     [Type: widestring::ucstring::U32CString]
+[len]            : 0xf [Type: unsigned __int64]
+[chars]
+
+utf16_string     : "my utf16 string" [Type: widestring::utfstring::Utf16String]
+[<Raw View>]     [Type: widestring::utfstring::Utf16String]
+[len]            : 0xf [Type: unsigned __int64]
+[chars]
+
+utf32_string     : "my utf32 string" [Type: widestring::utfstring::Utf32String]
+[<Raw View>]     [Type: widestring::utfstring::Utf32String]
+[len]            : 0xf [Type: unsigned __int64]
+[chars]
+
+u16_cstr         [Type: ref$<widestring::ucstr::U16CStr>]
+pattern:\[\+0x000\] data_ptr         : 0x[0-9a-f]+ : "my u16 cstr" \[Type: widestring::ucstr::U16CStr \*\]
+[+0x008] length           : 0xc [Type: unsigned __int64]
+
+u32_cstr         [Type: ref$<widestring::ucstr::U32CStr>]
+pattern:\[\+0x000\] data_ptr         : 0x[0-9a-f]+ : "my u32 cstr" \[Type: widestring::ucstr::U32CStr \*\]
+[+0x008] length           : 0xc [Type: unsigned __int64]
+"#
+)]
+fn test_debugger_visualizer() {
+    let u16_string = U16String::from_str("my u16 string");
+    assert!(!u16_string.is_empty());
+
+    let u32_string = U32String::from_str("my u32 string");
+    assert!(!u32_string.is_empty());
+
+    let u16_cstring = U16CString::from_str("my u16 cstring").unwrap();
+    assert!(!u16_cstring.is_empty());
+
+    let u32_cstring = U32CString::from_str("my u32 cstring").unwrap();
+    assert!(!u32_cstring.is_empty());
+
+    let utf16_string = Utf16String::from_str("my utf16 string");
+    assert!(!utf16_string.is_empty());
+
+    let utf32_string = Utf32String::from_str("my utf32 string");
+    assert!(!utf32_string.is_empty());
+
+    let u16_cstr = u16cstr!("my u16 cstr");
+    assert!(!u16_cstr.is_empty());
+
+    let u32_cstr = u32cstr!("my u32 cstr");
+    assert!(!u32_cstr.is_empty());
+    __break(); // #break
+}