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
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
|
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Automotive Suite.
**
** $QT_BEGIN_LICENSE:FDL-QTAS$
** Commercial License Usage
** Licensees holding valid commercial Qt Automotive Suite 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$
**
****************************************************************************/
/*!
\page qtas-sdk-repository-structure.html
\title Planning Repository Structure
\previouspage qtas-sdk-workflow.html
\nextpage qtas-sdk-build-repositories.html
You should carefully plan an online repository structure before building
the repositories. Consider the following items when you implement your SDK:
\section1 Amount of Updated Content
A full update of a very large repository might not be optimal, because
uploading the repository content would take a long time.
See \l{Partially Updating Repositories} for practical tips
how to update repositories partially.
\section1 Flexible Repository Structure
You can keep the online repository structure flexible if you do not hard
code the repository addresses into the online installer. Instead of hard
coding the addresses, you can make the online installer point to a
single repository.
For example, define a remote repository in your \e{config.xml} as follows:
\badcode
<RemoteRepositories>
<Repository>
<Url>https://mycompany.com/myonlinerepository/linux-x86_64/root</Url>
<Enabled>1</Enabled>
<DisplayName>MyCompany Linux-x64 root online repository</DisplayName>
</Repository>
</RemoteRepositories>
\endcode
In the configuration file structure demonstrated in \l{Building Online Installer},
the remote repository is defined in
\l{http://code.qt.io/cgit/qtsdk/qtsdk.git/tree/packaging-tools/configurations/linux/config.xml.template.linux-x64.qt5-sdk}.
For more information about the configuration file elements, see \l{Configuration File}.
In \e{https://mycompany.com/myonlinerepository/linux-x86_64/root/Updates.xml}
under your root directory, define a list of updated repositories as follows:
\badcode
<Updates>
<ApplicationName>{AnyApplication}</ApplicationName>
<ApplicationVersion>IFW_REPOSITORY_FORMAT_VERSION</ApplicationVersion>
<Checksum>true</Checksum>
<RepositoryUpdate>
<Repository action="add" url="https://mycompany.com/myonlinerepository/linux-x86_64/desktop/qtcreator" displayname="description..."/>
<Repository action="add" url="https://mycompany.com/myonlinerepository/linux-x86_64/desktop/another_cool_tool" displayname="description..."/>
<Repository action="add" url="https://mycompany.com/myonlinerepository/linux-x86_64/desktop/qt58" displayname="description..."/>
...
</RepositoryUpdate>
</Updates>
\endcode
Now you can make new repositories available to end users simply by adding a
new line into the root repository \e{Updates.xml}. You can add repositories
to any \e{Updates.xml} using the same syntax.
For general information about online repositories, see
\l{Creating Online Installers}.
\section1 File Structure in Qt Releases
A Qt release provides a concrete example of a tree structure of an online
repository. The tree structure corresponds to the structure that an end user
sees in the Qt installer wizard's \uicontrol{Select component} page.
For example, the online installer contains the following tree structure:
\badcode
qt
57
msvc2013 32-bit
msvc2013 64-bit
...
Android x86
58
msvc2015 32-bit
msvc2015 64-bit
...
...
Tools
Qt Creator 4.1.0
MinGW 5.3.0
...
\endcode
You find a similar structure under the Qt release configuration directories
in the \l{Qt SDK Git Repository}{Qt SDK Git repository}. For example,
see \e{pkg_<Qt version>} directories under
\l{http://code.qt.io/cgit/qtsdk/qtsdk.git/tree/packaging-tools/configurations/pkg_templates}.
A particular package is included into an online repository via configuration
files. For example, see
\l{http://code.qt.io/cgit/qtsdk/qtsdk.git/tree/packaging-tools/configurations/linux/x64/58/x86_64-qt58-gcc-conf}.
\section1 Qt Configuration Files
The following syntax is used in the Qt configuration files:
\table
\header
\li Property name
\li Description
\li Example
\row
\li archives
\li A comma-separated list of values that will be specified in a detailed
level later in the file.
\li
archives: 58.gcc_64.qtbase,
58.gcc_64.qtconnectivity
\row
\li target_install_base
\li A common base directory for all archives in a component
\li
target_install_base: /%QT_VERSION_MINOR%/gcc_64
\row
\li archive_url
\li The location from where an archived content is fetched. The location can
be an absolute file system path or a URL. By default, the path or the URL
is appended to a base directory defined in \e{target_install_base}.
\li
archive_uri: /qt/%QT_VERSION_MINOR%/latest/qtbase/qtbase-Linux-RHEL_6_6-GCC-Linux-RHEL_6_6-X86_64.7z
\row
\li package_strip_dirs
\li Can get numerical values, for example 0, 1 or 3. The value defines
the number of unnecessary directories that are stripped away from the path.
\li \e{package_strip_dirs} is set as \e{3} and an archive path is
\e{/home/qtbuilder/build/<actual content>}. After you have run \e{build_wrapper.py},
the archive is repackaged so that it has only <actual content>
in the repository root directory. If the path is not stripped,
an unnecessary directory structure is created in the end user host
when they install the component.
\row
\li target_install_dir
\li Defines a subdirectory for archive installation.
\li target_install_dir: /lib
\endtable
A configuration file can refer to other configuration files. For example,
see the \e{[PackageConfigurationFiles]} section in
\l{http://code.qt.io/cgit/qtsdk/qtsdk.git/tree/packaging-tools/configurations/offline_installer_jobs/5.8/linux_x64}.
It lists the included configuration files:
\badcode
[PackageConfigurationFiles]
file_list: qt-conf,
qt-license-conf,
qt-installer-changelog,
qt58-src-conf,
qt58-doc-examples-conf,
x86_64-qt58-gcc-conf,
x86_64-tools-qtcreator-qt58x-conf
\endcode
See \l{Package Directory} for general information about the package
directory structure.
*/
/*!
\page qtas-sdk-build-repositories.html
\title Working with Online Repositories
\previouspage qtas-sdk-repository-structure.html
\nextpage qtas-sdk-troubleshooting-repositories.html
You need to build online repositories when you add a new repository to
a server or when you update an existing repository.
\section1 Creating New Repository
When you create an online repository that does not yet exist in the server,
you can upload the repository content and add it to the root repository as
instructed in \l{Flexible Repository Structure}.
\section1 Updating Repository
\l{Promoting Updates} describes the steps required for updating online repositories.
Updating an online repository can vary greatly depending on the used online
server system. Typically, updating contains the following steps:
\list 1
\li Uploading content files to the server. See \l{Uploading Content Files}.
\li Uploading \e{Updates.xml} to the server. See \l{Uploading Updates.xml}.
\endlist
\section2 Uploading Content Files
For example, a maintenance tool update could contain the following content files:
\badcode
mycompany.tools.maintenancetool/2.0.4-0meta.7z
mycompany.tools.maintenancetool/2.0.4-0maintenancetool.7z
mycompany.tools.maintenancetool/2.0.4-0maintenancetool.7z.sha1
\endcode
Each content file is prepended with a version number set in the \c{<Version>} element
in the component's \e{package.xml} file. Thus you can copy the updated
files to a same directory that contains current file versions. It is just
important to remember to update the version numbers. For example, the
maintenance tool directory could contain the following files:
\badcode
mycompany.tools.maintenancetool/2.0.2-0meta.7z
mycompany.tools.maintenancetool/2.0.2-0maintenancetool.7z
mycompany.tools.maintenancetool/2.0.2-0maintenancetool.7z.sha1
mycompany.tools.maintenancetool/2.0.3-0meta.7z
mycompany.tools.maintenancetool/2.0.3-0maintenancetool.7z
mycompany.tools.maintenancetool/2.0.3-0maintenancetool.7z.sha1
mycompany.tools.maintenancetool/2.0.4-0meta.7z
mycompany.tools.maintenancetool/2.0.4-0maintenancetool.7z
mycompany.tools.maintenancetool/2.0.4-0maintenancetool.7z.sha1
\endcode
\section2 Uploading Updates.xml
If your online server uses mirroring, it is important to ensure that all
content is synchronized to the server before you update \e{Updates.xml}.
You can set a cache expiration time as zero for \e{Updates.xml} in order to
reduce delay in synchronization.
\section1 Maintenance Tool
A maintenance tool is built when you build the
\l{Building Qt Installer Framework} {Qt Installer Framework}. Usually,
the maintenance tool is included in online repositories. It is installed to
the end user host from the online repository with other installed content.
Online repositories should always provide the latest version of the
maintenance tool. We recommend that you build both an online installer and
the maintenance tool with the Qt Installer Framework version with the same
SHA-1. Otherwise, end users can install an old version of the maintenance
tool via the online installer. Then, if some updates on the server side are
available only via the latest maintenance tool version, the end users with
the old maintenance tool cannot access them.
For example, the maintenance tool online repository could be as follows:
\badcode
linux_x64/desktop/tools_maintenancetool/Updates.xml
mycompany.tools.maintenancetool/2.0.4-0meta.7z
mycompany.tools.maintenancetool/2.0.4-0maintenancetool.7z
mycompany.tools.maintenancetool/2.0.4-0maintenancetool.7z.sha1
\endcode
*/
/*!
\page qtas-sdk-troubleshooting-repositories.html
\title Troubleshooting and Best Practices
\previouspage qtas-sdk-build-repositories.html
\nextpage qtas-sdk-creation.html
When you work with online repositories, it is important to understand
how different actions affect the repositories. \l{Troubleshooting}
lists use cases that should be handled carefully so they do not lead to
errors in end user host. \l{Best Practices} lists some useful
practices that might be helpful in your daily work with online repositories.
\section1 Troubleshooting
\section2 Dependencies to Online Repository
Immediately after an end user installs something from an online repository
via an online installer or a maintenance tool, a local dependency from the
end user host to the online repository is established. Thus you should
follow the following quidelines:
\list
\li Do not remove repositories from the online server simply by deleting
the repositories. Instead, you should add the following setting in the
root repository:
\badcode
<Repository action="remove" url="...">
\endcode
\li Do not manually change content in online repositories as it causes
a SHA-1 checksum mismatch.
\li If you push an update for a component in an online repository, you
must always remember to increase the version number of the updated component.
See \l{Updating Repository}.
\endlist
\section2 Unsuccessful Updates
If something goes wrong while you are uploading either
\l{Uploading Content Files}{content} or \l{Uploading Updates.xml}{Updates.xml},
do not upload the previous versions from your own backup-files.
The Qt Installer Framework does not support roll-back functionality. Thus the
maintenance tool does not allow end users to install again the previous
version that is known to work.
You should create a new version of the broken component and upload it
to the online repository. End users need to uninstall the broken component
and install the fixed one instead.
\section2 Mirroring and File Caching
If the web server uses mirroring or file caching, it is important to ensure
that all content has been uploaded to the server before you upload a new version
of \e{Updates.xml}.
Some web servers support setting cache expiration time to zero for some
files. In this case, you could set the cache expiration time to zero for
\e{Updates.xml}.
\section1 Best Practices
\section2 Uploading to Test Server
You can use a test server where you upload the repository builds for testing
purposes. After you have verified the content, you can upload it publicly
available to the web server that is used by online installers.
*/
|