creator-projects-qbs.qdoc 8.27 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
    \contentspage {Qt Creator Manual}
28 29 30 31 32 33 34
    \previouspage creator-project-cmake.html
    \page creator-project-qbs.html
    \nextpage creator-projects-autotools.html

    \title Setting Up a Qbs Project

    To use Qbs to build a project, you must create a .qbs file for the project.
35 36
    You can use \QC to create a C or C++ project that is built with Qbs.
    For more information about Qbs, see
Sergio Ahumada's avatar
Sergio Ahumada committed
37
    the \l{http://doc.qt.io/qbs/index.html}{Qbs Manual}.
38

Leena Miettinen's avatar
Leena Miettinen committed
39 40 41 42
    The application is built using the default Qbs profile that is associated
    with the build and run kit. \QC automatically creates a Qbs profile for each
    kit. You can edit the build profiles by adding new keys and values.

Leena Miettinen's avatar
Leena Miettinen committed
43 44 45
    To check which Qbs version is being used, select \uicontrol Tools >
    \uicontrol Options > \uicontrol Qbs > \uicontrol {Version Info}.

Leena Miettinen's avatar
Leena Miettinen committed
46 47
    \section1 Building Qbs

48 49
    If you build \QC yourself from the \QC Git repository, you also need to
    fetch the Qbs submodule to get Qbs support:
50

51
    \list 1
52

53 54
        \li Fetch the Qbs submodule in your \QC git checkout with
            \c {git submodule update --init}.
55

56
        \li Run qmake on \QC and build \QC again.
57 58 59 60 61 62 63 64 65

    \endlist

    \section1 Building Applications with Qbs

    To build your application with Qbs:

    \list 1

Leena Miettinen's avatar
Leena Miettinen committed
66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81
        \li Select \uicontrol File > \uicontrol {New File or Project} >
            \uicontrol {Non-Qt Project} > \uicontrol {Plain C Project} or
            \uicontrol {Plain C++ Project} > \uicontrol Choose.

        \li In the \uicontrol {Project Location} dialog, specify the name and
            location for the project and select \uicontrol Next.

        \li In the \uicontrol {Define Build System} dialog, select
            \uicontrol Qbs in the \uicontrol {Build system} field, and then
            select \uicontrol Next.

        \li In the \uicontrol {Kit Selection} dialog, select a build and run kit
            for the project, and then select \uicontrol Next.

        \li In the \uicontrol {Project Management} dialog, select
            \uicontrol Finish to create a Qbs project.
82 83 84

            \image creator-qbs-project.png

85 86 87 88
        \li Edit the .qbs file for you project. Usually, you must add the
            \c Depends item for a Qt application. For examples, see the
            \c {examples} directory in the qbs repository.

89
        \li Select \uicontrol Projects to specify \uicontrol {Build Settings} for the
Leena Miettinen's avatar
Leena Miettinen committed
90 91
            project.

92
        \li Select \uicontrol {Build Steps} > \uicontrol Details to specify build steps:
Leena Miettinen's avatar
Leena Miettinen committed
93 94 95 96 97

            \image creator-qbs-build-app.png

            \list 1

98
                \li In the \uicontrol {Build variant} field, select \uicontrol Debug to
Leena Miettinen's avatar
Leena Miettinen committed
99
                    include debug symbols in the build for debugging the
100
                    application and \uicontrol Release to create the final
Leena Miettinen's avatar
Leena Miettinen committed
101 102
                    installation file.

103
                \li In the \uicontrol {Parallel jobs} field, specify the number of
Leena Miettinen's avatar
Leena Miettinen committed
104 105
                    parallel jobs to use for building.

106
                \li Select the \uicontrol {Enable QML debugging} check box to debug
Leena Miettinen's avatar
Leena Miettinen committed
107 108 109 110 111 112 113 114
                    Qt Quick application projects.

                    \note Debugging requires opening a socket at a well-known
                    port, which presents a security risk. Anyone on the Internet
                    could connect to the application that you are debugging and
                    execute any JavaScript functions. Therefore, you must make
                    sure that the port is properly protected by a firewall.

115
                \li In the \uicontrol Properties field, specify the properties to pass
Leena Miettinen's avatar
Leena Miettinen committed
116 117
                    to the project. Use colons (:) to separate keys from values.
                    For more information, see
Sergio Ahumada's avatar
Sergio Ahumada committed
118
                    \l{http://doc.qt.io/qbs/language-introduction.html}
Leena Miettinen's avatar
Leena Miettinen committed
119 120
                    {Modules} in the Qbs Manual.

121
                \li In the \uicontrol Flags field:
Leena Miettinen's avatar
Leena Miettinen committed
122 123 124

                    \list

125
                        \li Select \uicontrol {Keep going} to continue building when
Leena Miettinen's avatar
Leena Miettinen committed
126 127
                            errors occur, if possible.

128
                        \li Select \uicontrol {Show command lines} to print actual command lines
129 130
                            to the compile output pane instead of high-level descriptions.

131 132 133 134 135 136
                        \li Select \uicontrol {Install} to copy artifacts to their install location
                            after building them. This option is enabled by default.

                        \li Select \uicontrol {Clean install root} to remove the contents of
                            the install root directory before the build starts.

Leena Miettinen's avatar
Leena Miettinen committed
137 138 139 140
                    \endlist

            \endlist

141
            The \uicontrol {Equivalent command line} field displays the build command
Leena Miettinen's avatar
Leena Miettinen committed
142 143
            that is constructed based on the selected options.

144
        \li Select \uicontrol {Clean Steps} > \uicontrol Details to specify flags for the
Leena Miettinen's avatar
Leena Miettinen committed
145 146 147 148 149 150
            cleaning step.

            \image creator-qbs-build-clean.png

            \list

151
                \li Select \uicontrol {Dry run} to test cleaning without executing
Leena Miettinen's avatar
Leena Miettinen committed
152 153
                    commands or making permanent changes to the build graph.

154
                \li Select \uicontrol {Keep going} to continue cleaning when errors
Leena Miettinen's avatar
Leena Miettinen committed
155 156 157 158
                    occur, if possible.

            \endlist

159
            The \uicontrol {Equivalent command line} field displays the clean command
Leena Miettinen's avatar
Leena Miettinen committed
160 161
            that is constructed based on the selected options.

162
        \li Select \uicontrol Build > \uicontrol {Build Project} to build the application.
Leena Miettinen's avatar
Leena Miettinen committed
163

164
        \li Click the
165
            \inlineimage run_small.png
166
            (\uicontrol Run) button to deploy and run the application.
167 168
        \endlist

Leena Miettinen's avatar
Leena Miettinen committed
169 170 171 172
    \section1 Editing Build Profiles

    \image qtcreator-options-qbs.png

173 174
    You can modify a build profile that is associated with a build and run kit
    by editing the values of the keys generated by \QC and by adding new values:
Leena Miettinen's avatar
Leena Miettinen committed
175 176 177 178 179

    \list 1

        \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Qbs.

Leena Miettinen's avatar
Leena Miettinen committed
180 181 182 183 184 185 186
        \li By default, Qbs profiles are stored in the \c qbs directory in the
            \QC settings directory to ensure that different \QC instances do not
            overwrite each other's profiles. If you only run one \QC instance,
            you can store the profiles in the Qbs settings directory instead,
            by deselecting the \uicontrol {Store profiles in Qt Creator settings
            directory} check box.

Leena Miettinen's avatar
Leena Miettinen committed
187 188 189 190
        \li In the \uicontrol Kit field, select a build and run kit.

        \li Select \uicontrol Edit to edit the profile associated with the kit.

191 192 193 194 195 196 197 198 199
        \li Select \uicontrol Add to add keys and values to the profile or to
            modify existing values.

        \li In the \uicontrol Key column, spefify the key to add or modify as:
            \c <module_name>.<property_name>.

        \li In the \uicontrol Value column, specify a value as a JSON literal.

        \li Click \uicontrol OK.
Leena Miettinen's avatar
Leena Miettinen committed
200 201 202

    \endlist

203 204 205
    The values that you have modified are displayed in red in the
    \uicontrol {Profile properties} field.

Leena Miettinen's avatar
Leena Miettinen committed
206 207 208
    For a list of available keys and values, see the
    \l{http://doc.qt.io/qbs/list-of-modules.html}{List of Modules} in the
    Qbs Manual.
209
*/