creator-projects-compilers.qdoc 9.52 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
    \previouspage creator-project-qmake.html
    \page creator-tool-chains.html
36
    \nextpage creator-debuggers.html
37

38
    \title Adding Compilers
39

40 41
    Qt is supported on a variety of 32-bit and 64-bit platforms, and can
    usually be built on each platform with GCC, a vendor-supplied compiler, or
42
    a third party compiler. In \QC, a \l{glossary-buildandrun-kit}{kit}
43 44
    specifies the compiler and other necessary tools for building an application
    for and running it on a particular platform.
45

46
    \QC automatically detects the compilers that are registered by your system
47
    or by an installer. You can add compilers to build applications by using other
48 49
    compilers or by using additional versions of the automatically detected
    compilers:
50 51 52

    \list

53
        \li GNU Compiler Collection (GCC) is a compiler for Linux and
54
            \macos.
55

56
        \li MinGW (Minimalist GNU for Windows) is a native software port of GCC
57 58
            and GNU Binutils for use in the development of native Microsoft
            Windows applications on Windows. MinGW is
59
            distributed together with \QC and Qt installers for Windows.
60

61
        \li Linux ICC (Intel C++ Compiler) is a group of C and C++ compilers
62 63
            for Linux.

64
        \li Clang is a C, C++, Objective C, and Objective C++ front-end for the
65
            LLVM compiler for Windows, Linux, and \macos.
Leena Miettinen's avatar
Leena Miettinen committed
66

Leena Miettinen's avatar
Leena Miettinen committed
67 68
        \li QCC is the interface for compiling C++ applications for QNX.

69 70
    \endlist

Leena Miettinen's avatar
Leena Miettinen committed
71
    To build an application using GCC, MinGW, Clang, or QCC, specify the path
72
    to the directory where the compiler is located and select
73 74
    the application binary interface (ABI) version from the list of available
    versions. You can also create a custom ABI definition.
75
    For QCC, also specify the path to the QNX Software Development Platform (SDP).
76

77 78
    You specify the compiler to use for each kit in \uicontrol Tools >
    \uicontrol Options > \uicontrol {Build & Run} > \uicontrol Kits.
79

80
    To add compilers:
81 82 83

    \list 1

84
        \li Select \uicontrol Tools > \uicontrol Options >
85 86 87
            \uicontrol {Build & Run} > \uicontrol Compilers > \uicontrol Add,
            then select a compiler in the list, and then select \uicontrol C or
            \uicontrol C++ to add a C or C++ compiler.
88 89 90

            \image qtcreator-toolchains.png

91
            To clone the selected compiler, select \uicontrol Clone.
92

93 94
        \li In the \uicontrol Name field, enter a name for the compiler to
            identify it in \QC.
95

96 97
        \li In the \uicontrol {Compiler path} field, enter the path to the
            directory where the compiler is located.
98

99
        \li In the \uicontrol {Platform codegen flags} field, check the flags passed
100 101 102
            to the compiler that specify the architecture on the target
            platform.

103
        \li In the \uicontrol {Platform linker flags} field, check the flags passed to
104 105 106
            the linker that specify the architecture on the target platform.
            The linker flags are used only when building with Qbs.

107
            The other settings to specify depend on the compiler.
108

109 110 111 112
        \li In the \uicontrol ABI field, provide an identification for the
            target architecture. This is used to warn about ABI mismatches
            within the kits.

113 114
    \endlist

Leena Miettinen's avatar
Leena Miettinen committed
115 116 117
    \section1 Adding Custom Compilers

    To add a compiler that is not listed above or a remote compiler, use the
118
    \uicontrol Custom option and specify the paths to the directories where the
Leena Miettinen's avatar
Leena Miettinen committed
119 120 121 122 123 124 125 126
    compiler and make tool are located and options for the compiler.

    \image creator-compilers-custom.png

    To add other compilers:

    \list 1

127
        \li Select \uicontrol Tools > \uicontrol Options > \uicontrol {Build & Run} >
128 129
            \uicontrol Compilers > \uicontrol Add > \uicontrol Custom >
            \uicontrol C or \uicontrol C++.
Leena Miettinen's avatar
Leena Miettinen committed
130

