source: trunk/doc/src/development/moc.qdoc

/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** 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 Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page moc.html
    \title Using the Meta-Object Compiler (moc)
    \ingroup qttools
    \keyword moc

    The Meta-Object Compiler, \c moc, is the program that handles
    \l{Meta-Object System}{Qt's C++ extensions}.

    The \c moc tool reads a C++ header file. If it finds one or more
    class declarations that contain the Q_OBJECT macro, it
    produces a C++ source file containing the meta-object code for
    those classes. Among other things, meta-object code is required
    for the signals and slots mechanism, the run-time type information,
    and the dynamic property system.

    The C++ source file generated by \c moc must be compiled and
    linked with the implementation of the class.

    If you use \l qmake to create your makefiles, build rules will be
    included that call the moc when required, so you will not need to
    use the moc directly. For more background information on \c moc,
    see \l{Why Doesn't Qt Use Templates for Signals and Slots?}

    \section1 Usage

    \c moc is typically used with an input file containing class
    declarations like this:

    \snippet doc/src/snippets/moc/myclass1.h 0

    In addition to the signals and slots shown above, \c moc also
    implements object properties as in the next example. The
    Q_PROPERTY() macro declares an object property, while
    Q_ENUMS() declares a list of enumeration types within the class
    to be usable inside the \l{Qt's Property System}{property
    system}.

    In the following example, we declare a property of the
    enumeration type \c Priority that is also called \c priority and
    has a get function \c priority() and a set function \c
    setPriority().

    \snippet doc/src/snippets/moc/myclass2.h 0

    The Q_FLAGS() macro declares enums that are to be used
    as flags, i.e. OR'd together. Another macro, Q_CLASSINFO(),
    allows you to attach additional name/value pairs to the class's
    meta-object:

    \snippet doc/src/snippets/moc/myclass3.h 0

    The output produced by \c moc must be compiled and linked, just
    like the other C++ code in your program; otherwise, the build
    will fail in the final link phase. If you use \c qmake, this is
    done automatically. Whenever \c qmake is run, it parses the
    project's header files and generates make rules to invoke \c moc
    for those files that contain a Q_OBJECT macro.

    If the class declaration is found in the file \c myclass.h, the
    moc output should be put in a file called \c moc_myclass.cpp.
    This file should then be compiled as usual, resulting in an
    object file, e.g., \c moc_myclass.obj on Windows. This object
    should then be included in the list of object files that are
    linked together in the final building phase of the program.

    \section1 Writing Make Rules for Invoking \c moc

    For anything but the simplest test programs, it is recommended
    that you automate running the \c{moc}. By adding some rules to
    your program's makefile, \c make can take care of running moc
    when necessary and handling the moc output.

    We recommend using the \l qmake makefile generation tool for
    building your makefiles. This tool generates a makefile that does
    all the necessary \c moc handling.

    If you want to create your makefiles yourself, here are some tips
    on how to include moc handling.

    For Q_OBJECT class declarations in header files, here is a
    useful makefile rule if you only use GNU make:

    \snippet doc/src/snippets/code/doc_src_moc.qdoc 0

    If you want to write portably, you can use individual rules of
    the following form:

    \snippet doc/src/snippets/code/doc_src_moc.qdoc 1

    You must also remember to add \c moc_foo.cpp to your \c SOURCES
    (substitute your favorite name) variable and \c moc_foo.o or \c
    moc_foo.obj to your \c OBJECTS variable.

    Both examples assume that \c $(DEFINES) and \c $(INCPATH) expand
    to the define and include path options that are passed to the C++
    compiler. These are required by \c moc to preprocess the source
    files.

    While we prefer to name our C++ source files \c .cpp, you can use
    any other extension, such as \c .C, \c .cc, \c .CC, \c .cxx, and
    \c .c++, if you prefer.

    For Q_OBJECT class declarations in implementation (\c .cpp)
    files, we suggest a makefile rule like this:

    \snippet doc/src/snippets/code/doc_src_moc.qdoc 2

    This guarantees that make will run the moc before it compiles
    \c foo.cpp. You can then put

    \snippet doc/src/snippets/code/doc_src_moc.qdoc 3

    at the end of \c foo.cpp, where all the classes declared in that
    file are fully known.

    \section1 Command-Line Options

    Here are the command-line options supported by the moc:

    \table
    \header \o Option \o Description

    \row
    \o \c{-o<file>}
    \o Write output to \c <file> rather than to standard output.

    \row
    \o \c{-f[<file>]}
    \o Force the generation of an \c #include statement in the
    output. This is the default for header files whose extension
    starts with \c H or \c h. This option is useful if you have
    header files that do not follow the standard naming conventions.
    The \c <file> part is optional.

    \row
    \o \c -i
    \o Do not generate an \c #include statement in the output.
    This may be used to run the moc on on a C++ file containing one or
    more class declarations. You should then \c #include the meta-object
    code in the \c .cpp file.

    \row
    \o \c -nw
    \o Do not generate any warnings. (Not recommended.)

    \row
    \o \c {-p<path>}
    \o Makes the moc prepend \c {<path>/} to the file name in the
    generated \c #include statement.

    \row
    \o \c {-I<dir>}
    \o Add dir to the include path for header files.

    \row
    \o \c{-E}
    \o Preprocess only; do not generate meta-object code.

    \row
    \o \c {-D<macro>[=<def>]}
    \o Define macro, with optional definition.

    \row
    \o \c{-U<macro>}
    \o Undefine macro.

    \row
    \o \c{@<file>}
    \o Read additional command-line options from \c{<file>}.
    Each line of the file is treated as a single option. Empty lines
    are ignored. Note that this option is not supported within the
    options file itself (i.e. an options file can't "include" another
    file).

    \row
    \o \c{-h}
    \o Display the usage and the list of options.

    \row
    \o \c {-v}
    \o Display \c{moc}'s version number.

    \row
    \o \c{-Fdir}
    
    \o Mac OS X. Add the framework directory \c{dir} to the head of
       the list of directories to be searched for header files. These