/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $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$
**
****************************************************************************/

/*!
    \page uacpp-index.html
    \title Setting up UACPP SDK
    \brief Instructions how to setup UACPP SDK

    \section1 Download and Installation

    The UACPP plugin integrates the professional C++ based OPC UA SDK from Unified Automation GmbH
    into Qt OPC UA. You can also test this using the evaluation version of the SDK,
    but in this tutorial we show how to build the C++ SDK (full version)
    and the Qt OPC UA plugin from source for best flexibility and portability.

    By building the SDK from source, we can choose to build static
    libraries instead of dynamic libraries, which reduces runtime
    dependencies and code size.
    The very same version of the OpenSSL library that was used to build Qt has to be used.
    Otherwise there will be dynamic linker errors when loading the library.

    Binaries depend on specific versions of OpenSSL and will not run on all Linux distributions.

    When using the evaluation version, you can skip the step for Building the SDK,
    but you must ensure to use the same compiler, OpenSSL and LibXML2 that were used for building the Eval SDK.

    \section1 Requirements

    \list
     \li Qt 5.12 or higher
     \li Qt OPC UA
     \li Unified Automation C++ SDK 1.6.x or higher.
     \li C++ Toolchain (GCC on Linux or MSVC on Windows)
     \li CMake 2.8 or higher
     \li Ninja (a faster make tool, GNU make would work too)
    \endlist

    When using GNU make instead of Ninja, use "-G 'Unix Makefiles'" instead of "-G Ninja" in
    the CMake calls.

    \section1 Building on Linux using GCC

    \section2 Preparations

    We assume that you have a development machine with a running C++ toolchain and Qt installed.
    If not, install it now.

    Example for Debian based systems:

    \code
    sudo apt install build-essential
    sudo apt install cmake cmake-curses-gui cmake-qt-gui
    sudo apt install ninja
    \endcode

    In this tutorial, we show example install commands using the \c apt
    package management. On other distributions, you can install the
    same tools, just the exact commands and package names may differ.

    \section2 Building the SDK

    On Linux, we want to build using the system provided OpenSSL library.
    Therefor you need to install OpenSSL development packages. The same
    applies for LibXML2.

    \code
    sudo apt install libssl-dev libxml2-dev
    \endcode

    At the time of writing, the pre-built Qt library was still built against OpenSSL1.0.
    Debian Stretch and newer default to OpenSSL1.1. So we need to install the older
    OpenSSL1.0 devel package to make the SDK and Qt use the same library version.
    OpenSSL1.0 and OpenSSL1.1 are not binary compatible.

    \code
    sudo apt install libssl1.0-dev libxml2-dev
    \endcode

    Building the C++ OPC UA SDK:

    \code
    cd /path/to/sdk
    export SDKDIR=$PWD
    # force position independent code even for static libraries (to make it working in a Qt plugin)
    export CFLAGS=-fPIC
    export CXXFLAGS=-fPIC
    # create out-of-source build directory
    mkdir build
    cd build
    # Create Ninja build file (like a Makefile)
    cmake -GNinja -DCMAKE_INSTALL_PREFIX=$SDKDIR -DCMAKE_BUILD_TYPE=Debug -DBUILD_SHARED_LIBS=off -DBUILD_SHARED_STACK=off -DBUILD_UAMODELS=off -DBUILD_UAMODULE=off -DBUILD_COREMODULE=off -DBUILD_EXAMPLES=off -DBUILD_UASERVERCPP_APP=off -DBUILD_TESTING=off ..
    # build and install the SDK
    ninja
    ninja install
    # clear compiler flags again to avoid problems with other builds
    export CFLAGS=
    export CXXFLAGS=
    \endcode

    Note: You can replace \c Debug in \c "CMAKE_BUILD_TYPE=Debug" with \c Release, \c MinSizeRel, or \c RelWithDebInfo to build a release version.
    See \l{https://cmake.org/cmake/help/v3.8/variable/CMAKE_BUILD_TYPE.html}{here} for more information.

    \section2 Building the Qt OPC UA UACPP Plugin

    \code
    cd /path/to/qtopcua
    qmake CONFIG+=debug -- UACPP_PREFIX=$SDKDIR
    make -j $(nproc)
    make install
    \endcode

    The output of the \c qmake configuration step indicates whether the detection was successful:

    \code
    Unified Automation C++ SDK ............. yes
    \endcode

    If not, you can inspect the config.log to find the reason for the problem.

    \section1 Building on Windows using MSVC

    \section2 Preparations

    You need to install Visual Studio, Qt, CMake, and Ninja.
    Please ensure the CMake and Ninja executables are in PATH,
    so that the tools work on the console.

    Downloads:

    \list
     \li https://cmake.org
     \li https://ninja-build.org/
    \endlist

    \section2 Building the SDK

    We assume that you have installed Visual Studio. To get a working toolchain, you need to open the Visual Studio Command Prompt.
    It is important to run CMake also from this console, no matter if it's the \c cmake command or the CMake GUI.
    Otherwise compiler detection may fail.

    Important: All components need to be built with the same Visual Studio version.

    Building the C++ OPC UA SDK:

    \code
    cd \path\to\sdk
    set SDKDIR=%CD%
    # create out-of-source build directory
    mkdir build
    cd build
    # Create Ninja build file (like a Makefile)
    cmake -GNinja -DCMAKE_INSTALL_PREFIX=%SDKDIR% -DCMAKE_BUILD_TYPE=Debug -DBUILD_SHARED_LIBS=off -DBUILD_SHARED_STACK=off -DBUILD_UAMODELS=off -DBUILD_UAMODULE=off -DBUILD_COREMODULE=off -DBUILD_EXAMPLES=off -DBUILD_TESTING=off ..
    # build and install the SDK
    ninja
    ninja install
    \endcode

    Note: You can replace \c Debug in \c "CMAKE_BUILD_TYPE=Debug" with \c Release, \c MinSizeRel, or \c RelWithDebInfo
    to build a release version. See \l{https://cmake.org/cmake/help/v3.8/variable/CMAKE_BUILD_TYPE.html}{here} for more information.

    Instead of building on console, you can also generate a Visual Studio solution
    by replacing "-GNinja" with "-G 'Visual Studio 15 2017'". See "cmake --help" to get a list of available generators.

    \section2 Building the Qt OPC UA UACPP Plugin

    For building the Qt plugin, you need to open the Qt Command prompt for the same Visual Studio version
    as you used for building the SDK.

    \code
    cd \path\to\qtopcua
    qmake CONFIG+=debug -- UACPP_PREFIX=%SDKDIR%
    nmake
    nmake install
    \endcode

    The output of the \c qmake configuration step indicates whether the detection was successful:

    \code
    Unified Automation C++ SDK ............. yes
    \endcode

    If not, you can inspect the config.log to find the reason for the problem.

    \section1 Final notes

    The SDK and Qt OPC UA can also be compiled with other compilers like MinGW-w64 for Windows,
    Clang or can be cross-compiled using various cross-compilers, but this is out of scope of this document.

    Please consult the documentation \l{http://documentation.unified-automation.com/uasdkcpp/1.6.3/html/CrossCompiling.html}{here} for cross-compiling the SDK
    or contact the support if you have any questions.

    \section1 Setting up the Key Infrastructure

    With the UACPP Plugin, you can create secure connections with Qt OPC UA.
    To make this work, each application instances (installation of a program),
    needs to have its own \c {Application Instance Certificate} and the according private key.

    Follow the common instructions on \l {Creating OPC UA Clients with security support} to setup the keys.

    \section1 Demo Server

    For testing the client with security, you can download one of Demo Servers from Unified Automation for free (Windows only).

    https://www.unified-automation.com/downloads/opc-ua-servers.html

    In addition, you can download evaluation versions of various OPC UA Server SDKs which also contain demo servers (Windows and Linux).

    https://www.unified-automation.com/downloads/opc-ua-development.html

*/
