/** \mainpage digiKam project API reference.
    \author (c) 2001-2026 digiKam team.
    \brief digiKam is an advanced open-source digital photo management application that runs on Linux, Windows, and macOS.
    \image html logo-digikam.png

\section sourcedirs Source Code Directories

   digiKam is split into a number of components, each ones located to a dedicated directory.
   The main namespace is Digikam for the digiKam application and all sub components.
   A second namespace is ShowFoto for the stand alone version of digiKam image editor.

   See below the complete list of directories used by the project:

| SOURCE TREE-VIEW                                            | DETAILS                                                                 |
| ----------------------------------------------------------- | ----------------------------------------------------------------------- |
|. AUTHORS                                                    | List of developers and contributors to the project                      |
|. bootstrap.api                                              | Script to build API documentation (HTML + PDF)                          |
|. bootstrap.linux                                            | Configuration script to compile under Linux                             |
|. bootstrap.local                                            | Configuration script to compile a local version under Linux             |
|. bootstrap.macports                                         | Configuration script to compile under macOS with Macports               |
|. bootstrap.homebrew                                         | Configuration script to compile under macOS with HomeBrew               |
|. bootstrap.vcpkg                                            | Configuration script to compile under Windows with VPCKG                |
|. bootstrap.tarball                                          | Script to build the release tarball                                     |
|. build                                                      | Temporary directory created by bootstrap script to host compiled files  |
|. ChangeLog                                                  | Note about how to list source code changes since the project origin     |
|. CMakeLists.txt                                             | Main Cmake script including lead compilation rules for the project      |
|. COPYING                                                    | Link to main project license                                            |
|. LICENSES                                                   | All licenses used in the project                                        |
|. Mainpage.dox                                               | API documentation main page based on Doxygen                            |
|. Messages.sh                                                | Script to extract strings for translators                               |
|. NEWS                                                       | Notice to resume all project changes done at release time               |
|. README.DEVEL                                               | Read me file for developers                                             |
|. README.md                                                  | First start helper documentation                                        |
|. README.BUNDLES                                             | Read me for Linux, macOS, and Windows bundles support                   |
|. build                                                      | Directory to store compiled files and binary targets                    |
|. core                                                       | All source code are hosted in this directory                            |
|. . app                                                      | Lead application component                                              |
|. . . date                                                   | All date relevant views                                                 |
|. . . dragdrop                                               | Drag and drop helper classes                                            |
|. . . filters                                                | Tags filter widgets                                                     |
|. . . items                                                  | Item management classes                                                 |
|. . . . delegate                                             | Item view delegate                                                      |
|. . . . overlays                                             | Item overlays                                                           |
|. . . . thumbbar                                             | Item thumbbar widget                                                    |
|. . . . utils                                                | Item utility classes                                                    |
|. . . . views                                                | Item view classes                                                       |
|. . . main                                                   | Main digiKam application                                                |
|. . . utils                                                  | Generic utility classes                                                 |
|. . . views                                                  | Views classes                                                           |
|. . . . preview                                              | Item preview classes                                                    |
|. . . . sidebar                                              | Left sidebar contents                                                   |
|. . . . stack                                                | Stacked-view show in central place of main digiKam window               |
|. . . . tableview                                            | Table-view classes                                                      |
|. . . . utils                                                | View utility classes                                                    |
|. . cmake                                                    | Extra Cmake scripts will be hosted here                                 |
|. . . modules                                                | Cmake scripts to find extra dependencies                                |
|. . . templates                                              | Cmake template files used at configuration time                         |
|. . data                                                     | Application data files will be hosted here                              |
|. . . colorschemes                                           | GUI Color scheme files                                                  |
|. . . database                                               | Database XML configuration files                                        |
|. . . facesengine                                            | Face detection and recognition data files                               |
|. . . filters                                                | Image filters data files                                                |
|. . . geolocation                                            | Geolocation tool data files                                             |
|. . . hotplug                                                | Hotplug Linux integration files                                         |
|. . . htmlgallery                                            | HTML gallery tool data files                                            |
|. . . icons                                                  | Application icons                                                       |
|. . . metadata                                               | Metadata tool data files                                                |
|. . . pics                                                   | Application pictures                                                    |
|. . . printcreator                                           | Print Creator tool data files                                           |
|. . . profiles                                               | Basis open source ICC color profiles                                    |
|. . . scripts                                                | Miscs maintenance scripts                                               |
|. . dplugins                                                 | All digiKam plugins will be hosted in this directory                    |
|. . . bqm                                                    | All Batch Queue Manager plugins                                         |
|. . . . colors                                               | All color adjustments plugins                                           |
|. . . . convert                                              | All file convert plugins                                                |
|. . . . custom                                               | All user-custom processing plugins                                      |
|. . . . decorate                                             | All decorate item plugins                                               |
|. . . . enhance                                              | All enhance item plugins                                                |
|. . . . filters                                              | All filter item plugins                                                 |
|. . . . metadata                                             | All metadata edit plugins                                               |
|. . . . transform                                            | All transform item plugins                                              |
|. . . editor                                                 | All Image Editor plugins                                                |
|. . . . colors                                               | All color adjustments plugins                                           |
|. . . . decorate                                             | All decorate item plugins                                               |
|. . . . enhance                                              | All enhance item plugins                                                |
|. . . . file                                                 | All file processing plugins                                             |
|. . . . filters                                              | All filter item plugins                                                 |
|. . . . transform                                            | All transform item plugins                                              |
|. . . generic                                                | All generic plugins                                                     |
|. . . . import                                               | Tools to import items                                                   |
|. . . . metadata                                             | Plugins to change items metadata                                        |
|. . . . tools                                                | Plugins hosted in Tools main menu                                       |
|. . . . view                                                 | Plugins to display items                                                |
|. . . . webservices                                          | All plugins to import and export items to remote web-services           |
|. . . rawimport                                              | All Raw import plugins                                                  |
|. . . dimg                                                   | All DImg image loader plugins                                           |
|. . libs                                                     | digiKam core sub-components (few are shared with Showfoto)              |
|. . . album                                                  | All classes use to manage digiKam albums operations and properties      |
|. . . database                                               | All low level database interface is here                                |
|. . . . collection                                           | All classes relevant of collections management                          |
|. . . . coredb                                               | The core database interface used to host all image properties           |
|. . . . dbjobs                                               | All database multi-threaded jobs                                        |
|. . . . engine                                               | The low level database engine classes                                   |
|. . . . haar                                                 | The similarity low level algorithms to compute image finger-prints      |
|. . . . history                                              | The item history classes for the database                               |
|. . . . item                                                 | The database item classes, including containers, lister, and scanner    |
|. . . . models                                               | The database model classes                                              |
|. . . . server                                               | The Mysql internal server                                               |
|. . . . similaritydb                                         | The similarity database                                                 |
|. . . . tags                                                 | The database tags management classes                                    |
|. . . . thumbsdb                                             | The thumbnails database                                                 |
|. . . . utils                                                | Miscs tools and widgets used with database                              |
|. . . dialogs                                                | Common dialogs                                                          |
|. . . dimg                                                   | The Qt digiKam image data container support ICC and 16 bits color depth |
|. . . . filters                                              | All image filters will be hosted here. All support 16 bits color depth  |
|. . . . . auto                                               | Auto colors correction filters                                          |
|. . . . . bcg                                                | Brightness-Contrast-Gamma filter                                        |
|. . . . . bw                                                 | Black and White image converter, including infrared filter              |
|. . . . . cb                                                 | Colors balance filter                                                   |
|. . . . . curves                                             | Colors curves filter                                                    |
|. . . . . decorate                                           | Decorate filters                                                        |
|. . . . . film                                               | Analog film emulation filters                                           |
|. . . . . fx                                                 | Special effect filters                                                  |
|. . . . . greycstoration                                     | Cimg based restoration filter                                           |
|. . . . . hsl                                                | Hue-Saturation-Lightness filter                                         |
|. . . . . icc                                                | Icc color profile filters                                               |
|. . . . . imgqsort                                           | The image quality sort algorithms                                       |
|. . . . . lc                                                 | Local contrast filter (pseudo HDR)                                      |
|. . . . . lens                                               | Lens corrections filters, including Qt Lensfun interface                |
|. . . . . levels                                             | Color levels filter                                                     |
|. . . . . nr                                                 | Wavelets noise reduction filter                                         |
|. . . . . redeye                                             | Red-eyes parser and fixer                                               |
|. . . . . sharp                                              | Image sharp filter, including Unsharped-mask and Refocus                |
|. . . . . transform                                          | All image transformation filters                                        |
|. . . . . wb                                                 | White balance filter                                                    |
|. . . . imagehistory                                         | Image history interface for image container                             |
|. . . . loaders                                              | All DImg image loaders interface                                        |
|. . . metadataengine                                         | The metadata wrapper based on Exiv2 for image and FFMpeg for video      |
|. . . dngwriter                                              | Qt classes to convert RAW files to DNG format                           |
|. . . . extra                                                | DNG and XMP sdks from Adobe                                             |
|. . . dplugins                                               | All shared dplugins classes are hosted here                             |
|. . . . core                                                 | Low level classes for plugins definitions                               |
|. . . . iface                                                | Low level classes for host interface definitions                        |
|. . . . setup                                                | Classes to setup plugins in configuration panel                         |
|. . . . webservices                                          | Common classes for Webservices tools                                    |
|. . . . widgets                                              | Common widget sfor plugins                                              |
|. . . dtrash                                                 | digiKam trash manager full independent of desktop trash                 |
|. . . facesengine                                            | Face detection and recognition engine + Faces database implementations  |
|. . . . detection                                            | Face detection modules                                                  |
|. . . . . opencv-dnn                                         | Deep-learning classes based on OpenCV to detect face                    |
|. . . . common                                               | Face containers                                                         |
|. . . . facedb                                               | Faces database classes                                                  |
|. . . . preprocessing                                        | Face pre-processing classes                                             |
|. . . . . recognition                                        | Preprocessor recognition module                                         |
|. . . . . shape-predictor                                    | Shape predictor algorithms                                              |
|. . . . recognition                                          | Face recognition modules                                                |
|. . . . . opencv-dnn                                         | Deep-learning classes based on OpenCV to recognize face                 |
|. . . fileactionmanager                                      | Classes to connect database and metadata actions to file operations     |
|. . . filters                                                | Widgets to filter items by metadata properties                          |
|. . . imageproperties                                        | All widgets used in right side-bar from all main views                  |
|. . . iojobs                                                 | Multithreaded jobs manager used with files operations                   |
|. . . jpegutils                                              | Utilities to process JPEG files                                         |
|. . . . libjpeg                                              | JPEG loss-less transform private implementations from libjpeg           |
|. . . kmemoryinfo                                            | Qt backend to analyze system memory information                         |
|. . . models                                                 | Qt models used with item views                                          |
|. . . notificationmanager                                    | Multi-desktop notifications wrapper                                     |
|. . . pgfutils                                               | Qt Classes to work with PGF image format                                |
|. . . progressmanager                                        | Multi-level operations progress widget                                  |
|. . . rawengine                                              | Qt classes to work with libraw decoder                                  |
|. . . . libraw                                               | Internal Libraw sdk                                                     |
|. . . settings                                               | digiKam settings manager                                                |
|. . . tags                                                   | Classes to play with tags                                               |
|. . . . tagsmanager                                          | Tags manager view                                                       |
|. . . template                                               | Metadata template support                                               |
|. . . threadimageio                                          | Classes to process thumbs and preview extraction including video support|
|. . . threads                                                | Classes to manage and chain threads using multi-core                    |
|. . . timeadjust                                             | Common classes time adjustments tools                                   |
|. . . transitionmngr                                         | Frames transitions manager                                              |
|. . . versionmanager                                         | Classes to manage versioning operations                                 |
|. . . video                                                  | Classes to play with video contents                                     |
|. . . widgets                                                | To host plenty of widgets used everywhere                               |
|. . . . colors                                               | Colors relevant views                                                   |
|. . . . combo                                                | Combo-box helper classes                                                |
|. . . . common                                               | Uncategorized widgets                                                   |
|. . . . files                                                | File operation classes                                                  |
|. . . . fonts                                                | Font management classes                                                 |
|. . . . graphicsview                                         | Graphics-view implementation (model-view)                               |
|. . . . iccprofiles                                          | ICC color profiles widgets                                              |
|. . . . imagehistory                                         | Image history widgets                                                   |
|. . . . itemview                                             | Item-view implementations (model-view)                                  |
|. . . . layout                                               | Layout helper classes                                                   |
|. . . . mainview                                             | Common top-level view implementations                                   |
|. . . . metadata                                             | Metadata widgets                                                        |
|. . . . range                                                | Range helper classes                                                    |
|. . showfoto                                                 | Stand alone image editor                                                |
|. . . main                                                   | Main Showfoto application                                               |
|. . . setup                                                  | Showfoto Setup views                                                    |
|. . . thumbbar                                               | Showfoto thumb-bar views                                                |
|. . tests                                                    | Unit tests                                                              |
|. . utilities                                                | digiKam utilities and advanced tools (few are shared with showfoto)     |
|. . . advancedrename                                         | Advance rename tool                                                     |
|. . . extrasupport                                           | Extra desktop features support as Baloo search engine                   |
|. . . facemanagement                                         | Face management classes and tools                                       |
|. . . firstrun                                               | First-run assistant to configure lead digiKam settings                  |
|. . . fuzzysearch                                            | Similarity search tools                                                 |
|. . . geolocation                                            | All geo-location tools are located here                                 |
|. . . . editor                                               | Tool to edit items geo-location                                         |
|. . . . geoiface                                             | All shared classes used by geo-location tools                           |
|. . . . geomapwrapper                                        | Legacy helper classes for geo-location support                          |
|. . . . mapsearches                                          | Tool to perform map searches                                            |
|. . . imageeditor                                            | The famous digiKam image editor, a lots of classes shared with Showfoto |
|. . . . core                                                 | Core implementation including canvas and tools interface                |
|. . . . dialogs                                              | Image editor dialogs                                                    |
|. . . . editor                                               | The core image editors classes                                          |
|. . . . main                                                 | The main digiKam image editor view, not shared with Showfoto            |
|. . . . widgets                                              | All common widgets                                                      |
|. . . import                                                 | The import tools, including USB Mass Storage and Gphoto2 support        |
|. . . . backend                                              | Camera backends                                                         |
|. . . . dialogs                                              | Import tools dialogs                                                    |
|. . . . items                                                | Import item classes                                                     |
|. . . . main                                                 | Import tool main view                                                   |
|. . . . models                                               | Import model classes                                                    |
|. . . . views                                                | Import view classes                                                     |
|. . . . widgets                                              | Import common widgets                                                   |
|. . . lighttable                                             | The Light-table tool to compare images side by side                     |
|. . . maintenance                                            | The digiKam tool to maintain the database contents                      |
|. . . queuemanager                                           | The famous Batch Queue Manager tool                                     |
|. . . . main                                                 | The main BQM view                                                       |
|. . . . manager                                              | The multi-core manager to run tools in background                       |
|. . . . tools                                                | All BQM tools classed by functions                                      |
|. . . . views                                                | The BQM internal views                                                  |
|. . . searchwindow                                           | The powerful advanced search tool                                       |
|. . . setup                                                  | All digiKam setup panel, with few ones shared with Showfoto             |
|. . . . album                                                | Album configuration views                                               |
|. . . . camera                                               | Camera configuration views                                              |
|. . . . collections                                          | Collection configuration views                                          |
|. . . . editor                                               | Image Editor configuration views                                        |
|. . . . metadata                                             | Metadata configuration views                                            |
|. . . slideshow                                              | The simple slideshow tool                                               |
|. po                                                         | Program translations                                                    |
|. project                                                    | Extra project parts                                                     |
|. . bundles                                                  | Bundles build scripts                                                   |
|. . . 3rdparty                                               | External components required to build bundles                           |
|. . . CD                                                     | Continuous deployment configurations                                    |
|. . . appimage                                               | Linux AppImage                                                          |
|. . . homebrew                                               | macOS package (HomeBrew version)                                        |
|. . . macports                                               | macOS package (Macports version)                                        |
|. . . vcpkg                                                  | Windows installer                                                       |
|. . documents                                                | Project documentations                                                  |
|. . reports                                                  | Static analyzers report scripts for Continuous Integration              |
|. . scripts                                                  | 3rdparty source code management scripts                                 |

\section externaldeps External Dependencies

Before compiling digiKam, you need to install all required tools and libraries. See the instructions here:

https://www.digikam.org/download/git/#install-external-dependencies

\section getsourcecode Get Source Code

\subsection softcomponents Software Components

digiKam project use a single git repository from GitLab to host whole source code base. The project page is given below:

https://invent.kde.org/graphics/digikam

The digikam handbook source code is hosted in a separate GitLab repository:

https://invent.kde.org/documentation/digikam-doc

\section develenv Development Environment

If you are a developer with push access to the git repositories, it is strongly recommended
to use the "kde:" prefix and let git use the read-only mirrors for pulling.

If you did not clone this repository from "kde:", do it again:

\code
    git config --global url.git://anongit.kde.org/.insteadof kde:
    git config --global url.ssh://git@git.kde.org/.pushinsteadof kde:
    git clone kde:digikam
\endcode

See below an example of \b .gitconfig file working with a developer account:

\code
[url "git://anongit.kde.org/"]
        insteadof = kde://

[url "git@git.kde.org:"]
        pushinsteadof = kde://

[url "ssh://git@git.kde.org/"]
        pushinsteadof = kde://

[alias]
        up = pull --rebase -v --stat
        ci = commit -a -v
[core]
        editor = mcedit

[user]
        name = my name
        email = my email

[push]
        default = tracking

[color]
        # turn on color
        diff = auto
        status = auto
        branch = auto
        interactive = auto
        ui = auto

[color "branch"]
        current = green bold
        local = green
        remote = red bold

[color "diff"]
        meta = yellow bold
        frag = magenta bold
        old = red bold
        new = green bold

[color "status"]
        added = green bold
        changed = yellow bold
        untracked = red

[color "sh"]
        branch = yellow
        [color "sh"]
\endcode

\section cmakeoptions Cmake Configuration Options

To configure the project with CMake, use dedicated "bootstrap" script for your platform where all available configuration
options are present with default values. See the instructions here:

https://www.digikam.org/download/git/#configure-with-cmake

\section setuplocaldev Setup Local Compilation and Run-Time

This section describes how to install digiKam from the git repository, while keeping a system-wide digiKam install.

This procedure is based on the configure script \b bootstrap.local

 1. Set the root directory for your git install in bootstrap.local (DIGIKAM_INSTALL_PREFIX variable)
 2. If you want a clean build directory, set CLEANROOT to 1
 3. Type the following command in your terminal:

\code
   $ ./bootstrap.local  # or "./bootstrap.local --eclipse" if you intend to use Eclipse
   $ cd build
   $ make
   $ make install
   $ KDESYCOCA="/your/root/directory/var/tmp/kde-$USER/ksycoca5" kbuildsycoca5
\endcode

To run digikam, use the following commands:

\code
   $ export KDESYCOCA=/your/root/directory/var/tmp/kde-$USER/ksycoca5
   $ export QT_PLUGIN_PATH=/your/root/directory/lib64/plugins:/your/root/directory/lib/plugins:$QT_PLUGIN_PATH
   $ export XDG_DATA_DIRS=/your/root/directory/share:$XDG_DATA_DIRS
   $ /your/root/directory/bin/digikam
\endcode

The same applies for all binaries in /your/root/directory/bin/

If your shell is bash, you can edit your \b .bashrc file (in $HOME) and add the following alias:

\code
 DIGIKAMROOT="/your/root/directory"
 alias digikam-dev="KDESYCOCA=\$DIGIKAMROOT/var/tmp/kde-$USER/ksycoca5 XDG_DATA_DIRS=\$DIGIKAMROOT/share:\$XDG_DATA_DIRS QT_PLUGIN_PATH=\$DIGIKAMROOT/lib64/plugins:\$DIGIKAMROOT/lib/plugins:\$QT_PLUGIN_PATH \$DIGIKAMROOT/bin/digikam"
\endcode

then you can start your newly installed digikam with

\code
    $ digikam-dev
\endcode

\section debugtraces Debug Traces At Run-Time

digiKam uses categorized logging at run-time. By default, all debug messages are printed on the console. To disable output, you can either
fine-grained control by using one or more logging categories listed below.

Note: under Windows, to catch all debug messages you need to install an extra Microsoft application named DebugView available at this url:
http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx

\subsection Enable Logging Using an Environment Variable

You can set the environment variable \b QT_LOGGING_RULES. Rules are divided by semicolons.

E.g. you can start digiKam like this on the command line with thumbnails and core database messages disabled:

\code
    export QT_LOGGING_RULES='digikam.thumbsdb=false:digikam.coredb=false'
    digikam
\endcode

\subsection digiKamloggincat Logging Categories in digiKam

All logging categories are listed in \include app/utils/digikam_debug.cpp source code.

\subsection moreaboutloggincat Further Reading

 For more details see the Qt framework documentation about logging categories available at this url:
 https://doc.qt.io/qt-5/qloggingcategory.html#details

\section cmakecompilrules Cmake compilation rules

\subsection cmakeintro Introduction

The whole project is written mostly in C++/Qt and the Cmake framework is used to compile under Linux, macOS, and Windows.
The Cmake rules have been configured to reduce the linking overhead and improve CPU utilization with modular design.

Independent Cmake configuration is presents in following folders:

 - root source dir
 - core
 - doc

The Cmake rules will build the following targets:

 - digikamcore shared lib
 - digikamdatabase shared lib
 - digikamgui shared lib
 - digikam executable
 - showfoto executable
 - plugin shared libraries (dplugins)
 - various test executables - if testing is enabled
 - various unit-tests - if testing is enabled

Each of them depend on various sources which must be compiled before.
A complete description of source code direction is given to the sourcedirs section.

\subsection cmakeimpldetails CMake Implementation Details

\subsubsection includedirs Include Directories

Local include directories are all managed by this snippet of code:

\code
    set(DK_INCLUDES_ALL "")
    HEADER_DIRECTORIES(DK_LOCAL_INCLUDES_RAW)
\endcode

The libjpeg- folders are all included, so we need to delete them all and include the correct one only:

\code
    # This macro will set all paths which do not contain libjpeg-
    # We will add later the directory we need

    FOREACH(var ${DK_LOCAL_INCLUDES_RAW})
        STRING(REGEX MATCH "libjpeg-" item ${var})
        IF(item STREQUAL "")
            LIST(APPEND DK_LOCAL_INCLUDES ${var})
        ENDIF(item)
    ENDFOREACH(var)

    set(DK_LOCAL_INCLUDES ${DK_LOCAL_INCLUDES}
                          libs/jpegutils/${DIGIKAM_LIBJPEG_DIR})

    include_directories(${DK_LOCAL_INCLUDES})
\endcode

There is no need for manual intervention to add new includes, even if you add a new folder, just keep in mind to use:

\code
    #include "tagmngrlistitem.h"
\endcode

instead of :

\code
    #include "models/tagmngrlistitem.h"
\endcode

\subsubsection sharedlibs Shared Libraries

To avoid linking overhead and make a better use of sources there are some dynamic libs as these one:

 - digikamcore : core components used by almost all executables as digiKam and Showfoto.
 - digikamdatabase : database components, also used together with digikamcore but only for digiKam

Please add sources to digikam core or digikam database only if they don't depend on any big component
from digikam main executable. These two shared libs must be kept small because they link in a lot of places

\subsubsection staticlibs Static Libraries

Currently cmake configuration features a lots of shared libraries as:

 - metadataedit
 - geolocationedit
 - digikamfaceengine

This libraries are linked in digikam main executable and some tests tools.

Avoid making static libraries if possible, and use OBJECT libraries instead.
Only make STATIC libraries which does not depend on other digikam code.
Also make sure you put the PRIVATE parameter when setting the target_link_libraries.

\code
    target_link_libraries(digikamcore
                          PRIVATE
                          Qt{QT_VERSION_MAJOR}::Core
                          Qt{QT_VERSION_MAJOR}::Gui
                          Qt{QT_VERSION_MAJOR}::Widgets
    )
\endcode


\subsubsection objlibs Object Libraries

While static libraries are still collection of objects, CMake offer a better approach by
allowing to specify an OBJECT library:

\code
    set(libslideshow_SRCS
        slidetoolbar.cpp
        slideosd.cpp
        slideproperties.cpp
        slideimage.cpp
        slideerror.cpp
        slideend.cpp
        slideshow.cpp
        slidehelp.cpp
        slideshowsettings.cpp
    )

    add_library(slideshow_src OBJECT ${libslideshow_SRCS})
\endcode

OBJECT library is a cmake internal implementation feature and allow to easily manage sources.
Here is an example of how to make a shared lib using OBJECT libraries:

\code
    add_library(digikamcore
                SHARED
                $<TARGET_OBJECTS:slideshow_src> # the lib we made few lines above
                $<TARGET_OBJECTS:digikamdatabasecore_src>
                $<TARGET_OBJECTS:dimg_src>
                ....
    )
\endcode

\section codecontrib Contribute To The Code

This section's purpose is to guide contributors and developers to help on the
digiKam project.

\subsection startopensource Starting With Open-Source

Before to contribute to digiKam project, please take a look to this link
which provide 10 golden rules for starting with open source project:

http://schlitt.info/opensource/blog/0541_10_golden_rules_for_starting_with_open_source.html

\subsection codeformat Source Code Formatting

Adhere to this style guide strictly while adding new code to digiKam or
working on existing code.

\subsubsection indentlength Indentation length

Indent with 4 spaces exactly.

For example:

\code
void function()
{
....int a;                          // 4 spaces from beginning
....for (int i = 0 ; i < 10 ; ++i)  // 4 spaces from beginning
....{                               // 4 spaces from beginning
........a = i;                      // 4 spaces from previous indent block
\endcode

Emacs by default will indent to 4 spaces
vim users add this to you .vimrc
 set tabstop=4

\subsubsection tabsspaces Tabs vs Spaces

Absolutely no tabs. Use a sensible editor which will convert tabs to spaces.
This will reduce unnecessary changes in your git commits.

Emacs by default will convert tab to spaces.
For vim users, add this to your .vimrc
  set expandtab

\subsubsection linelength Line length

Line length should never exceed 80 chars (unless really necessary - these
cases are rare). Having long lines greatly reduces readability of code

\subsubsection bracketing Bracketing

In all cases, {} brackets should start on a newline and should be
aligned with previous line (follow the indentation spaces). For example.

\code
class A
{ //new line
...

for (int i = 0 ; i < 10 ; ++i)
{ //new line

if (a == foobar)
{ //new line
...
}
else
{ // new line
..
}
\endcode

\subsubsection accessmod Positioning of Access modifiers

public, private, protected, public slots, ... should be aligned to the
beginning of the line with no margin

\code
class A
{
public: // aligned to left
...
private Q_SLOTS: // aligned to left
\endcode

Follow a consistent order in defining these attributes. The recommended
order is public, protected (functions), private (functions),
signals, public slots, protected slots, private slots, private (variables)

\subsection itemsnames Class, file and Variable names

\subsubsection classfilenames Class and filenames

- filenames should always be in lower-case
- class names should match the filenames. Capitalize the first letter and
  other letters logically to improve readability

\subsubsection protectvars Protected Member variables

- protected member variable names should always be of the form m_varName.
- Capitalize logically so that it becomes easy to read it. Do not capitalize
  the first letter after _ (Use m_varName not m_VarName)
- variable names should be indicative of their functionality and also of
  the type they belong too if they are instances of qt widgets.
  For example, QCheckBox* m_autoRotateCheckBox;

\subsubsection nomembvars Non-Member variables

- non-member variables should follow the same naming convention as the member
  variables, except for the leading m_

\subsubsection privmembvars Private Member variables

- private member variables must be stored in a d private container to reduce
  compilation time and improve binary compatibility between digiKam components.
  See more information how to use a 'd' private class at this url:

  https://community.kde.org/Policies/Library_Code_Policy

\subsection commentsspaces Comments and Whitespace

Use whitespaces liberally to improve readability. Add blank lines between logical
sections of the code.

Comment as much as possible. Position comments at the beginning of the
section/line you want to comment, NEVER at the end of the line, excepted for special
cases for ex to describe enum values.

\code
// put your comments here
a = (b == foobar) ? 1 : -1;

a = (b == foobar) ? 1 : -1; // you are asking for trouble by putting comments here
\endcode

\subsection headerfiles Header Files

- Add copyright to top of every file. Use the same header than others digiKam
  source code.
- Add double inclusion protection

\code
#pragma once

class AnotherNiceClass
{
...
}
\endcode

- Use forward declarations as much as possible.

\code
class QFileInfo;

class A
{
....QFileInfo* m_fileInfo = nullptr;
\endcode

\subsection autocodeformat Automatic source code formatting

The above coding style guidelines can be automatically applied with
astyle (http://astyle.sourceforge.net/).

Run it in the directory where the files are located that should be formatted.

To apply the coding guidelines with astyle is to use the
fileformatter.py script in project/scripts directory. This script will also clean up the
source tree and remove backup files that had been created by astyle,
if the appropriate command line argument is given.

To handle the command easier, create a bash function in ~/.bashrc, e.g.

\code
dkfrmcode()
{
    astyle --style=allman             \
           --indent=spaces=4          \
           --convert-tabs             \
           --indent-switches          \
           --break-blocks             \
           --break-closing-brackets   \
           --pad-header               \
           --align-pointer=type       \
           --indent-col1-comments     \
           --add-brackets             \
           --min-conditional-indent=0 \
           `find $1 -type f -name '*.cpp'` `find $1 -type f -name '*.c'` `find $1 -type f -name '*.h'`
}
\endcode

You can pass a parameter to the function, in this case the first parameter is the directory, where
files should be formatted.

Examples:

1. Run astyle in the current directory
\code
$> dkfrmcode
\endcode

2. Run astyle in a different directory
\code
$> dkfrmcode /home/user/code/git/digikam/
\endcode

\subsection generalrecommend General recommendations

Please take a look into this contrib page tips before to write code/patches for
digiKam project : http://techbase.kde.org/Contribute

Use the same .cpp/.h header than the rest of digiKam project.

Use a decent editor which does auto-indentation/syntax-highlighting for you, 
as Kate or QtCreator

There are excellent initializer scripts in the kdesdk
package for xemacs and vim which can substantially increase your productivity.

Just to give a taste of what i can do with emacs (and kdesdk):

* automatically insert copyright (and ifdefs) in new files.
* insertion of class function definitions for declared class
  functions in header with one keystroke
* switch between header and declaration files with one keystroke
* go to corresponding definition/declaration with one keystroke
* tab completion of variable/function names already declared.

\subsection gdbbacktrace GDB Backtrace

If you found a context to crash digiKam, you can provide a backtrace using GDB debugger.
digiKam need to be compiled with all debug info else the backtrace will not suitable.
There is a configure option for that:

\code
$> cmake . -DCMAKE_BUILD_TYPE=debugfull
$> make
$> su
$> make install/fast
\endcode

To make a backtrace with GDB use following command:

\code
$ gdb digikam
> catch throw
> run
> ...
> _crash here_
> ...
> bt
> _the backtrace is here_
> quit
\endcode

Post this backtrace at the right place (Bugzilla or development mailing list) for investigation by developers.

For Windows users, take a look on this tutorial :

http://techbase.kde.org/Development/Tutorials/Debugging/Debugging_on_MS_Windows

\subsection memleak Memory Leak

To check any memory leak problem in digiKam, valgrind is your friend (http://valgrind.org)
Try this command line to use with valgrind :

\code
valgrind --tool=memcheck --leak-check=full --error-limit=no --suppressions=project/reports/digikam.supp digikam
\endcode

NOTE: digikam.supp file is available in digikam/project sub-folder.

\subsection profilingcode Profiling With Cachegrind

Valgrind also includes a tool to find out in which parts of your code time is spent.

\code
valgrind --tool=callgrind digikam
\endcode

Profiling can be disabled at startup to limit the output to the code you are interested in.
Start with

\code
valgrind --tool=callgrind --instr-atstart=no digikam
\endcode

and prepare the situation you want to profile. Then, in another console, start profiling with
"callgrind_control -i on" and, after the situation has passed, request a profile dump with
"callgrind_control -d".
The resulting callgrind.out files need to be viewed with the kcachegrind program, e.g.:

\code
kcachegrind callgrind.out.16693.1
\endcode

\subsection unittests Unit Testing / Automated Testing

Unit Testing is great way to ensure that software units (in OOP this normally
means classes) work as expected. Wikipedia gives a good introduction to
Unit Testing:

http://en.wikipedia.org/wiki/Unit_testing

It is also worth to follow most of QTTest API rules with digiKam:

http://doc.qt.io/qt-5/qtest-tutorial.html

The digiKam test suite is located under tests and will be compiled if
BUILD_TESTING is turned ON at cmake configuration time. After compiling the source code
the tests can be executed via

\code
make test
\endcode

The console output while running the tests is stored in
Testing/Temporary/LastTest.log in the CMake binary dir.

All tests are simple binaries that can be executed separately if needed.

\subsection corruptedsignalslot Checking For Corrupt Qt Signal Slot Connection

Use this alias for running digikam:

\code
alias digikamdbg="digikam 2>&1 | tee - /tmp/digikam.out; echo -e \"\n\n\nPossible connection errors:\n\n\"; cat /tmp/digikam.out | grep -A2 'Object::connect'"
\endcode

It will print a list of connection warnings after terminating the program.
Moreover the complete console log of the last session is stored in
/tmp/digikam.out.

\subsection dupcodes Finding Duplicated Code

Code duplication should be avoided as bugs have to be fixed for every piece of
duplicated code. The current duplication can be analyzed eg. with Simian:
http://www.redhillconsulting.com.au/products/simian/

In the digikam checkout directory run:

\code
java -jar simian.jar `find . -regex '.*\.cpp\|.*\.h' | grep -v 3rdparty`
\endcode

This prints out a list of duplicated code segments.

\subsection docvalidcodecheck API Documentation Validation, User Documentation Validation, Source Code Checking

The following site check on a daily basis for the a.m. errors:
www.englishbreakfastnetwork.org/krazy/

It can be very useful, in particular before major releases.
Don't trust it blindly! Sometimes they propose too advanced modifications that
are no compatible with the prevailing include files.

\subsection appusability Usability Issues

OpenUsability project has define default menu structure and keyboard shortcuts:

http://wiki.openusability.org/guidelines/index.php/Appendices:Keyboard_Shortcuts

\subsection apidoc Generate API Documentation

To generate API documentation, you need to install:

- Doxygen program (http://www.doxygen.org)
- Dot program (http://www.graphviz.org)
- TeXLive package full version to generate the API doc in PDF (https://tug.org/texlive/)

Under Ubuntu run: 

\code
sudo apt install doxygen graphviz texlive-full
\endcode

After cmake generated a Makefile you can call 'make doc'. A new subfolder named
'html' will be created. Warning, this can take a while.

For finding documentation errors, doxygen generates a warning log file at the
cmake binary dir called 'doxygen-warn.log'.

\subsection speedupcompil Speed Up The Code-Compile-Test Cycle

Assuming you have setup your environment in ~/.bashrc as is suggested for development,
you can add something like this to your ~/.bashrc:

\code
function digikam_start
{
LD_LIBRARY_PATH=${KDE_BUILD}/extragear/graphics/lib:${LD_LIBRARY_PATH} ${KDE_BUILD}/extragear/graphics/digikam/digikam/digikam
}

function digikam_start_gdb
{
LD_LIBRARY_PATH=${KDE_BUILD}/extragear/graphics/lib:${LD_LIBRARY_PATH} gdb ${KDE_BUILD}/extragear/graphics/digikam/digikam/digikam
}
\endcode

This allows you to run digikam after compiling without the need of a "make install", even
if you changed code in the libraries.

\subsection gitbranches Working With Branches From Git Repository

Example to create a local 'dplugins' development branch based on master:

\code
git checkout master
git checkout -b development/dplugins
\endcode

Example to delete the local 'dplugins' development branch:

\code
git checkout master
git branch -d development/dplugins
\endcode

Example to create a remote 'dplugins' development branch from the local branch:

\code
git push -u origin development/dplugins
\endcode

Example to delete the remote 'dplugins' development branch:

\code
git push origin :development/dplugins
\endcode

\subsection syncgitbranches Sync a Branch With Master From Git Repository

It typical to use a dedicated development branch in Git to keep the
master code stable for production. To synchronize branches with master, use these commands in your
local branch checkout:

\code
$>git checkout master
$>git pull --rebase
$>git checkout -b MY_DEVEL_BRANCH GIT_REMOTE_PATH
  Branch 'MY_DEVEL_BRANCH' set up to track remote branch path 'GIT_REMOTE_PATH' from origin.
  To list GIT_REMOTE_PATH, use 'git branch -a' command
  Switched to a new branch 'MY_DEVEL_BRANCH'
$>git merge master
  Merge made by the 'recursive' strategy.
  ...
$>git push
  ...
\endcode

The first 2 lines make sure that your local master repository is up to date. The 3rd line creates the local development branch "MY_DEVEL_BRANCH". If you have already created this branch, just run "git checkout MY_DEVEL_BRANCH". 
Merging between master and "MY_DEVEL_BRANCH" branch is done in the 4th line. Git might ask you to resolve conflicts here.
When it's done, it will ask you to provide a commit message. Finally you push your merge into the remote repository.

*/
