text: //===------------ DebugInfo.h - LLVM C API Debug Info API -----------------===//
  //
  //                     The LLVM Compiler Infrastructure
  //
  // This file is distributed under the University of Illinois Open Source
  // License. See LICENSE.TXT for details.
  //
  //===----------------------------------------------------------------------===//
  ///
  /// This file declares the C API endpoints for generating DWARF Debug Info
  ///
  /// Note: This interface is experimental. It is *NOT* stable, and may be
  ///       changed without warning.
  ///
  //===----------------------------------------------------------------------===//
  
  #ifndef LLVM_C_DEBUGINFO_H
  #define LLVM_C_DEBUGINFO_H
  
  #include "llvm-c/Core.h"
  
  #ifdef __cplusplus
  extern "C" {
  #endif
  
  /**
   * Debug info flags.
   */
  typedef enum {
    LLVMDIFlagZero = 0,
    LLVMDIFlagPrivate = 1,
    LLVMDIFlagProtected = 2,
    LLVMDIFlagPublic = 3,
    LLVMDIFlagFwdDecl = 1 << 2,
    LLVMDIFlagAppleBlock = 1 << 3,
    LLVMDIFlagBlockByrefStruct = 1 << 4,
    LLVMDIFlagVirtual = 1 << 5,
    LLVMDIFlagArtificial = 1 << 6,
    LLVMDIFlagExplicit = 1 << 7,
    LLVMDIFlagPrototyped = 1 << 8,
    LLVMDIFlagObjcClassComplete = 1 << 9,
    LLVMDIFlagObjectPointer = 1 << 10,
    LLVMDIFlagVector = 1 << 11,
    LLVMDIFlagStaticMember = 1 << 12,
    LLVMDIFlagLValueReference = 1 << 13,
    LLVMDIFlagRValueReference = 1 << 14,
    LLVMDIFlagReserved = 1 << 15,
    LLVMDIFlagSingleInheritance = 1 << 16,
    LLVMDIFlagMultipleInheritance = 2 << 16,
    LLVMDIFlagVirtualInheritance = 3 << 16,
    LLVMDIFlagIntroducedVirtual = 1 << 18,
    LLVMDIFlagBitField = 1 << 19,
    LLVMDIFlagNoReturn = 1 << 20,
    LLVMDIFlagMainSubprogram = 1 << 21,
    LLVMDIFlagIndirectVirtualBase = (1 << 2) | (1 << 5),
    LLVMDIFlagAccessibility = LLVMDIFlagPrivate | LLVMDIFlagProtected |
                              LLVMDIFlagPublic,
    LLVMDIFlagPtrToMemberRep = LLVMDIFlagSingleInheritance |
                               LLVMDIFlagMultipleInheritance |
                               LLVMDIFlagVirtualInheritance
  } LLVMDIFlags;
  
  /**
   * Source languages known by DWARF.
   */
  typedef enum {
    LLVMDWARFSourceLanguageC89,
    LLVMDWARFSourceLanguageC,
    LLVMDWARFSourceLanguageAda83,
    LLVMDWARFSourceLanguageC_plus_plus,
    LLVMDWARFSourceLanguageCobol74,
    LLVMDWARFSourceLanguageCobol85,
    LLVMDWARFSourceLanguageFortran77,
    LLVMDWARFSourceLanguageFortran90,
    LLVMDWARFSourceLanguagePascal83,
    LLVMDWARFSourceLanguageModula2,
    // New in DWARF v3:
    LLVMDWARFSourceLanguageJava,
    LLVMDWARFSourceLanguageC99,
    LLVMDWARFSourceLanguageAda95,
    LLVMDWARFSourceLanguageFortran95,
    LLVMDWARFSourceLanguagePLI,
    LLVMDWARFSourceLanguageObjC,
    LLVMDWARFSourceLanguageObjC_plus_plus,
    LLVMDWARFSourceLanguageUPC,
    LLVMDWARFSourceLanguageD,
    // New in DWARF v4:
    LLVMDWARFSourceLanguagePython,
    // New in DWARF v5:
    LLVMDWARFSourceLanguageOpenCL,
    LLVMDWARFSourceLanguageGo,
    LLVMDWARFSourceLanguageModula3,
    LLVMDWARFSourceLanguageHaskell,
    LLVMDWARFSourceLanguageC_plus_plus_03,
    LLVMDWARFSourceLanguageC_plus_plus_11,
    LLVMDWARFSourceLanguageOCaml,
    LLVMDWARFSourceLanguageRust,
    LLVMDWARFSourceLanguageC11,
    LLVMDWARFSourceLanguageSwift,
    LLVMDWARFSourceLanguageJulia,
    LLVMDWARFSourceLanguageDylan,
    LLVMDWARFSourceLanguageC_plus_plus_14,
    LLVMDWARFSourceLanguageFortran03,
    LLVMDWARFSourceLanguageFortran08,
    LLVMDWARFSourceLanguageRenderScript,
    LLVMDWARFSourceLanguageBLISS,
    // Vendor extensions:
    LLVMDWARFSourceLanguageMips_Assembler,
    LLVMDWARFSourceLanguageGOOGLE_RenderScript,
    LLVMDWARFSourceLanguageBORLAND_Delphi
  } LLVMDWARFSourceLanguage;
  
  /**
   * The amount of debug information to emit.
   */
  typedef enum {
      LLVMDWARFEmissionNone = 0,
      LLVMDWARFEmissionFull,
      LLVMDWARFEmissionLineTablesOnly
  } LLVMDWARFEmissionKind;
  
  /**
   * The current debug metadata version number.
   */
  unsigned LLVMDebugMetadataVersion(void);
  
  /**
   * The version of debug metadata that's present in the provided \c Module.
   */
  unsigned LLVMGetModuleDebugMetadataVersion(LLVMModuleRef Module);
  
  /**
   * Strip debug info in the module if it exists.
   * To do this, we remove all calls to the debugger intrinsics and any named
   * metadata for debugging. We also remove debug locations for instructions.
   * Return true if module is modified.
   */
  LLVMBool LLVMStripModuleDebugInfo(LLVMModuleRef Module);
  
  /**
   * Construct a builder for a module, and do not allow for unresolved nodes
   * attached to the module.
   */
  LLVMDIBuilderRef LLVMCreateDIBuilderDisallowUnresolved(LLVMModuleRef M);
  
  /**
   * Construct a builder for a module and collect unresolved nodes attached
   * to the module in order to resolve cycles during a call to
   * \c LLVMDIBuilderFinalize.
   */
  LLVMDIBuilderRef LLVMCreateDIBuilder(LLVMModuleRef M);
  
  /**
   * Deallocates the \c DIBuilder and everything it owns.
   * @note You must call \c LLVMDIBuilderFinalize before this
   */
  void LLVMDisposeDIBuilder(LLVMDIBuilderRef Builder);
  
  /**
   * Construct any deferred debug info descriptors.
   */
  void LLVMDIBuilderFinalize(LLVMDIBuilderRef Builder);
  
  /**
   * A CompileUnit provides an anchor for all debugging
   * information generated during this instance of compilation.
   * \param Lang          Source programming language, eg.
   *                      \c LLVMDWARFSourceLanguageC99
   * \param FileRef       File info.
   * \param Producer      Identify the producer of debugging information
   *                      and code.  Usually this is a compiler
   *                      version string.
   * \param ProducerLen   The length of the C string passed to \c Producer.
   * \param isOptimized   A boolean flag which indicates whether optimization
   *                      is enabled or not.
   * \param Flags         This string lists command line options. This
   *                      string is directly embedded in debug info
   *                      output which may be used by a tool
   *                      analyzing generated debugging information.
   * \param FlagsLen      The length of the C string passed to \c Flags.
   * \param RuntimeVer    This indicates runtime version for languages like
   *                      Objective-C.
   * \param SplitName     The name of the file that we'll split debug info
   *                      out into.
   * \param SplitNameLen  The length of the C string passed to \c SplitName.
   * \param Kind          The kind of debug information to generate.
   * \param DWOId         The DWOId if this is a split skeleton compile unit.
   * \param SplitDebugInlining    Whether to emit inline debug info.
   * \param DebugInfoForProfiling Whether to emit extra debug info for
   *                              profile collection.
   */
  LLVMMetadataRef LLVMDIBuilderCreateCompileUnit(
      LLVMDIBuilderRef Builder, LLVMDWARFSourceLanguage Lang,
      LLVMMetadataRef FileRef, const char *Producer, size_t ProducerLen,
      LLVMBool isOptimized, const char *Flags, size_t FlagsLen,
      unsigned RuntimeVer, const char *SplitName, size_t SplitNameLen,
      LLVMDWARFEmissionKind Kind, unsigned DWOId, LLVMBool SplitDebugInlining,
      LLVMBool DebugInfoForProfiling);
  
  /**
   * Create a file descriptor to hold debugging information for a file.
   * \param Builder      The \c DIBuilder.
   * \param Filename     File name.
   * \param FilenameLen  The length of the C string passed to \c Filename.
   * \param Directory    Directory.
   * \param DirectoryLen The length of the C string passed to \c Directory.
   */
  LLVMMetadataRef
  LLVMDIBuilderCreateFile(LLVMDIBuilderRef Builder, const char *Filename,
                          size_t FilenameLen, const char *Directory,
                          size_t DirectoryLen);
  
  /**
   * Creates a new DebugLocation that describes a source location.
   * \param Line The line in the source file.
   * \param Column The column in the source file.
   * \param Scope The scope in which the location resides.
   * \param InlinedAt The scope where this location was inlined, if at all.
   *                  (optional).
   * \note If the item to which this location is attached cannot be
   *       attributed to a source line, pass 0 for the line and column.
   */
  LLVMMetadataRef
  LLVMDIBuilderCreateDebugLocation(LLVMContextRef Ctx, unsigned Line,
                                   unsigned Column, LLVMMetadataRef Scope,
                                   LLVMMetadataRef InlinedAt);
  
  #ifdef __cplusplus
  } /* end extern "C" */
  #endif
  
  #endif
  