1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
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
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of Qbs.
**
** $QT_BEGIN_LICENSE:FDL$
** 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.
**
** GNU Free Documentation License Usage
** 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. 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.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\qmltype vcs
\inqmlmodule QbsModules
\since Qbs 1.10
\brief Provides support for version control systems (Git, SVN, Mercurial).
The \c vcs module provides information about the current state of the project's repository.
This is useful for embedding version information directly into your binaries, such as the
latest tag, number of commits since the tag, and current commit hash.
By default, a C header file is generated, which defines macros representing the repository
state. This allows C/C++ code to access this information at run time.
Supported version control systems:
\list
\li Git
\li Subversion (SVN)
\li Mercurial (hg)
\endlist
For example:
\code
#include <vcs-repo-state.h>
#include <iostream>
int main()
{
std::cout << "I was built from " << VCS_REPO_STATE << std::endl;
std::cout << "Latest tag: " << VCS_REPO_LATEST_TAG << std::endl;
std::cout << "Commits since tag: " << VCS_REPO_COMMITS_SINCE_TAG << std::endl;
std::cout << "Commit SHA: " << VCS_REPO_COMMIT_SHA << std::endl;
}
\endcode
Above, a header file called \c{vcs-repo-state.h} is created, defining a
macro called \c VCS_REPO_STATE, which expands to a character constant
describing the current state of the repository. For Git, this would be the
current HEAD's commit hash.
Example:
\code
VCS_REPO_STATE = "v1.2.3-5-gabcdef0"
VCS_REPO_LATEST_TAG = "v1.2.3"
VCS_REPO_COMMITS_SINCE_TAG = "5"
VCS_REPO_COMMIT_SHA = "gabcdef0"
\endcode
For Git repositories without any tags, the commit hash will be used instead.
For Mercurial repositories, the full repository state is always shown.
For SVN, only \l{vcs::}{repoState} is currently available.
*/
/*!
\qmlproperty string vcs::headerFileName
The name of the C header file to be generated. This header file defines the following macros:
\list
\li \c VCS_REPO_STATE — Full repository state string
\li \c VCS_REPO_LATEST_TAG — Latest tag reachable from HEAD (or "none")
\li \c VCS_REPO_COMMITS_SINCE_TAG — Number of commits since latest tag (or "none")
\li \c VCS_REPO_COMMIT_SHA — Current commit SHA (or "none")
\endlist
Set this to \c undefined to disable header file generation.
\defaultvalue \c{"vcs-repo-state.h"}
*/
/*!
\qmlproperty string vcs::repoDir
The root directory of the repository.
\defaultvalue The top-level project directory (\l{Project::sourceDirectory}
{project.sourceDirectory}).
*/
/*!
\qmlproperty string vcs::repoState
The full repository state string.
For Git, this corresponds to the output of:
\c {git describe --tags --always --long HEAD}
Example values:
\list
\li \c abc1234 (no tags)
\li \c abc1234-0-gabc1234 (at tag)
\li \c v1.0.0-3-gabc1234 (3 commits after tag)
\endlist
For Mercurial, this corresponds to the output of:
\c {hg log -r . --template "{latesttag}-{latesttagdistance}-m{node|short}"}
Example values:
\list
\li \c null-0-m000000000000 (empty repo)
\li \c null-1-mabc1234 (no tags)
\li \c null-3-mabc1234 (4 commits, no tags)
\li \c v1.0.0-1-mabc1234 (at tag)
\li \c v1.0.0-3-mabc1234 (4 commits after tag)
\endlist
For SVN, this is the current revision number.
\nodefaultvalue
*/
/*!
\qmlproperty string vcs::repoLatestTag
The latest reachable tag in the repository.
For Git, this is the \c TAG component from \c git describe output.
If no tags are present, this will be set to \c "none".
For Mercurial, this is the \c {latesttag} component from the template.
For SVN, this property is currently not set and will be \c "none".
\nodefaultvalue
\since Qbs 3.1.0
*/
/*!
\qmlproperty string vcs::repoCommitsSinceTag
The number of commits since the latest tag.
For Git, this is the \c N component from \c git describe output.
If no tags are present, this will be set to \c "none".
For Mercurial, this is the \c {latesttagdistance} component from the template.
For SVN, this property is currently not set and will be \c "none".
\nodefaultvalue
\since Qbs 3.1.0
*/
/*!
\qmlproperty string vcs::repoCommitSha
The abbreviated commit hash of HEAD.
For Git, this is the \c gSHA component from \c git describe output.
If no tags are present, this will be set to the commit hash prefixed with \c g.
For Mercurial, this is the \c m{node|short} component from the template.
For SVN, this property is currently not set and will be \c "none".
\nodefaultvalue
\since Qbs 3.1.0
*/
/*!
\qmlproperty string vcs::toolFilePath
Set this property if the tool has an unusual name in your local
installation, or if it is located in a directory that is not in the build
environment's \c PATH.
\defaultvalue The file name of the version control tool corresponding to
\l{vcs::type}{type}.
*/
/*!
\qmlproperty string vcs::type
The version control system used in the project.
Currently, the supported values are \c{"git"}, \c{"hg"} and \c{"svn"}.
\defaultvalue auto-detected
*/
|
