B::Xref(3perl)

NAME 💖

B::Xref — bestie, it generates cross reference reports for Perl programs, no cap.

(yeah you're on the B::Xref(3perl) page, part of the Perl Programmers Reference Guide, and it's genuinely one of the cutest little backend modules out there)

---

SYNOPSIS ✨

perl -MO=Xref[,OPTIONS] foo.pl

like that's it, that's the whole vibe check 🎀

---

DESCRIPTION 🦋

okay so B::Xref makes a cross reference listing of all the definitions and uses of variables, subroutines, and formats inside a Perl program. It's implemented as a backend for the Perl compiler — so it's not out here doing its own parsing, it's riding the compiler's coattails fr fr.

The report it spits out looks like this:

    File filename1
      Subroutine subname1
        Package package1
          object1        line numbers
          object2        line numbers
          ...
        Package package2
        ...

Every File section reports on a single file, one file per section, no mixing. And every Subroutine section reports on a single subroutine — except for the two special cases, "(definitions)" and "(main)". Those two are doing their own thing: "(definitions)" reports on subroutine definitions found by the initial symbol table walk, and "(main)" reports on the main part of the program or module that lives external to all subroutines. iconic behavior honestly 💅

Then the whole report gets grouped by the Package of each variable, subroutine or format — with one special case, "(lexicals)", which means lexical variables. Every object name (implicitly qualified by the Package it's sitting in, bestie) includes its type character(s) at the beginning where possible. Lexicals are lowkey the easiest to track and they even get dereferencing information included where possible. slay.

The "line numbers" are a comma separated list of line numbers where that object is used in some way, and some of them have code letters in front. Simple uses? no code letter, they're just out here existing. Introductions (like when a lexical first gets defined with my) get the letter "i". Subroutine and method calls get the character "&". Subroutine definitions get "s" and format definitions get "f". periodt.

For instance, here's part of the report from the pod2man program that comes with Perl:

  Subroutine clear_noremap
    Package (lexical)
      $ready_to_print   i1069, 1079
    Package main
      $&                1086
      $.                1086
      $0                1086
      $1                1087
      $2                1085, 1085
      $3                1085, 1085
      $ARGV             1086
      %HTML_Escapes     1085, 1085

So what's this telling us 👀 This is the variables used in the subroutine "clear_noremap". The variable $ready_to_print is a my() (lexical) variable — it's introduced (first declared with my()) on line 1069, and used on line 1079. The variable $& from the main package is used on 1086, and so on down the list. see how the i is doing all the heavy lifting there 🫶

A line number may be prefixed by a single letter:

• i — Lexical variable introduced (declared with my()) for the first time.
• & — Subroutine or method call.
• s — Subroutine defined.
• r — Format defined.

ngl the most useful option the cross referencer has is saving the report to a separate file instead of dumping it all over your terminal. So for instance, to save the report on myperlprogram to the file report:

$ perl -MO=Xref,-oreport myperlprogram

obsessed. go off, -o 🍓

---

OPTIONS 👑

Option words are separated by commas (not whitespace, bestie, do not put spaces in there) and they follow the usual conventions of compiler backend options.

• -oFILENAME — directs output to FILENAME instead of standard output. yes babe, write it to a file, your scrollback will thank you.
• -r — Raw output. Instead of producing a human-readable report, it outputs a line in machine-readable form for each definition/use of a variable/sub/format. it's giving ✨for the robots✨
• -d — Don't output the "(definitions)" sections. just skip 'em.
• -D[tO] — (Internal) debug options, probably only useful if -r is included. The t option prints the object on the top of the stack as it's being tracked. The O option prints each operator as it's being processed in the execution order of the program. it's giving "I am inside the compiler and I am watching everything" 💀

---

BUGS 😭

okay so not everything is perfect here and we have to be honest:

• Non-lexical variables are quite difficult to track through a program.
• Sometimes the type of a non-lexical variable's use is impossible to determine.
• Introductions of non-lexical non-scalars don't seem to be reported properly.

it's not a bug it's a ✨feature✨ — no bestie, it's a bug, they literally put it under BUGS, read the room 🙈

---

AUTHOR 🌸

Malcolm Beattie, mbeattie@sable.ox.ac.uk. thank you king, we love you 👑

---

and that's the whole page bestie!! this was perl v5.44.0, dated 2026-10-17, and it's the B::Xref(3perl) man page 💜 mwah, go cross reference something and slay 🌈⭐🎀