Permalink
Browse files

Added overview of the debuginfo module at the beginning of debuginfo.rs.

  • Loading branch information...
michaelwoerister committed Jun 18, 2013
1 parent 7375e94 commit 5d5311dc74b2bce19a754538dfd3c849e8c989ed
Showing with 26 additions and 0 deletions.
  1. +26 −0 src/librustc/middle/trans/debuginfo.rs
@@ -8,6 +8,32 @@
// option. This file may not be copied, modified, or distributed
// except according to those terms.
/*!
# Debug Info Module
This module serves the purpose of generating debug symbols. We use LLVM's
[source level debugging](http://llvm.org/docs/SourceLevelDebugging.html) features for generating
the debug information. The general principle is this:
Given the right metadata in the LLVM IR, the LLVM code generator is able to create DWARF debug
symbols for the given code. The [metadata](http://llvm.org/docs/LangRef.html#metadata-type) is
structured much like DWARF *debugging information entries* (DIE), representing type information
such as datatype layout, function signatures, block layout, variable location and scope information,
etc. It is the purpose of this module to generate correct metadata and insert it into the LLVM IR.
As the exact format of metadata trees may change between different LLVM versions, we now use LLVM
[DIBuilder](http://llvm.org/docs/doxygen/html/classllvm_1_1DIBuilder.html) which to create metadata
where possible. This will hopefully ease the adaption of this module to future LLVM versions.
The public API of the module is a set of functions that will insert the correct metadata into the
LLVM IR when called with the right parameters. The module is thus driven from an outside client with
function like `debuginfo::create_local_var(bcx: block, local: @ast::local)`.
Internally the module will try to reuse already created metadata by utilizing a cache. All private
state used by the module is stored within a DebugContext struct, which in turn is contained in the
CrateContext.
*/
use core::prelude::*;
use driver::session;

0 comments on commit 5d5311d

Please sign in to comment.