QXmlEdit Installation
=====================

Requirements
============

QXmlEdit requires QT 4 or QT 5 (4.7.3 or higher) to be installed. Qt sqlite driver and QtSql module are
required. OpenGL is required if QwtPlot3D library is used.

Quick Guide
===========

QXmlEdit is built and installed using qmake. The package is composed by
an application and some libraries.
In the main folder there is a main QxmlEdit.pro file.

Extract the source, go to top folder

   qmake
   make
   sudo make install

The file DISTRIBUTING contains a list of files that should take part in a binary distribution.
To configure the destination folders, check the marker 'BEGIN INSTALLATION FOLDERS DECLARATION' in
each project file present in the src subfolder.

The program is composed by some shared objects (or DLL) loaded at the program start. When installing
on a Linux system make sure that the libraries are in the library search path.

To compile a release version use
qmake "CONFIG+=release"

In the main folder there are "compile.xxx" batch commands for Linux and Windows, to configure and compile the project.

To parametrize the installation
-------------------------------
The qmake project reads the following variables from environment variables.

Folder for data: QXMLEDIT_INST_DATA_DIR.
Folder for the executable: QXMLEDIT_INST_DIR.
Folder for the documentation: QXMLEDIT_INST_DOC_DIR.
Folder for the shared libraries: QXMLEDIT_INST_LIB_DIR.
Folder for the language translations: QXMLEDIT_INST_TRANSLATIONS_DIR.
Folder for the includes of the xml edit widget: QXMLEDIT_INST_INCLUDE_DIR.
Folder for the icon: QXMLEDIT_INST_ICON_DIR.
Folder for the appdata file: QXMLEDIT_INST_METAINFO_DIR.
Folder for the desktopinfo file: QXMLEDIT_INST_DESKTOPINFO_DIR.
Disable the precompiled headers by setting the value to non empty string: QXMLEDIT_INST_AVOID_PRECOMP_HEADERS.
Disable the link with QwtPlot3D setting QXMLEDIT_NO_QWTPLOT to non empty string.
Disable the icon installation: set QXMLEDIT_NO_ICON to non empty string.
Enable C++11 compiler option defining QXMLEDIT_INST_USE_C11=y (default: not enabled).
Disable tips management: QXMLEDIT_COMPILE_DISABLE_TIPS non void (default: tips enabled).
Disable appdata meta info installation: set QXMLEDIT_NO_METAINFO to non empty string.
Disable desktop info file installation: set QXMLEDIT_NO_DESKTOPINFO to non empty string.
Disable the Qt SCXML module setting QXMLEDIT_DISABLE_SCXML to non empty string (default: SCXML enabled if Qt >= 5.7.0).
To disable the version number in the libraries name set QXMLEDIT_NOVERSIONED to Y.
To enable the version number in the libraries name set QXMLEDIT_NOVERSIONED to N.
 -Note: On Windows the version number in the name is disabled by default, on Linux is enabled.
 -Note: this is a departure from previous version on Linux and usually this option is not needed.
To append to the library name the version number as a suffix set QXMLEDIT_LIB_SUFFIX to a value (usually not needed).
To disallow convert compiler warnings in errors set QXMLEDIT_INST_DISABLE_COMPILE_WARNINGS to a value.
To disable TODO annotation in code while developing set QXMLEDIT_DISABLE_TODO_CONFIG to a value (release
  compilations automatically disable TODOs. No need to define this variable for a release.

QwtPlot3D library is linked (statically) by default unless QXMLEDIT_NO_QWTPLOT environment variable is defined and not empty.
It is used as an optional component and can be excluded without compromising QXmlEdit functionalities.
Warning: QwtPlot3D library requires OpenGL.

The Qt module SCXML is enabled by default when the Qt version is greater then 5.7.0, but can be
disabled via compiler options.

To force the executable name all lowercase (qxmledit) as in Unix style, the following environment variable
must be set to 1:
QXMLEDIT_UNIX_LOWERCASE_NAME
For unix, except MacOS, the flag is automatically set.

The variable QXMLEDIT_VERSIONED force library version number if not empty. On Linux the libraries are versioned by default.
If the environment variables are not set, a default is used.
The version in the name of libraries can be turned off defining the variable QXMLEDIT_NOVERSIONED to any value.

It is possible to override the environment variables and set directly the variables qmake command line.
Example:
 qmake "QXMLEDIT_INST_DATA_DIR = some_folder"

It is possible to test the installation without compiling all the sources.
Setting the variable QXMLEDIT_USE_FAKE_SOURCES to any value recalls an alternative set of source files.
Warning: this is a developer only option; the program compiled with this option contains no features.

IMPORTANT NOTE FOR LINUX INSTALLERS
-----------------------------------
The naming of the libraries is changed from version 0.9.17 removing the suffix by default on Linux.
A speedy install test can be done setting the variable QXMLEDIT_USE_FAKE_SOURCES to a value. An alternative
   set of sources (a fake) will be used to create the release in a fraction of time needed for a full version.
Starting from 0.8.15 the name of the executable on Unix systems, except MacOS, is lowercase by default.
This behavior can be changed via the QXMLEDIT_UNIX_LOWERCASE_NAME variable.
The .desktop and .appdata file have been updated.
This can require some attention when upgrading a previously installed package.

Note for Qt4 compatibility
--------------------------
QXmlEdit is source compatible with Qt4.7.3, Qt4.8 and Qt5.

Additional resources
--------------------
There are resources for a Linux desktop installation:

.desktop file in: install_scripts/environment/desktop/QXmlEdit.desktop
AppData file in: install_scripts/environment/desktop/QXmlEdit.appdata.xml
man file:  install_scripts/environment/man/qxmledit.1

Pixmap icons in: install_scripts/environment/icon
Scalable icon: source/images/icon.svg

Mac OS X Note
=============
Snippets and sample style files should be copied in a "SharedSupport" directory in the final bundle.
There is an installation script to create the final package after the build. The script expects some enviroment
variables to be set, as specified in the script itself.
MacOS X Mavericks has been tested with Qt5.2.


Windows Users Note
==================

In the install_scripts directory there is a NSIS NullSoft installer script that can be used to
generate a package compatible with Windows Installer. Simply put required files into "distribution"
subdirectory and generate the script. The needed libraries are in the Qt and mingw packages.
There is a script for using QT5 and another one for QT4.

Qt must be compiled statically to build a single file executable.

Projects
--------
Main project: QXmlEdit.pro
Unit tests: test/test.pro
Test to use the XML editor as a library: testlib/testlib.pro
Alternative project to compile QXmlEdit as a monolithic app: singleapp/singleapp.pro (Note: this project is not supported, it is intended for development).

Other info
----------
Site: http://qxmledit.org

Snapcraft
---------
A build file for Snapcraft packaging, courtesy of the package maintainer, is in the "install_scripts" folder.
Please note that QXmlEdit team has not any direct relationship with Snapcraft.
