modules/dbgfmts/yasm_dbgfmts.xml

<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id="yasm_dbgfmts">

 <refentryinfo>
  <title>Yasm Supported Debug Formats</title>
  <date>October 2006</date>
  <productname>Yasm</productname>
  <author>
   <firstname>Peter</firstname>
   <surname>Johnson</surname>
   <affiliation>
    <address><email>peter@tortall.net</email></address>
   </affiliation>
  </author>

  <copyright>
   <year>2006</year>
   <holder>Peter Johnson</holder>
  </copyright>
 </refentryinfo>

 <refmeta>
  <refentrytitle>yasm_dbgfmts</refentrytitle>
  <manvolnum>7</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>yasm_dbgfmts</refname>
  <refpurpose>Yasm Supported Debugging Formats</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>yasm</command>
   <arg choice="plain">
    <option>-g <replaceable>dbgfmt</replaceable></option>
   </arg>
   <arg choice="plain">
    <option><replaceable>...</replaceable></option>
   </arg>
  </cmdsynopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>The standard Yasm distribution includes a number of modules
   for different debugging formats.  The debugging information is
   embedded into the object file.  Use of a non-<quote>null</quote>
   debug format also causes Yasm to output all symbols to the object
   file (including local symbols).</para>

  <para>The debug format is selected on the
   
   <citerefentry>
    <refentrytitle>yasm</refentrytitle>
    <manvolnum>1</manvolnum>
   </citerefentry>
   
   command line by use of the <option>-g
    <replaceable>dbgfmt</replaceable></option> command line
   option.</para>
 </refsect1>

 <refsect1>
  <title>cv8</title>

  <para>The CV8 debug format is used by Microsoft Visual Studio 2005
   (version 8.0) and is completely undocumented, although it bears
   strong similarities to earlier CodeView formats.  Yasm's support
   for the CV8 debug format is currently limited to generating
   assembly-level line number information (to allow some level of
   source-level debugging).  The CV8 debug information is stored in
   the .debug$S and .debug$T sections of the Win64 object file.</para>
 </refsect1>

 <refsect1>
  <title>dwarf2</title>

  <para>The DWARF 2 debug format is a complex, well-documented
   standard for debugging information.  It was created to overcome
   shortcomings in STABS, allowing for much more detailed and compact
   descriptions of data structures, data variable movement, and
   complex language structures such as in C++.  The debugging
   information is stored in sections (just like normal program
   sections) in the object file.  Yasm supports full pass-through of
   DWARF2 debugging information (e.g. from a C++ compiler), and can
   also generate assembly-level line number information.</para>
 </refsect1>

 <refsect1>
  <title>null</title>

  <para>The <quote>null</quote> debug format is a placeholder; it adds
   no debugging information to the output file.</para>
 </refsect1>

 <refsect1>
  <title>stabs</title>

  <para>The STABS debug format is a poorly documented, semi-standard
   format for debugging information in COFF and ELF object files.  The
   debugging information is stored as part of the object file's symbol
   table and thus is limited in complexity and scope.  Despite this,
   STABS is a common debugging format on older Unix and compatible
   systems, as well as DJGPP.</para>
 </refsect1>

 <refsect1>
  <title>See Also</title>

  <para><citerefentry>
   <refentrytitle>yasm</refentrytitle>
   <manvolnum>1</manvolnum>
  </citerefentry>,

  <citerefentry>
   <refentrytitle>yasm_objfmts</refentrytitle>
   <manvolnum>7</manvolnum>
  </citerefentry></para>
 </refsect1>
</refentry>