========
Glossary
========

.. glossary::
   :sorted:

   code file
   code_file
       The code file is the filename of the binary.

       For example, on Windows, the compiler may produce a ``.dll``
       file--that's the code file.

       This piece of data is only relevant for Windows binaries.


   code id
   code_id
   code identifier
   code_identifier
       The code id is generated when compiling a binary. It's 12 hex characters
       long.

       Example::

           6527E59F9071000


   debug file
   debug_file
       The debug file is the filename of the file that has debug information.

       For example, on Windows, the compiler may produce a ``.dll`` file and
       the debug file would be ``.pdb``.

       On Linux, the compiler may produce a ``.so`` file and the debug file
       would be the same.

       On MacOS, the compiler may produce a ``.dylib`` file and the debug file
       would be the same.


   debug id
   debug_id
   debug identifier
   debug_identifier
       The debug identifier is a string that identifies a specific build of a
       binary. Each build has a different debug identifier, so compiling the
       same binary twice in a row will yield two different debug identifiers.
       It is computed differently depending on the platform.

       Debug identifiers are 33 hexidecimal digits.

       Example::

           B7C0D76AF5EE3B644C4C44205044422E1

       Sometimes, it's shown hyphenated::

           b7c0d76a-f5ee-3b64-4c4c-44205044422e-1

       This debug identifier is the null debug identifier and it means we don't
       know what the debug identifier for the module is::

           000000000000000000000000000000000

       The debug identifier

       .. seealso::

          `Sentry docs on debug information <https://docs.sentry.io/platforms/native/guides/breakpad/data-management/debug-files/identifiers/>`__


   dump_syms
       dump_syms is a tool for parsing the debugging information the compiler
       provides (whether as DWARF or STABS sections in an ELF file or as
       stand-alone PDB files) and writing that information back out in the
       Breakpad symbol file format.

       .. seealso::

          `dump_syms <https://github.com/mozilla/dump_syms>`__
              dump_syms project.


   missing symbol
       Tecken stores symbols files for modules compiled by Mozilla build
       systems as well as system modules from device drivers, video drivers,
       system libraries, and other external things.

       When the Socorro processor processes a minidump, there are occasions
       when modules that Tecken does not have a symbols file for a module
       loaded in memory of the crashed process.

       We call this a "missing symbol".


   symbols
   symbols file
       When compiling a build, the compiler generates binaries with debugging
       symbols in them.

       The build system uses :term:`dump_syms` to extract the debugging symbols
       from the binaries and put them in Breakpad-style symbol files.

       An entry in the symbol file is something like "This set of bytes in this
       binary correspond to function JammyJamJam on line 200 in source file
       jampocalypso.c."

       Let's create a symbol file.

       We can create a new Rust project, build it, then extract symbols from
       it using :term:`dump_syms`::

           $ cargo new testproj
           $ cd testproj
           $ cargo build
           $ dump_syms target/debug/testproj > testproj.sym

       That creates a sym file like this::

           MODULE Linux x86_64 D48F191186D67E69DF025AD71FB91E1F0 testproj
           ...
           FILE 5 /home/willkg/projects/testproj/src/main.rs
           ...
           FUNC 5380 44 0 testproj::main
           5380 9 1 5
           5389 36 2 5
           53bf 5 3 5

       This sym file is 6,809 lines for a "Hello, world!" binary.

       .. seealso::

          `Breakpad symbol format <https://chromium.googlesource.com/breakpad/breakpad/+/HEAD/docs/symbol_files.md>`__
              Specification for Breakpad symbol file format.


   symbolication
       Symbolication is the act of converting an array of addresses and module
       information into symbols of the function in the source code for that
       address.

       Here's an array of modules loaded in memory and a stack defined as an
       array of memory offsets::

           {"jobs": [{
             "memoryMap": [
               [ "firefox.pdb", "5F84ACF1D63667F44C4C44205044422E1" ],
               [ "mozavcodec.pdb", "9A8AF7836EE6141F4C4C44205044422E1" ],
               [ "Windows.Media.pdb", "01B7C51B62E95FD9C8CD73A45B4446C71" ],
               [ "xul.pdb", "09F9D7ECF31F60E34C4C44205044422E1" ],
               // ...
             ],
             "stacks": [[
               [ 3, 6516407 ],
               [ 3, 12856365 ],
               [ 3, 12899916 ],
               [ 3, 13034426 ],
               [ 3, 13581214 ],
               [ 3, 13646510 ],
               // ...
             ]]
           }]}

       We can use the sym files, look up the memory addresses, and find the
       symbols for them. That gets us this::

           0  xul.pdb  mozilla::ConsoleReportCollector::FlushReportsToConsole(unsigned long long, nsIConsoleReportCollector::ReportAction)
           1  xul.pdb  mozilla::net::HttpBaseChannel::MaybeFlushConsoleReports()",
           2  xul.pdb  mozilla::net::HttpChannelChild::OnStopRequest(nsresult const&, mozilla::net::ResourceTimingStructArgs const&, mozilla::net::nsHttpHeaderArray const&, nsTArray<mozilla::net::ConsoleReportCollected> const&)
           3  xul.pdb  std::_Func_impl_no_alloc<`lambda at /builds/worker/checkouts/gecko/netwerk/protocol/http/HttpChannelChild.cpp:1001:11',void>::_Do_call()
          ...

       That's symbolication.

       .. seealso::

          `Mozilla Symbolication Server <https://symbolication.services.mozilla.com/>`__

          `Eliot <https://mozilla-eliot.readthedocs.io/>`__
              Documentation for the Mozilla Symbolication Server.


   try symbols
       Engineers can kick off "try" builds in Firefox CI. This allows them to
       test changes on systems other than they one they're doing development
       on as well as perform other build tasks.

       Try builds are ephemeral. They're helpful for a short period of time
       and after that, they're not useful anymore.

       Try builds upload symbols, but since the build is ephemeral, we don't
       want to keep the symbols files forever and ever. Instead, Tecken
       differentiates between symbols from regular builds and try builds,
       stores the files in different places, and expires try build files after
       30 days.

       .. seealso::

          `Tecken download API <https://tecken.readthedocs.io/en/latest/download.html#try-builds>`__
              Documentation on downloading try build symbols with the Tecken
              download API.