Add example for online installer

Change-Id: I7c4f32db01b94b24339641907ae7cdbe209ff707
Reviewed-by: Jarek Kobus <jaroslaw.kobus@theqtcompany.com>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@theqtcompany.com>

15 files changed, 255 insertions, 0 deletions

diff --git a/examples/doc/images/qtifw-examples-online-1.png b/examples/doc/images/qtifw-examples-online-1.png
new file mode 100644
index 000000000..fc0fe5a94
--- /dev/null
+++ b/examples/doc/images/qtifw-examples-online-1.png
diff --git a/examples/doc/images/qtifw-examples-online.png b/examples/doc/images/qtifw-examples-online.png
new file mode 100644
index 000000000..b527b3e2d
--- /dev/null
+++ b/examples/doc/images/qtifw-examples-online.png
diff --git a/examples/doc/online.qdoc b/examples/doc/online.qdoc
new file mode 100644
index 000000000..3f9f800eb
--- /dev/null
+++ b/examples/doc/online.qdoc
@@ -0,0 +1,160 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing
+**
+** This file is part of the Qt Installer Framework.
+**
+** $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 Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example online
+    \ingroup qtifwexamples
+    \title Online Installer Example
+
+    \brief Using the repogen tool and the configuration file to set up an
+    online installer.
+
+    \image qtifw-examples-online.png
+
+    \e{Online Installer} illustrates how to set up an online installer that
+    fetches the original packages and updates to them from a server.
+
+    \include installerfw-examples-configuring.qdocinc
+
+    \list
+        \li The \c <RemoteRepositories> element is specific to an online
+            installer. It can contain one or several \c <Repository> child
+            elements that specify a connection to an online repository. For more
+            information about the available options, see
+            \l{Configuring Repositories}.
+    \endlist
+
+    \quotefile online/config/config.xml
+
+    \include installerfw-examples-packaging.qdocinc
+
+    \list
+        \li The \c <Default> element is set to \c true to preselect the
+            component in the installer.
+    \endlist
+
+    \quotefile online/packages/A/meta/package.xml
+
+    This installer contains two components, A and B, that each have their own
+    package information file with slightly different contents.
+
+    \section1 Generating the Online Repository
+
+    The packages need to be converted to a file structure that the installer can
+    fetch at runtime. To use the \c repogen tool to convert the packages, switch
+    to the example source directory on the command line and enter the following
+    command:
+
+    \list
+        \li On Windows:
+            \code
+            ..\..\bin\repogen.exe -p packages repository
+            \endcode
+        \li On Linux or OS X:
+            \code
+            ../../bin/repogen -p packages repository
+            \endcode
+    \endlist
+
+    The generated \c repository directory will now contain a full copy of the
+    package data and some additionally generated metadata, such as SHA
+    checksums.
+
+    The directory now needs to be made available at the URL set in
+    \c config.xml: \c{http://localhost/repository}. How this is done depends on
+    the platform and web server used. If you do not have a running web server
+    yet, but have Python available, you should be able to start a minimal web
+    server from the command line. Make sure you are in the example directory,
+    and then enter:
+
+    \code
+        python -m SimpleHTTPServer 80
+    \endcode
+
+    You should now be able to open and explore \l{http://localhost/repository}
+    in your web browser.
+
+    \note If you do not have enough permissions to set up a web server locally,
+    you can also specify an absolute \c{file:///} URL as the value of the \c URL
+    element in \c config.xml. For example,
+    \c file:///C:/Qt/QtIFW/examples/online/repository would be a valid URL on
+    Windows if \c repository is located in \c C:\Qt\QtIFW\examples\online.
+
+    \section1 Generating the Example Installer
+
+    To create the example installer, switch to the example source directory on
+    the command line and enter the following command:
+
+    \list
+        \li On Windows:
+            \code
+            ..\..\bin\binarycreator.exe --online-only -c config\config.xml -p packages installer.exe
+            \endcode
+        \li On Linux or OS X:
+            \code
+            ../../bin/binarycreator --online-only -c config/config.xml -p packages installer
+            \endcode
+    \endlist
+
+    You should now be able to run the installer and install from the repository.
+
+    \section1 Providing Updates
+
+    A benefit of using an online installer is that you can add new packages over
+    time or update the existing ones. During new installations, the new and
+    updated packages are automatically used, and existing installations can be
+    upgraded to use them.
+
+    To update a package, you need to increase its \c <Version> element in
+    \c package.xml. The \c packages_update directory in the example folder is
+    a copy of \c the package directory, with an updated component
+    A. To deploy an update, you again use \c{repogen}:
+
+    \list
+        \li On Windows:
+            \code
+            ..\..\bin\repogen.exe --update-new-components -p packages_update repository
+            \endcode
+        \li On Linux or OS X:
+            \code
+            ../../bin/repogen --update-new-components -p packages_update repository
+            \endcode
+    \endlist
+
+    \c {--update-new-components} lets \c {repogen} compare the version
+    numbers of components in the repository and the packages directory, and
+    only updates packages that are new, or have a higher version number.
+    See also the \l{Summary of repogen Parameters}.
+
+    If you then run the maintenance tool from the previous installation and
+    select \gui {Update Components}, you should see that an update of package
+    \c A is available.
+
+    For more information on providing updates, see \l {Promoting Updates}.
+
+    \image qtifw-examples-online-1.png
+*/
diff --git a/examples/examples.pro b/examples/examples.pro
index d88e5611f..75cb2e20b 100644
--- a/examples/examples.pro
+++ b/examples/examples.pro
@@ -7,6 +7,7 @@ SUBDIRS += \
   dynamicpage \
   licenseagreement \
   modifyextract \
+  online \
   openreadme \
   quit_installer \
   registerfileextension \
diff --git a/examples/online/README b/examples/online/README
new file mode 100644
index 000000000..a29944668
--- /dev/null
+++ b/examples/online/README
@@ -0,0 +1,26 @@
+Shows how to set up an online installer.
+
+The example uses a very simple web server shipped with python.
+
+Generate online repository with
+
+  repogen -p packages repository
+
+Generate installer with
+
+  binarycreator --online-only -c config/config.xml -p packages installer
+
+Now launch a minimal web server in the local directory
+
+  python -m SimpleHTTPServer 80
+
+This should make the content of the local directory available under
+http://localhost
+
+You should be able to now launch the installer.
+
+To deploy an update, run
+
+  repogen --update-new-components -p packages_update repository
+
+and launch the maintenance tool in your installation.
diff --git a/examples/online/config/config.xml b/examples/online/config/config.xml
new file mode 100644
index 000000000..9aeedd00d
--- /dev/null
+++ b/examples/online/config/config.xml
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Installer>
+    <Name>Online Installer Example</Name>
+    <Version>1.0.0</Version>
+    <Title>Online Installer Example</Title>
+    <Publisher>The Qt Company</Publisher>
+    <!-- Directory name is used in component.xml -->
+    <StartMenuDir>Qt IFW Examples</StartMenuDir>
+    <TargetDir>@HomeDir@/IfwExample</TargetDir>
+    <RemoteRepositories>
+        <Repository>
+            <Url>http://localhost/repository</Url>
+        </Repository>
+    </RemoteRepositories>
+</Installer>
diff --git a/examples/online/online.pro b/examples/online/online.pro
new file mode 100644
index 000000000..37a0144b7
--- /dev/null
+++ b/examples/online/online.pro
@@ -0,0 +1,13 @@
+TEMPLATE = aux
+
+INSTALLER = installer
+
+INPUT = $$PWD/config/config.xml $$PWD/packages
+example.input = INPUT
+example.output = $$INSTALLER
+example.commands = ../../bin/binarycreator --online-only -c $$PWD/config/config.xml -p $$PWD/packages ${QMAKE_FILE_OUT}
+example.CONFIG += target_predeps no_link combine
+
+QMAKE_EXTRA_COMPILERS += example
+
+OTHER_FILES = README
diff --git a/examples/online/packages/A/data/A.txt b/examples/online/packages/A/data/A.txt
new file mode 100644
index 000000000..98114dd6e
--- /dev/null
+++ b/examples/online/packages/A/data/A.txt
@@ -0,0 +1,2 @@
+Example content for package A.
+
diff --git a/examples/online/packages/A/meta/package.xml b/examples/online/packages/A/meta/package.xml
new file mode 100644
index 000000000..08cef59c0
--- /dev/null
+++ b/examples/online/packages/A/meta/package.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Package>
+    <DisplayName>A</DisplayName>
+    <Description>Example component A</Description>
+    <Version>1.0.2-1</Version>
+    <ReleaseDate>2015-01-01</ReleaseDate>
+    <Default>true</Default>
+</Package>
diff --git a/examples/online/packages/B/data/B.txt b/examples/online/packages/B/data/B.txt
new file mode 100644
index 000000000..1ee864074
--- /dev/null
+++ b/examples/online/packages/B/data/B.txt
@@ -0,0 +1,2 @@
+Example content for package B.
+
diff --git a/examples/online/packages/B/meta/package.xml b/examples/online/packages/B/meta/package.xml
new file mode 100644
index 000000000..44e90b9a2
--- /dev/null
+++ b/examples/online/packages/B/meta/package.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Package>
+    <DisplayName>B</DisplayName>
+    <Description>Example component B</Description>
+    <Version>1.0.0-1</Version>
+    <ReleaseDate>2015-01-01</ReleaseDate>
+    <Default>true</Default>
+</Package>
diff --git a/examples/online/packages_update/A/data/A.txt b/examples/online/packages_update/A/data/A.txt
new file mode 100644
index 000000000..ed7f1ea55
--- /dev/null
+++ b/examples/online/packages_update/A/data/A.txt
@@ -0,0 +1,2 @@
+Example content for package A (new version!).
+
diff --git a/examples/online/packages_update/A/meta/package.xml b/examples/online/packages_update/A/meta/package.xml
new file mode 100644
index 000000000..d8010a2c0
--- /dev/null
+++ b/examples/online/packages_update/A/meta/package.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Package>
+    <DisplayName>A</DisplayName>
+    <Description>Example component A</Description>
+    <Version>1.0.3-1</Version>
+    <ReleaseDate>2015-01-01</ReleaseDate>
+    <Default>true</Default>
+</Package>
diff --git a/examples/online/packages_update/B/data/B.txt b/examples/online/packages_update/B/data/B.txt
new file mode 100644
index 000000000..1ee864074
--- /dev/null
+++ b/examples/online/packages_update/B/data/B.txt
@@ -0,0 +1,2 @@
+Example content for package B.
+
diff --git a/examples/online/packages_update/B/meta/package.xml b/examples/online/packages_update/B/meta/package.xml
new file mode 100644
index 000000000..44e90b9a2
--- /dev/null
+++ b/examples/online/packages_update/B/meta/package.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Package>
+    <DisplayName>B</DisplayName>
+    <Description>Example component B</Description>
+    <Version>1.0.0-1</Version>
+    <ReleaseDate>2015-01-01</ReleaseDate>
+    <Default>true</Default>
+</Package>