Dependencies
============

Required:

  * C++ compiler with C++17 support
  * CMake >= 3.22. A particular version of Qt may require a newer
    version of CMake.
  * Make
  * Qt 5.3.2 - 6. DPSO_QT_VERSION CMake option.
  * libtesseract >= 4.1.0
  * pkg-config to find libtesseract
  * libx11
  * libxext - for X11 Nonrectangular Window Shape Extension
  * libintl. On some systems libintl is a part of GNU C library and
    doesn't need to be installed separately.
  * gettext tools >= 0.19 (msgfmt is needed to compile gettext message
    catalogs).

Optional:

  * pandoc to generate HTML manual. DPSO_GEN_HTML_MANUAL CMake
    option.

To install dependencies on Debian, Ubuntu, and derivatives, run:

    sudo apt-get install cmake make pkg-config g++ qtbase5-dev \
        libtesseract-dev libx11-dev libxext-dev gettext pandoc


Building
========

You can build dpScreenOCR with the following commands:

    cd path_to_dpscreenocr_source
    mkdir build
    cd build
    cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release ..
    make

You can configure the build with various CMake options; run
"cmake -LH .." to see them all. Options specific to dpScreenOCR have
the "DPSO_" prefix.


Installing
==========

Use "make install" and "make uninstall" to install and remove
dpScreenOCR, respectively. You can set the installation prefix via
CMAKE_INSTALL_PREFIX at the build stage; the default is "/usr/local".

Since version 1.1, dpScreenOCR supports relocation: it loads resources
from paths relative to the location of the executable, rather than
from absolute paths based on the installation prefix. For example, you
can install in "~/dpscreenocr", then move the "dpscreenocr" directory
to a different location, and the program will still work correctly.


Packaging
=========


Bundle
------

You can build dpScreenOCR as a bundle - a self-contained directory
that includes the program itself, all the necessary libraries, and a
launcher.

It's recommended to build the bundle from within a Docker environment
from the "tools/dpscreenocr_build_env" directory. It uses an old OS
distribution to ensure that the bundle will work even on legacy
systems, and has all the necessary dependencies configured. See
"tools/dpscreenocr_build_env/readme.txt" for the details.

If you are not using a Docker image, you will need to install
additional dependencies beyond those listed in the "Dependencies"
section:

  * libcurl >= 7.28. If your system provides several flavors of
    libcurl, it doesn't matter which one to install: dpScreenOCR will
    dynamically load libcurl instead of linking against it, so only
    the headers are needed when building. It usually makes sense to
    use the flavor whose runtime version is already installed: this
    avoids downloading unnecessary transitive dependencies.

  * libjansson >= 2.7

On Debian, Ubuntu, and derivatives, you can install the above with:

    sudo apt-get install libcurl4-gnutls-dev libjansson-dev

The process of creating the bundle is now independent of whether you
are inside a Docker image: use the steps described in the "Building"
section, with two important differences:

  * Disable DPSO_USE_DEFAULT_TESSERACT_DATA_PATH, enable
    DPSO_DYNAMIC_CURL and DPSO_ENABLE_UPDATE_CHECKER CMake options.

  * Call "make bundle_archive" instead of "make".