131
        \li In the \uicontrol Name field, enter a name for the compiler.
Leena Miettinen's avatar
Leena Miettinen committed
132

133
        \li In the \uicontrol {Compiler path} field, enter the path to the directory
Leena Miettinen's avatar
Leena Miettinen committed
134 135
            where the compiler is located.

136
        \li In the \uicontrol {Make path} field, enter the path to the directory where
Leena Miettinen's avatar
Leena Miettinen committed
137 138
            the make tool is located.

139
       \li  In the \uicontrol ABI field, specify the ABI version.
Leena Miettinen's avatar
Leena Miettinen committed
140

141
        \li In the \uicontrol {Predefined macros} field, specify the macros that the
Leena Miettinen's avatar
Leena Miettinen committed
142 143 144
            compiler enables by default. Specify each macro on a separate line,
            in the following format: MACRO[=value].

145
        \li In the \uicontrol {Header paths} field, specify the paths to directories
Leena Miettinen's avatar
Leena Miettinen committed
146 147 148
            that the compiler checks for headers. Specify each path on a
            separate line.

149
        \li In the \uicontrol {C++11 flags} field, specify the flags that turn on
Leena Miettinen's avatar
Leena Miettinen committed
150 151
            C++11 support in the compiler.

152
        \li In the \uicontrol {Qt mkspecs} field, specify the path to the directory
Leena Miettinen's avatar
Leena Miettinen committed
153 154 155
            where mkspecs are located. Usually, the path is specified relative
            to the Qt mkspecs directory.

156 157
        \li In the \uicontrol {Error parser} field, select the error parser to use.
            Select \uicontrol Custom, and then select \uicontrol {Customer Parser Settings}
158 159 160 161
            to specify settings for a custom parser:

            \image qtcreator-custom-parser.png

162 163 164 165
            The custom error parser enables you to capture errors and warnings separately.
            You can configure the error parser in the \uicontrol Error tab and the warning
            parser in the \uicontrol Warning tab:

166 167
            \list 1

168
                \li In the \uicontrol {Error message capture pattern} field, specify
169 170
                    a regular expression to define what is an error. The custom
                    parser matches the compile output line by line against the
171
                    regular expression and displays errors in the \uicontrol Issues
172 173 174
                    output pane. Create regular expression groups that contain
                    the file name, line number and error message.

175 176 177
                \li In the \uicontrol {Capture Positions} field, map the regular
                    expression groups to \uicontrol {File name}, \uicontrol {Line number},
                    and \uicontrol Message.
178

179 180 181 182
                \li In the \uicontrol {Capture Output Channels} field, specify whether
                    messages from standard output, standard error, or both channels
                    should be captured.

183 184
                \li In the \uicontrol {Test} group, you can test how the message that
                    you enter in the \uicontrol {Error message} field is matched when
185 186 187 188
                    using the current settings.

            \endlist

Leena Miettinen's avatar
Leena Miettinen committed
189 190 191
    \endlist

    \section1 Troubleshooting MinGW Compilation Errors
192

193
    If error messages displayed in the \uicontrol {Compile Output} pane contain
194
    paths where slashes are missing (for example, \c {C:QtSDK}),
195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227
    check your PATH variable. At the command line, enter the following commands:

    \code
        where sh.exe
        where make.exe
        where mingw32-make.exe
    \endcode

    If these commands show paths, they have been added to the global PATH
    variable during the installation of a tool chain based on Cygwin or MinGW,
    even though this is against Windows conventions.

    To keep working with the third-party tool chain, create a new shell link
    that adds the required paths (as Visual Studio and Qt do). The shell link
    must point to cmd.exe, as illustrated by the following example:

    \c {C:\Windows\System32\cmd.exe /K C:\path_to\myenv.bat}

    where the /K parameter carries out the command specified in the bat file.

    Create the myenv.bat file at \e path_to, which should be in a convenient
    location. In the file, specify the paths to the tool chains. For example,

    \c  {set PATH=C:\path1;C:\path2;%PATH%}

    where \e path1 and \e path2 are paths to the tool chains.

    Finally, remove the paths from the global PATH, reboot the computer, and
    run the \c where commands again to verify that the global PATH is now clean.

    You can use the shell link to run the tools in the third-party tool chains.

*/