source: trunk/doc/src/examples/globalVariables.qdoc@ 5

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Qt Software Information ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain
** additional rights. These rights are described in the Nokia Qt LGPL
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example xmlpatterns/xquery/globalVariables
    \title C++ Source Code Analyzer Example

    This example uses XQuery and the \c xmlpatterns command line utility to
    query C++ source code.

    \tableofcontents

    \section1 Introduction

    Suppose we want to analyze C++ source code to find coding standard
    violations and instances of bad or inefficient patterns. We can do
    it using the common searching and pattern matching utilities to
    process the C++ files (e.g., \c{grep}, \c{sed}, and \c{awk}). Now
    we can also use XQuery with the QtXmlPatterns module.

    An extension to the \c{g++} open source C++ compiler
    (\l{http://public.kitware.com/GCC_XML/HTML/Index.html} {GCC-XML})
    generates an XML description of C++ source code declarations. This
    XML description can then be processed by QtXmlPatterns using
    XQueries to navigate the XML description of the C++ source and
    produce a report. Consider the problem of finding mutable global
    variables:

    \section2 Reporting Uses of Mutable Global Variables

    Suppose we want to introduce threading to a C++ application that
    was originally written without threading. In a threaded program,
    mutable global variables can cause bugs, because one thread might
    change a global variable that other threads are reading, or two
    threads might try to set the same global variable. So when
    converting our program to use threading, one of the things we must
    do is protect the global variables to prevent the bugs described
    above. How can we use XQuery and
    \l{http://public.kitware.com/GCC_XML/HTML/Index.html} {GCC-XML} to
    find the variables that need protecting? 

    \section3 A C++ application

    Consider the declarations in this hypothetical C++ application:

    \snippet examples/xmlpatterns/xquery/globalVariables/globals.cpp 0

    \section3 The XML description of the C++ application

    Submitting this C++ source to  
    \l{http://public.kitware.com/GCC_XML/HTML/Index.html} {GCC-XML}
    produces this XML description:

    \quotefromfile examples/xmlpatterns/xquery/globalVariables/globals.gccxml
    \printuntil

    \section3 The XQuery for finding global variables

    We need an XQuery to find the global variables in the XML
    description. Here is our XQuery source. We walk through it in
    \l{XQuery Code Walk-Through}.

    \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq
    \printuntil

    \section3 Running the XQuery

    To run the XQuery using the \c xmlpatterns command line utility,
    enter the following command:

    \code
    xmlpatterns reportGlobals.xq -param fileToOpen=globals.gccxml -output globals.html
    \endcode

    \section3 The XQuery output

    The \c xmlpatterns command loads and parses \c globals.gccxml,
    runs the XQuery \c reportGlobals.xq, and generates this report:

    \raw HTML
<html xmlns="http://www.w3.org/1999/xhtml/" xml:lang="en" lang="en">
    <head>
        <title>Global variables report for globals.gccxml</title>
    </head>
    <style type="text/css">
        .details
        {
            text-align: left;
            font-size: 80%;
            color: blue
        }
        .variableName
        {
            font-family: courier;
            color: blue
        }
    </style>
    <body>
        <p class="details">Start report: 2008-12-16T13:43:49.65Z</p>
        <p>Global variables with complex types:</p>
        <ol>
            <li>
                <span class="variableName">mutableComplex1</span> in globals.cpp at line 14</li>