creator-beautifier.qdoc 7.97 KB
Newer Older
1 2
/****************************************************************************
**
3 4
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
5
**
6
** This file is part of the Qt Creator documentation.
7
**
8 9 10 11 12 13 14
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
15
**
16
** GNU Free Documentation License Usage
17 18
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
19 20 21 22
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
23 24 25 26 27 28 29 30 31 32
**
****************************************************************************/

// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************

/*!
33
    \contentspage {Qt Creator Manual}
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61
    \previouspage creator-editor-refactoring.html
    \page creator-beautifier.html
    \nextpage creator-editor-options.html

    \title Beautifying Source Code

    You can use the experimental Beautifier plugin to format your source code
    by using the following external tools:

    \list

        \li \l{http://astyle.sourceforge.net}{Artistic Style}

        \li \l{http://clang.llvm.org/docs/ClangFormat.html}{ClangFormat}

        \li \l{http://uncrustify.sourceforge.net}{Uncrustify}

    \endlist

    The Beautifier plugin parses the source code into component structures, such
    as assignment statements, if blocks, loops, and so on, and formats them as
    specified in the Beautifier options. You can use a predefined style or
    define your own style.

    To use the Beautifier plugin:

    \list 1

62 63 64 65 66 67 68 69 70 71 72
        \li Download and install the tool to use for formatting source code:

            \list
                \li \l{http://sourceforge.net/projects/astyle/files/astyle}
                    {Artistic Style}
                \li \l{http://llvm.org/releases/download.html}{ClangFormat}
                \li \l{http://sourceforge.net/projects/uncrustify/files/uncrustify}
                    {Uncrustify}
            \endlist

            You might have to build the tools from sources for some platforms.
73

74 75
        \li Select \uicontrol Help > \uicontrol {About Plugins} > \uicontrol {C++} >
            \uicontrol Beautifier to enable the plugin.
76 77 78

        \li Restart \QC to be able to use the plugin.

79 80 81 82 83 84 85 86 87 88 89 90 91
        \li Select \uicontrol Tools > \uicontrol Options >
            \uicontrol Beautifier to specify settings for beautifying files.

        \li Select the \uicontrol {Enable auto format on file save} check box to
            automatically beautify files when you save them using the tool you
            select in the \uicontrol Tool field.

            \image qt-creator-beautifier-options-general.png

        \li In the \uicontrol {Restrict to MIME types} field, define the MIME
            types of the files to beautify, separated by semicolons. Leave the
            field empty to apply the tool on all files.

92 93 94 95 96
            This setting is applied only when automatically beautifying files on
            save. To restrict the MIME types when selecting the menu item to
            format the currently open file, specify this option in the
            tool-specific tab.

97 98 99 100 101 102 103
        \li Select the \uicontrol {Restrict to files contained in the current
            project} check box to only beautify files that belong to the
            current project.

        \li Select \uicontrol {Artistic Style}, \uicontrol {Clang Format}, or
            \uicontrol Uncrustify to specify settings for the tool you want to
            use.
104

105
            \image beautifier_options.png
106

107 108
        \li In the \uicontrol Configuration group, specify the path to
            the tool executable in the \uicontrol {Artistic Style command},
Tobias Hunger's avatar
Tobias Hunger committed
109
            \uicontrol {Clang Format command}, or
110 111
            \uicontrol {Uncrustify command} field.

112 113 114 115
        \li In the \uicontrol {Restrict to MIME types} field, define the MIME
            types of the files to beautify. This setting is applied when you
            select the menu item to format the currently open file.

116
        \li In the \uicontrol Options group, select the configuration file that
117
            defines the style to use in the source files. If you select several
118 119
            options, they are applied from top down. The available options
            depend on the tool.
120

121
            \list
122

Tobias Hunger's avatar
Tobias Hunger committed
123 124
                \li Select the \uicontrol {Use file defined in project files}
                    option to use the configuration file defined in the qmake
125
                    DISTFILES variable as the configuration file for the
126 127
                    selected tool. This option is available for Artistic Style
                    and Uncrustify.
128

129 130 131 132 133
                \li Select the \uicontrol {Use specific config file} option to
                    use the specified file as the configuration file for the
                    selected tool. This option is available for Artistic Style
                    and Uncrustify.

134
                \li Select the \uicontrol {Use file in $HOME} option to use the
Tobias Hunger's avatar
Tobias Hunger committed
135
                    specified file in the user's home directory as the
136 137 138 139 140 141 142 143 144 145 146 147
                    configuration file for the selected tool. This option is
                    available for Artistic Style and Uncrustify.

                \li For Clang Format, you can use a predefined style, by
                    selecting the \uicontrol {Use predefined style} radio
                    button, and then selecting the style to use from the list of
                    available styles.

                    Select \uicontrol File to load the style configuration from
                    the \c .clang-format or \c _clang-format file located in the
                    same directory as the source file or in one of its parent
                    directories.
148

149 150 151 152 153
                    To specify a fallback style to use if the style configuration
                    file is not available, use the \uicontrol {Fallback style}
                    combo box. Select \uicontrol Default to use the default style.
                    Select \uicontrol None to skip formatting.

Tobias Hunger's avatar
Tobias Hunger committed
154 155
                \li Select the \uicontrol {Use customized style} option, and
                    then \uicontrol Add to define your own style.
156

Tobias Hunger's avatar
Tobias Hunger committed
157
                    Define code formatting in the
158
                    \uicontrol {Add Configuration} dialog. It provides syntax
Tobias Hunger's avatar
Tobias Hunger committed
159 160
                    highlighting, auto-completion, and context-sensitive help.
                    For these features, you must have the tool installed.
161

162
                   \image beautifier_editor.png
163

Leena Miettinen's avatar
Leena Miettinen committed
164 165
            \endlist

166 167
        \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Beautifier
            > \uicontrol {Artistic Style}, \uicontrol ClangFormat, or
Tobias Hunger's avatar
Tobias Hunger committed
168 169
            \uicontrol Uncrustify > \uicontrol {Format Current File} to format
            the currently open file.
170 171 172 173 174

            You can \l{Keyboard Shortcuts}{create keyboard shortcuts} for the
            functions.

    \endlist
175

Tobias Hunger's avatar
Tobias Hunger committed
176
    In addition to the \uicontrol {Format Current File} command, ClangFormat
177
    and Uncrustify provide the \uicontrol {Format Selected Text} command. If you
178 179 180
    select it when no text is selected, the whole file is formatted by default.
    To disable this behavior, deselect the
    \uicontrol {Format entire file if no text was selected} check box.
181
*/