[clang-tools-extra] r193841 - pp-trace user documentation - beginnings
Sean Silva
silvas at purdue.edu
Thu Oct 31 18:55:31 PDT 2013
Any fields that are just the values of a Clang enum can probably be
documented by just linking to the appropriate clang doxygen (and specifying
how the output corresponds to those names).
-- Sean Silva
On Thu, Oct 31, 2013 at 8:38 PM, John Thompson <
John.Thompson.JTSoftware at gmail.com> wrote:
> Author: jtsoftware
> Date: Thu Oct 31 19:38:04 2013
> New Revision: 193841
>
> URL: http://llvm.org/viewvc/llvm-project?rev=193841&view=rev
> Log:
> pp-trace user documentation - beginnings
>
> Added:
> clang-tools-extra/trunk/docs/pp-trace.rst
> Modified:
> clang-tools-extra/trunk/docs/index.rst
>
> Modified: clang-tools-extra/trunk/docs/index.rst
> URL:
> http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/index.rst?rev=193841&r1=193840&r2=193841&view=diff
>
> ==============================================================================
> --- clang-tools-extra/trunk/docs/index.rst (original)
> +++ clang-tools-extra/trunk/docs/index.rst Thu Oct 31 19:38:04 2013
> @@ -17,6 +17,7 @@ Contents
>
> clang-modernize
> modularize
> + pp-trace
>
>
> Doxygen Documentation
>
> Added: clang-tools-extra/trunk/docs/pp-trace.rst
> URL:
> http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/pp-trace.rst?rev=193841&view=auto
>
> ==============================================================================
> --- clang-tools-extra/trunk/docs/pp-trace.rst (added)
> +++ clang-tools-extra/trunk/docs/pp-trace.rst Thu Oct 31 19:38:04 2013
> @@ -0,0 +1,169 @@
> +.. index:: pp-trace
> +
> +==================================
> +pp-trace User's Manual
> +==================================
> +
> +.. toctree::
> + :hidden:
> +
> +:program:`pp-trace` is a standalone tool that traces preprocessor
> +activity. It's also used as a test of Clang's PPCallbacks interface.
> +It runs a given source file through the Clang preprocessor, displaying
> +selected information from callback functions overidden in a PPCallbacks
> +derivation. The output is in a high-level YAML format, described in
> +:ref:`OutputFormat`.
> +
> +.. _Usage:
> +
> +pp-trace Usage
> +==============
> +
> +Command Line Format
> +-------------------
> +
> +``pp-trace [<pp-trace-options>] <source-file> [<front-end-options>...]``
> +
> +``<pp-trace-options>`` is a place-holder for options
> +specific to pp-trace, which are described below in
> +`pp-trace Command Line Options`.
> +
> +``<source-file>`` specifies the source file to run through the
> preprocessor.
> +
> +``<front-end-options>`` is a place-holder for regular Clang
> +front-end arguments, which must follow the <source-file>.
> +
> +Command Line Options
> +--------------------
> +
> +.. option:: -ignore <callback-name-list>
> +
> + This option specifies a comma-seperated list of names of callbacks
> + that shouldn't be traced. It can be used to eliminate unwanted
> + trace output. The callback names are the name of the actual
> + callback function names in the PPCallbacks class:
> +
> + * FileChanged
> + * FileSkipped
> + * FileNotFound
> + * InclusionDirective
> + * moduleImport
> + * EndOfMainFile
> + * Ident
> + * PragmaDirective
> + * PragmaComment
> + * PragmaDetectMismatch
> + * PragmaDebug
> + * PragmaMessage
> + * PragmaDiagnosticPush
> + * PragmaDiagnosticPop
> + * PragmaDiagnostic
> + * PragmaOpenCLExtension
> + * PragmaWarning
> + * PragmaWarningPush
> + * PragmaWarningPop
> + * MacroExpands
> + * MacroDefined
> + * MacroUndefined
> + * Defined
> + * SourceRangeSkipped
> + * If
> + * Elif
> + * Ifdef
> + * Ifndef
> + * Else
> + * Endif
> +
> +.. option:: -output <output-file>
> +
> + By default, pp-trace outputs the trace information to stdout. Use this
> + option to output the trace information to a file.
> +
> +.. _OutputFormat:
> +
> +pp-trace Output Format
> +======================
> +
> +The pp-trace output is formatted as YAML. See http://yaml.org/ for
> general
> +YAML information. It's arranged as a sequence of information about the
> +callback call, include the callback name and argument information, for
> +example:::
> +
> + ---
> + - Callback: Name
> + Argument1: Value1
> + Argument2: Value2
> + (etc.)
> + ...
> +
> +With real data:::
> +
> + ---
> + - Callback: FileChanged
> + Loc:
> "c:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-include.cpp:1:1"
> + Reason: EnterFile
> + FileType: C_User
> + PrevFID: (invalid)
> + (etc.)
> + - Callback: FileChanged
> + Loc:
> "D:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-include.cpp:5:1"
> + Reason: ExitFile
> + FileType: C_User
> + PrevFID:
> "D:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/Input/Level1B.h"
> + - Callback: EndOfMainFile
> + ...
> +
> +In all but one case (MacroDirective) the "Argument" scalars have the same
> +name as the argument in the corresponding PPCallbacks callback function.
> +
> +Callback Details
> +----------------
> +
> +The following sections describe the output format for each callback.
> +
> +FileChanged Callback
> +^^^^^^^^^^^^^^^^^^^^
> +
>
> ++----------------+-----------------------------------------------------+------------------------------+-----------------------+
> +| Argument Name | Argument Value Syntax |
> Clang C++ Type | Description |
>
> ++----------------+-----------------------------------------------------+------------------------------+-----------------------+
> +| Loc | "(file):(line):(col)" |
> SourceLocation | Where in the file. |
>
> ++----------------+-----------------------------------------------------+------------------------------+-----------------------+
> +| Reason | (EnterFile|ExitFile|SystemHeaderPragma|RenameFile) |
> PPCallbacks::FileChangeReason| Reason for change. |
>
> ++----------------+-----------------------------------------------------+------------------------------+-----------------------+
> +| FileType | (C_User|C_System|C_ExternCSystem) |
> SrcMgr::CharacteristicKind | Include type. |
>
> ++----------------+-----------------------------------------------------+------------------------------+-----------------------+
> +| PrevFID | ((file)|(invalid)) |
> FileID | Previous file, if any.|
>
> ++----------------+-----------------------------------------------------+------------------------------+-----------------------+
> +
> +Example:::
> +
> + - Callback: FileChanged
> + Loc:
> "D:/Clang/llvm/tools/clang/tools/extra/test/pp-trace/pp-trace-include.cpp:1:1"
> + Reason: EnterFile
> + FileType: C_User
> + PrevFID: (invalid)
> +
> +(More callback documentation to come...)
> +
> +Building pp-trace
> +=================
> +
> +To build from source:
> +
> +1. Read `Getting Started with the LLVM System`_ and `Clang Tools
> + Documentation`_ for information on getting sources for LLVM, Clang, and
> + Clang Extra Tools.
> +
> +2. `Getting Started with the LLVM System`_ and `Building LLVM with
> CMake`_ give
> + directions for how to build. With sources all checked out into the
> + right place the LLVM build will build Clang Extra Tools and their
> + dependencies automatically.
> +
> + * If using CMake, you can also use the ``pp-trace`` target to build
> + just the pp-trace tool and its dependencies.
> +
> +.. _Getting Started with the LLVM System:
> http://llvm.org/docs/GettingStarted.html
> +.. _Building LLVM with CMake: http://llvm.org/docs/CMake.html
> +.. _Clang Tools Documentation: http://clang.llvm.org/docs/ClangTools.html
> +
>
>
> _______________________________________________
> cfe-commits mailing list
> cfe-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20131031/b64e2db2/attachment.html>
More information about the cfe-commits
mailing list