| # Debugging components |
| |
| <<../../_common/components/_debugging_intro.md>> |
| |
| <<../../_common/components/_debugging_analyze.md>> |
| |
| ## Exercise: Using the Fuchsia debugger |
| |
| In this exercise, you'll use the Fuchsia debugger (`zxdb`) to inspect a running |
| instance of the `echo-args` component and understand the cause of a crash. |
| |
| <<../_common/_start_femu_with_packages.md>> |
| |
| ### Start a debug session |
| |
| Once the emulator has started up, start a `zxdb` debugging session with the |
| `ffx debug connect` command: |
| |
| ```posix-terminal |
| ffx debug connect |
| ``` |
| |
| ```none {:.devsite-disable-click-to-copy} |
| Connecting (use "disconnect" to cancel)... |
| Connected successfully. |
| 👉 To get started, try "status" or "help". |
| [zxdb] |
| ``` |
| |
| After successfully connecting, the `zxdb` prompt is ready to accept commands. |
| |
| ### Attach to the component |
| |
| Before launching the component, configure `zxdb` to attach to an instance of |
| `echo-args`. This enables the debugger to attach as soon as the process starts: |
| |
| <pre class="devsite-click-to-copy"> |
| <span class="no-select">[zxdb] </span>attach echo-args |
| </pre> |
| |
| Set a breakpoint on the `greeting()` function: |
| |
| <pre class="devsite-click-to-copy"> |
| <span class="no-select">[zxdb] </span>break greeting |
| </pre> |
| |
| With the debugger ready, start a new `echo-args` component instance: |
| |
| |
| ```posix-terminal |
| ffx component run /core/ffx-laboratory:echo-args fuchsia-pkg://fuchsia.com/echo-args#meta/echo-args.cm |
| ``` |
| |
| ### Explore the debug session |
| |
| Upon reaching the breakpoint in `greeting()`, execution stops and the debugger |
| waits for a new command. Use the `list` command to show where execution is |
| currently paused: |
| |
| * {Rust} |
| |
| ```none {:.devsite-disable-click-to-copy} |
| [zxdb] list |
| 18 |
| 19 // Return a proper greeting for the list |
| 20 fn greeting(names: &Vec<String>) -> String { |
| 21 // Join the list of names based on length |
| â–¶ 22 match names.len() { |
| 23 0 => String::from("Nobody"), |
| 24 1 => names.join(""), |
| 25 2 => names.join(" and "), |
| 26 _ => names.join(", "), |
| 27 } |
| 28 } |
| 29 |
| ``` |
| |
| * {C++} |
| |
| ```none {:.devsite-disable-click-to-copy} |
| [zxdb] list |
| 17 |
| 18 // Return a proper greeting for the list |
| â–¶ 19 std::string greeting(std::vector<std::string>& names) { |
| 20 // Join the list of names based on length |
| 21 auto number_of_names = names.size(); |
| 22 switch (number_of_names) { |
| 23 case 0: |
| 24 return "Nobody!"; |
| 25 case 1: |
| 26 return join(names, ""); |
| 27 case 2: |
| 28 return join(names, " and "); |
| 29 default: |
| ``` |
| |
| The `print` command will output the state of any variables in the current stack |
| frame. Print the current value of `names`: |
| |
| * {Rust} |
| |
| <pre class="devsite-click-to-copy"> |
| <span class="no-select">[zxdb] </span>print names |
| <span class="no-select">vec!["Alice", "Bob", "Spot"]</span> |
| </pre> |
| |
| * {C++} |
| |
| <pre class="devsite-click-to-copy"> |
| <span class="no-select">[zxdb] </span>print names |
| <span class="no-select">{"Alice", "Bob", "Spot"}</span> |
| </pre> |
| |
| Step through the `greeting()` function a few times using the `next` command: |
| |
| <pre class="devsite-click-to-copy"> |
| <span class="no-select">[zxdb] </span>next |
| </pre> |
| |
| To let the program continue to completion, use the `continue` command: |
| |
| <pre class="devsite-click-to-copy"> |
| <span class="no-select">[zxdb] </span>continue |
| </pre> |
| |
| Exit the debugging session to return to the terminal: |
| |
| <pre class="devsite-click-to-copy"> |
| <span class="no-select">[zxdb] </span>exit |
| </pre> |
| |
| ### Introduce some crashing code |
| |
| Next, you'll add some code to `src/main.rs` to cause the component to crash |
| (or panic). Simulate this behavior by adding an `assert!(false)` macro just |
| after the arguments are collected: |
| |
| * {Rust} |
| |
| `echo-args/src/main.rs`: |
| |
| ```rust |
| #[fuchsia::main(logging = true)] |
| async fn main() -> Result<(), anyhow::Error> { |
| // ... |
| |
| {{ '<strong>' }}// Simulate a crash {{ '</strong>' }} |
| {{ '<strong>' }}assert!(false, "fake crash");{{ '</strong>' }} |
| |
| // Print a greeting to syslog |
| info!("Hello, {}!", greeting(&args)); |
| |
| Ok(()) |
| } |
| ``` |
| |
| * {C++} |
| |
| `echo-args/main.cc`: |
| |
| ```cpp |
| int main(int argc, const char* argv[], char* envp[]) { |
| // ... |
| |
| {{ '<strong>' }}// Simulate a crash {{ '</strong>' }} |
| {{ '<strong>' }}std::strlen(nullptr);{{ '</strong>' }} |
| |
| // Print a greeting to syslog |
| FX_LOGS(INFO) << "Hello, " << echo::greeting(arguments) << "!" << std::endl; |
| |
| return 0; |
| } |
| ``` |
| |
| Run `fx build` again to rebuild the component: |
| |
| ```posix-terminal |
| fx build |
| ``` |
| |
| Start a new debug session with `zxdb`: |
| |
| ```posix-terminal |
| ffx debug connect |
| ``` |
| |
| ### Debug the crashing stack frame |
| |
| Configure the debugger to attach to the `echo-args` component: |
| |
| <pre class="devsite-click-to-copy"> |
| <span class="no-select">[zxdb] </span>attach echo-args |
| </pre> |
| |
| Start a new instance of the component: |
| |
| ```posix-terminal |
| ffx component run /core/ffx-laboratory:echo-args fuchsia-pkg://fuchsia.com/echo-args#meta/echo-args.cm |
| ``` |
| |
| This time, the debugger detects that an exception was thrown. Use the `frame` |
| command to inspect the stack trace at the point of the crash: |
| |
| * {Rust} |
| |
| ```none {:.devsite-disable-click-to-copy} |
| [zxdb] frame |
| ▶ 0 abort() • abort.c:7 |
| 1 panic_abort::__rust_start_panic::abort() • panic_abort/src/lib.rs:43 |
| 2 panic_abort::__rust_start_panic(…) • panic_abort/src/lib.rs:38 |
| 3 std::panicking::rust_panic(…) • library/std/src/panicking.rs:672 |
| 4 std::panicking::rust_panic_with_hook(…) • library/std/src/panicking.rs:642 |
| 5 std::panicking::begin_panic::$({closure#0}<&str>)() • rust/library/std/src/panicking.rs:544 |
| 6 std::sys_common::backtrace::$(__rust_end_short_backtrace<std::panicking::begin_panic::{closure#0}, !>)(…) • rust/library/std/src/sys_common/backtrace.rs:144 |
| 7 std::panicking::begin_panic<…>(…) • rust/library/std/src/panicking.rs:543 |
| {{ '<strong>' }}8 echo_args::main::component_entry_point::$({generator#0})(…) • main.rs:18{{ '</strong>' }} |
| 9 core::future::from_generator::$({impl#1})::$(poll<echo_args::main::component_entry_point::{generator#0}>)(…) • rust/library/core/src/future/mod.rs:80 |
| 10 core::future::future::$({impl#1})::$(poll<&mut core::future::from_generator::GenFuture<echo_args::main::component_entry_point::{generator#0}>>)(…) • future/future.rs:119 |
| 11 futures_util::future::future::FutureExt::$(poll_unpin<core::pin::Pin<&mut core::future::from_generator::GenFuture<echo_args::main::component_entry_point::{generator#0}>>>)(…) • future/future/mod.rs:562 |
| 12 fuchsia_async::runtime::fuchsia::executor::local::MainTask::$(poll<core::pin::Pin<&mut core::future::from_generator::GenFuture<echo_args::main::component_entry_point::{generator#0}>>>)(…) • fuchsia/src/lib/fuchsia-async/src/runtime/fuchsia/executor/local.rs:444 |
| 13 fuchsia_async::runtime::fuchsia::executor::local::LocalExecutor::$(run_singlethreaded<core::future::from_generator::GenFuture<echo_args::main::component_entry_point::{generator#0}>>)(…) • fuchsia/src/lib/fuchsia-async/src/runtime/fuchsia/executor/local.rs:73 |
| 14 fuchsia::$(main_singlethreaded<fuchsia::init_logging_for_component_with_executor::{closure#0}, core::future::from_generator::GenFuture<echo_args::main::component_entry_point::{generator#0}>, core::result::Result<(), anyhow::Error>>)(…) • fuchsia/src/lib/fuchsia/src/lib.rs:152 |
| 15 echo_args::main() • main.rs:7 |
| 16 core::ops::function::FnOnce::call_once<…>(…) • /b/s/w/ir/x/w/rust/library/core/src/ops/function.rs:227 |
| 17 std::sys_common::backtrace::__rust_begin_short_backtrace<…>(…) • rust/library/std/src/sys_common/backtrace.rs:125 |
| 18 std::rt::lang_start::$({closure#0}<core::result::Result<(), anyhow::Error>>)() • rust/library/std/src/rt.rs:63 |
| 19 core::ops::function::impls::$({impl#2})::call_once<…>(…) • /b/s/w/ir/x/w/rust/library/core/src/ops/function.rs:259 (inline) |
| 20 std::panicking::try::do_call<…>(…) • library/std/src/panicking.rs:403 (inline) |
| 21 std::panicking::try<…>(…) • library/std/src/panicking.rs:367 (inline) |
| 22 std::panic::catch_unwind<…>(…) • library/std/src/panic.rs:129 (inline) |
| 23 std::rt::lang_start_internal::$({closure#2})() • library/std/src/rt.rs:45 (inline) |
| 24 std::panicking::try::$(do_call<std::rt::lang_start_internal::{closure#2}, isize>)(…) • library/std/src/panicking.rs:403 (inline) |
| 25 std::panicking::$(try<isize, std::rt::lang_start_internal::{closure#2}>)(…) • library/std/src/panicking.rs:367 (inline) |
| 26 std::panic::$(catch_unwind<std::rt::lang_start_internal::{closure#2}, isize>)(…) • library/std/src/panic.rs:129 (inline) |
| 27 std::rt::lang_start_internal(…) • library/std/src/rt.rs:45 |
| 28 std::rt::lang_start<…>(…) • rust/library/std/src/rt.rs:62 |
| 29 $elf(main) + 0x1f |
| 30 «libc startup» (-r expands) |
| 31 «libc startup» (-r expands) |
| 32 $elf(_start) + 0x11 |
| ``` |
| |
| Notice line 8 in the stack trace indicates the point in `src/main.rs` where the |
| crash happened, corresponding to the `assert!()` macro line of code. |
| |
| * {C++} |
| |
| ```none {:.devsite-disable-click-to-copy} |
| [zxdb] frame |
| ▶ 0 strlen(…) • strlen.c:21 |
| {{ '<strong>' }}1 main(…) • main.cc:27{{ '</strong>' }} |
| 2 «libc startup» (-r expands) |
| 3 «libc startup» (-r expands) |
| 4 $elf(_start) + 0x11 |
| ``` |
| |
| Notice line 1 in the stack trace indicates the point in `main.cc` where the |
| crash happened, corresponding to the `nullptr` reference. |
| |
| The current stack frame (frame 0) is deep within the system library, but you |
| can inspect any stack frame by prefixing the command with the frame number from |
| the stack trace. |
| |
| Print the value of the arguments at the point of the crash by passing the |
| frame number as follows: |
| |
| * {Rust} |
| |
| <pre class="devsite-click-to-copy"> |
| <span class="no-select">[zxdb] </span>frame 8 print args |
| <span class="no-select">vec!["Alice", "Bob", "Spot"]</span> |
| </pre> |
| |
| * {C++} |
| |
| <pre class="devsite-click-to-copy"> |
| <span class="no-select">[zxdb] </span>frame 1 print arguments |
| <span class="no-select">{"Alice", "Bob", "Spot"}</span> |
| </pre> |
| |
| Exit the debugging session to return to the terminal: |
| |
| <pre class="devsite-click-to-copy"> |
| <span class="no-select">[zxdb] </span>exit |
| </pre> |
| |
| ### Destroy the instance |
| |
| Clean up the `echo-args` instance using the following command: |
| |
| ```posix-terminal |
| ffx component destroy /core/ffx-laboratory:echo-args |
| ``` |
