Warning, /graphics/digikam/Mainpage.dox is written in an unsupported language. File is not indexed.
0001 /** \mainpage digiKam API reference page.
0002 \author (c) 2001-2024 digiKam team.
0003 \brief digiKam is an advanced open-source digital photo management application that runs on Linux, Windows, and macOS.
0004 \image html logo-digikam.png
0005
0006 \section sourcedirs Source Code Directories
0007
0008 digiKam is split into a number of components, each ones located to a dedicated directory.
0009 The main namespace is Digikam for the digiKam application and all sub components. A second one is ShowFoto for the stand alone version of image editor.
0010
0011 See below the complete list of directories used by the project:
0012
0013 | SOURCE TREE-VIEW | DETAILS |
0014 | ----------------------------------------------------------- | ----------------------------------------------------------------------- |
0015 |├── AUTHORS | List of developers and contributors to the project |
0016 |├── bootstrap.linux | Configuration script to compile under Linux |
0017 |├── bootstrap.local | Configuration script to compile a local version under Linux |
0018 |├── bootstrap.macports | Configuration script to compile under macOS with Macports |
0019 |├── bootstrap.mxe | Configuration script to cross-compile for Windows under Linux with MXE |
0020 |├── bootstrap.tarball | Script to build the release tarball |
0021 |├── build | Temporary directory created by bootstrap script to host compiled files |
0022 |├── ChangeLog | Note about how to list source code changes since the project origin |
0023 |├── CMakeLists.txt | Main Cmake script including lead compilation rules for the project |
0024 |├── COPYING | Link to main project license |
0025 |├── LICENSES | All licenses used in the project |
0026 |├── Mainpage.dox | API documentation main page based on Doxygen |
0027 |├── Messages.sh | Script to extract strings for translators |
0028 |├── NEWS | Notice to resume all project changes done at release time |
0029 |├── README.DEVEL | Read me file for developers |
0030 |├── README.md | First start helper documentation |
0031 |├── README.BUNDLES | Read me for Linux, macOS, and Windows bundles support |
0032 |├── build | Directory to store compiled files and binary targets |
0033 |├── core | All source code are hosted in this directory |
0034 |│ ├── app | Lead application component |
0035 |│ │ ├── date | All date relevant views |
0036 |│ │ ├── dragdrop | Drag and drop helper classes |
0037 |│ │ ├── filters | Tags filter widgets |
0038 |│ │ ├── items | Item management classes |
0039 |│ │ │ ├── delegate | Item view delegate |
0040 |│ │ │ ├── overlays | Item overlays |
0041 |│ │ │ ├── thumbbar | Item thumbbar widget |
0042 |│ │ │ ├── utils | Item utility classes |
0043 |│ │ │ └── views | Item view classes |
0044 |│ │ ├── main | Main digiKam application |
0045 |│ │ ├── utils | Generic utility classes |
0046 |│ │ └── views | Views classes |
0047 |│ │ ├── preview | Item preview classes |
0048 |│ │ ├── sidebar | Left sidebar contents |
0049 |│ │ ├── stack | Stacked-view show in central place of main digiKam window |
0050 |│ │ ├── tableview | Table-view classes |
0051 |│ │ └── utils | View utility classes |
0052 |│ ├── cmake | Extra Cmake scripts will be hosted here |
0053 |│ │ ├── modules | Cmake scripts to find extra dependencies |
0054 |│ │ └── templates | Cmake template files used at configuration time |
0055 |│ ├── data | Application data files will be hosted here |
0056 |│ │ ├── about | Welcome page files (HTML + CSS) |
0057 |│ │ ├── colorschemes | GUI Color scheme files |
0058 |│ │ ├── database | Database XML configuration files |
0059 |│ │ ├── facesengine | Face detection and recognition data files |
0060 |│ │ ├── filters | Image filters data files |
0061 |│ │ ├── geolocation | Geolocation tool data files |
0062 |│ │ ├── hotplug | Hotplug Linux integration files |
0063 |│ │ ├── htmlgallery | HTML gallery tool data files |
0064 |│ │ ├── icons | Application icons |
0065 |│ │ ├── metadata | Metadata tool data files |
0066 |│ │ ├── pics | Application pictures |
0067 |│ │ ├── printcreator | Print Creator tool data files |
0068 |│ │ ├── profiles | Basis open source ICC color profiles |
0069 |│ │ └── scripts | Miscs maintenance scripts |
0070 |│ ├── dplugins | All digiKam plugins will be hosted in this directory |
0071 |│ │ ├── bqm | All Batch Queue Manager plugins |
0072 |│ │ │ ├── colors | All color adjustments plugins |
0073 |│ │ │ ├── convert | All file convert plugins |
0074 |│ │ │ ├── custom | All user-custom processing plugins |
0075 |│ │ │ ├── decorate | All decorate item plugins |
0076 |│ │ │ ├── enhance | All enhance item plugins |
0077 |│ │ │ ├── filters | All filter item plugins |
0078 |│ │ │ ├── metadata | All metadata edit plugins |
0079 |│ │ │ └── transform | All transform item plugins |
0080 |│ │ ├── editor | All Image Editor plugins |
0081 |│ │ │ ├── colors | All color adjustments plugins |
0082 |│ │ │ ├── decorate | All decorate item plugins |
0083 |│ │ │ ├── enhance | All enhance item plugins |
0084 |│ │ │ ├── file | All file processing plugins |
0085 |│ │ │ ├── filters | All filter item plugins |
0086 |│ │ │ └── transform | All transform item plugins |
0087 |│ │ ├── generic | All generic plugins |
0088 |│ │ │ ├── import | Tools to import items |
0089 |│ │ │ ├── metadata | Plugins to change items metadata |
0090 |│ │ │ ├── tools | Plugins hosted in Tools main menu |
0091 |│ │ │ ├── view | Plugins to display items |
0092 |│ │ │ └── webservices | All plugins to import and export items to remote web-services |
0093 |│ │ ├── rawimport | All Raw import plugins |
0094 |│ │ └── dimg | All DImg image loader plugins |
0095 |│ ├── libs | digiKam core sub-components (few are shared with Showfoto) |
0096 |│ │ ├── album | All classes use to manage digiKam albums operations and properties |
0097 |│ │ ├── database | All low level database interface is here |
0098 |│ │ │ ├── collection | All classes relevant of collections management |
0099 |│ │ │ ├── coredb | The core database interface used to host all image properties |
0100 |│ │ │ ├── dbjobs | All database multi-threaded jobs |
0101 |│ │ │ ├── engine | The low level database engine classes |
0102 |│ │ │ ├── haar | The similarity low level algorithms to compute image finger-prints |
0103 |│ │ │ ├── history | The item history classes for the database |
0104 |│ │ │ ├── item | The database item classes, including containers, lister, and scanner |
0105 |│ │ │ ├── models | The database model classes |
0106 |│ │ │ ├── server | The Mysql internal server |
0107 |│ │ │ ├── similaritydb | The similarity database |
0108 |│ │ │ ├── tags | The database tags management classes |
0109 |│ │ │ ├── thumbsdb | The thumbnails database |
0110 |│ │ │ └── utils | Miscs tools and widgets used with database |
0111 |│ │ ├── dialogs | Common dialogs |
0112 |│ │ ├── dimg | The Qt digiKam image data container support ICC and 16 bits color depth |
0113 |│ │ │ ├── filters | All image filters will be hosted here. All support 16 bits color depth |
0114 |│ │ │ │ ├── auto | Auto colors correction filters |
0115 |│ │ │ │ ├── bcg | Brightness-Contrast-Gamma filter |
0116 |│ │ │ │ ├── bw | Black and White image converter, including infrared filter |
0117 |│ │ │ │ ├── cb | Colors balance filter |
0118 |│ │ │ │ ├── curves | Colors curves filter |
0119 |│ │ │ │ ├── decorate | Decorate filters |
0120 |│ │ │ │ ├── film | Analog film emulation filters |
0121 |│ │ │ │ ├── fx | Special effect filters |
0122 |│ │ │ │ ├── greycstoration | Cimg based restoration filter |
0123 |│ │ │ │ ├── hsl | Hue-Saturation-Lightness filter |
0124 |│ │ │ │ ├── icc | Icc color profile filters |
0125 |│ │ │ │ ├── imgqsort | The image quality sort algorithms |
0126 |│ │ │ │ ├── lc | Local contrast filter (pseudo HDR) |
0127 |│ │ │ │ ├── lens | Lens corrections filters, including Qt Lensfun interface |
0128 |│ │ │ │ ├── levels | Color levels filter |
0129 |│ │ │ │ ├── nr | Wavelets noise reduction filter |
0130 |│ │ │ │ ├── redeye | Red-eyes parser and fixer |
0131 |│ │ │ │ ├── sharp | Image sharp filter, including Unsharped-mask and Refocus |
0132 |│ │ │ │ ├── transform | All image transformation filters |
0133 |│ │ │ │ └── wb | White balance filter |
0134 |│ │ │ ├── imagehistory | Image history interface for image container |
0135 |│ │ │ └── loaders | All DImg image loaders interface |
0136 |│ │ ├── metadataengine | The metadata wrapper based on Exiv2 for image and FFMpeg for video |
0137 |│ │ ├── dngwriter | Qt classes to convert RAW files to DNG format |
0138 |│ │ │ └── extra | DNG and XMP sdks from Adobe |
0139 |│ │ ├── dplugins | All shared dplugins classes are hosted here |
0140 |│ │ │ ├── core | Low level classes for plugins definitions |
0141 |│ │ │ ├── iface | Low level classes for host interface definitions |
0142 |│ │ │ ├── setup | Classes to setup plugins in configuration panel |
0143 |│ │ │ ├── webservices | Common classes for Webservices tools |
0144 |│ │ │ └── widgets | Common widget sfor plugins |
0145 |│ │ ├── dtrash | digiKam trash manager full independent of desktop trash |
0146 |│ │ ├── facesengine | Face detection and recognition engine + Faces database implementations |
0147 |│ │ │ ├── alignment-congealing | Face alignment based on congealing method |
0148 |│ │ │ ├── alignment-flandmark | Face alignment based on flandmark method |
0149 |│ │ │ ├── detection | Face detection algorithms |
0150 |│ │ │ ├── dnnface | Deep-learning face algorithms |
0151 |│ │ │ ├── facedb | Faces database classes |
0152 |│ │ │ ├── opencv3-face | OpenCV version 3 face management classes |
0153 |│ │ │ ├── preprocessing-tantriggs | Face pre-processing based on tantriggs method |
0154 |│ │ │ ├── recognition-dlib-dnn | Deep-learning faces recognition module |
0155 |│ │ │ ├── recognition-opencv-eigenfaces | Eigen faces recognition module |
0156 |│ │ │ ├── recognition-opencv-fisherfaces | Fisher faces recognition module |
0157 |│ │ │ ├── recognition-opencv-lbph | LBPH bases faces recognition module |
0158 |│ │ │ └── shape-predictor | Shape predictor algorithms |
0159 |│ │ ├── fileactionmanager | Classes to connect database and metadata actions to file operations |
0160 |│ │ ├── filters | Widgets to filter items by metadata properties |
0161 |│ │ ├── imageproperties | All widgets used in right side-bar from all main views |
0162 |│ │ ├── iojobs | Multithreaded jobs manager used with files operations |
0163 |│ │ ├── jpegutils | Utilities to process JPEG files |
0164 |│ │ │ └── libjpeg | JPEG loss-less transform private implementations from libjpeg |
0165 |│ │ ├── kmemoryinfo | Qt backend to analyze system memory information |
0166 |│ │ ├── models | Qt models used with item views |
0167 |│ │ ├── notificationmanager | Multi-desktop notifications wrapper |
0168 |│ │ ├── pgfutils | Qt Classes to work with PGF image format |
0169 |│ │ ├── progressmanager | Multi-level operations progress widget |
0170 |│ │ ├── rawengine | Qt classes to work with libraw decoder |
0171 |│ │ │ └── libraw | Internal Libraw sdk |
0172 |│ │ ├── settings | digiKam settings manager |
0173 |│ │ ├── tags | Classes to play with tags |
0174 |│ │ │ └── tagsmanager | Tags manager view |
0175 |│ │ ├── template | Metadata template support |
0176 |│ │ ├── threadimageio | Classes to process thumbs and preview extraction including video support|
0177 |│ │ ├── threads | Classes to manage and chain threads using multi-core |
0178 |│ │ ├── timeadjust | Common classes time adjustments tools |
0179 |│ │ ├── transitionmngr | Frames transitions manager |
0180 |│ │ ├── versionmanager | Classes to manage versioning operations |
0181 |│ │ ├── video | Classes to play with video contents |
0182 |│ │ └── widgets | To host plenty of widgets used everywhere |
0183 |│ │ ├── colors | Colors relevant views |
0184 |│ │ ├── combo | Combo-box helper classes |
0185 |│ │ ├── common | Uncategorized widgets |
0186 |│ │ ├── files | File operation classes |
0187 |│ │ ├── fonts | Font management classes |
0188 |│ │ ├── graphicsview | Graphics-view implementation (model-view) |
0189 |│ │ ├── iccprofiles | ICC color profiles widgets |
0190 |│ │ ├── imagehistory | Image history widgets |
0191 |│ │ ├── itemview | Item-view implementations (model-view) |
0192 |│ │ ├── layout | Layout helper classes |
0193 |│ │ ├── mainview | Common top-level view implementations |
0194 |│ │ ├── metadata | Metadata widgets |
0195 |│ │ └── range | Range helper classes |
0196 |│ ├── showfoto | Stand alone image editor |
0197 |│ │ ├── main | Main Showfoto application |
0198 |│ │ ├── setup | Showfoto Setup views |
0199 |│ │ └── thumbbar | Showfoto thumb-bar views |
0200 |│ ├── tests | Unit tests |
0201 |│ └── utilities | digiKam utilities and advanced tools (few are shared with showfoto) |
0202 |│ ├── advancedrename | Advance rename tool |
0203 |│ ├── extrasupport | Extra desktop features support as Baloo search engine |
0204 |│ ├── facemanagement | Face management classes and tools |
0205 |│ ├── firstrun | First-run assistant to configure lead digiKam settings |
0206 |│ ├── fuzzysearch | Similarity search tools |
0207 |│ ├── geolocation | All geo-location tools are located here |
0208 |│ │ ├── editor | Tool to edit items geo-location |
0209 |│ │ ├── geoiface | All shared classes used by geo-location tools |
0210 |│ │ ├── geomapwrapper | Legacy helper classes for geo-location support |
0211 |│ │ └── mapsearches | Tool to perform map searches |
0212 |│ ├── imageeditor | The famous digiKam image editor, a lots of classes shared with Showfoto |
0213 |│ │ ├── core | Core implementation including canvas and tools interface |
0214 |│ │ ├── dialogs | Image editor dialogs |
0215 |│ │ ├── editor | The core image editors classes |
0216 |│ │ ├── main | The main digiKam image editor view, not shared with Showfoto |
0217 |│ │ └── widgets | All common widgets |
0218 |│ ├── import | The import tools, including USB MAss Storage, Gphoto2, and Sane support |
0219 |│ │ ├── backend | Camera backends |
0220 |│ │ ├── dialogs | Import tools dialogs |
0221 |│ │ ├── items | Import item classes |
0222 |│ │ ├── main | Import tool main view |
0223 |│ │ ├── models | Import model classes |
0224 |│ │ ├── views | Import view classes |
0225 |│ │ └── widgets | Import common widgets |
0226 |│ ├── lighttable | The Light-table tool to compare images side by side |
0227 |│ ├── maintenance | The digiKam tool to maintain the database contents |
0228 |│ ├── queuemanager | The famous Batch Queue Manager tool |
0229 |│ │ ├── main | The main BQM view |
0230 |│ │ ├── manager | The multi-core manager to run tools in background |
0231 |│ │ ├── tools | All BQM tools classed by functions |
0232 |│ │ └── views | The BQM internal views |
0233 |│ ├── searchwindow | The powerful advanced search tool |
0234 |│ ├── setup | All digiKam setup panel, with few ones shared with Showfoto |
0235 |│ │ ├── album | Album configuration views |
0236 |│ │ ├── camera | Camera configuration views |
0237 |│ │ ├── collections | Collection configuration views |
0238 |│ │ ├── editor | Image Editor configuration views |
0239 |│ │ └── metadata | Metadata configuration views |
0240 |│ └── slideshow | The simple slideshow tool |
0241 |├── po | Program translations |
0242 |└── project | Extra project parts |
0243 | ├── bundles | Bundles build scripts |
0244 | │ ├── 3rdparty | External components required to build bundles |
0245 | │ ├── CD | Continuous deployment configurations |
0246 | │ ├── appimage | Linux AppImage |
0247 | │ ├── flatpak | Linux Flatpak |
0248 | │ ├── macports | macOS package |
0249 | │ └── mxe | Windows installer |
0250 | ├── documents | Project documentations |
0251 | ├── reports | Static analyzers report scripts for Continuous Integration |
0252 | └── scripts | 3rdparty source code management scripts |
0253
0254 \section externaldeps External Dependencies
0255
0256 \subsection depscheckout Dependencies To Checkout All Source Code
0257
0258 - Perl http://www.perl.org
0259 - Git http://git-scm.com
0260
0261 \subsection depstrans Dependencies To Process Translations Files (optional)
0262
0263 - Gettext https://www.gnu.org/software/gettext (including Msgfmt to compile po files to mo files)
0264
0265
0266 \subsection depscomplink Dependencies To Compile And Link Source Code
0267
0268 The full list of mandatory (X) and (optional) external dependencies required to compile and link digiKam source code is listed below.
0269
0270 | Dependency | Requirement | Version (Qt5) | Version (Qt6) | Project URL | Remarks | Notes |
0271 |----------------------|-------------|---------------|---------------|-------------------------------------------------------|--------------------------------------------------------|---------------------------------------------------------------------------------------|
0272 | CMake | X | >= 3.16.0 | >= 3.22.0 | https://www.cmake.org | | |
0273 | ECM | X | >= 5.55.0 | >= 5.240.0 | https://invent.kde.org/frameworks/extra-cmake-modules | Qt6 support implemented in KDE framework >= 5.91.0 | |
0274 | Qt::Core | X | >= 5.14 | >= 6.5 | https://code.qt.io/cgit/qt/qtbase.git/ | | |
0275 | Qt::Gui | X | >= 5.14 | >= 6.5 | https://code.qt.io/cgit/qt/qtbase.git/ | | |
0276 | Qt::Widgets | X | >= 5.14 | >= 6.5 | https://code.qt.io/cgit/qt/qtbase.git/ | | |
0277 | Qt::Network | X | >= 5.14 | >= 6.5 | https://code.qt.io/cgit/qt/qtbase.git/ | | |
0278 | Qt::NetworkAuth | X | >= 5.14 | >= 6.5 | https://code.qt.io/cgit/qt/qtbase.git/ | | |
0279 | Qt::Sql | X | >= 5.14 | >= 6.5 | https://code.qt.io/cgit/qt/qtbase.git/ | Including Qt::Sqlite and Qt::Mysql plugins | |
0280 | Qt::Xml | X | >= 5.14 | >= 6.5 | https://code.qt.io/cgit/qt/qtbase.git/ | | |
0281 | Qt::Concurrent | X | >= 5.14 | >= 6.5 | https://code.qt.io/cgit/qt/qtbase.git/ | | |
0282 | Qt::PrintSupport | X | >= 5.14 | >= 6.5 | https://code.qt.io/cgit/qt/qtbase.git/ | | |
0283 | Qt::Svg | X | >= 5.14 | >= 6.5 | https://code.qt.io/cgit/qt/qtsvg.git/ | | |
0284 | Qt::WebEngine | X | >= 5.14 | >= 6.5 | https://code.qt.io/cgit/qt/qtwebengine.git/ | To render web contents (ENABLE_QWEBENGINE=on) | To replace Qt5::WebKitWidgets everywhere, excepted for MXE |
0285 | Qt::WebKitWidgets | optional | >= 5.212 | --- | https://code.qt.io/cgit/qt/qtwebkit.git/ | To render web contents | Used with MXE only as WebEngine do not compile with MinGW. Not yet ported to Qt6. |
0286 | Qt::XmlPatterns | optional | >= 5.14 | --- | https://code.qt.io/cgit/qt/qtxmlpatterns.git/ | To parse and validate Xml | Used by Rajce plugin. Module removed with Qt6. |
0287 | Qt::X11Extras | optional | >= 5.14 | --- | https://code.qt.io/cgit/qt/qtx11extras.git/ | For color management support under Linux | Module removed with Qt6. |
0288 | Qt::DBus | optional | >= 5.14 | >= 6.5 | https://code.qt.io/cgit/qt/qtbase.git/ | Optional: only for Linux Desktop | |
0289 | Qt::OpenGL | optional | >= 5.14 | >= 6.5 | https://code.qt.io/cgit/qt/qtbase.git/ | For Presentation tool | |
0290 | Qt::OpenGLWidgets | optional | --- | >= 6.5 | https://code.qt.io/cgit/qt/qtbase.git/ | For Presentation tool | With Qt6, OpenGL is separated in 2 modules: core and widgets. |
0291 | Qt::Multimedia | optional | --- | >= 6.5 | https://code.qt.io/cgit/qt/qtbase.git/ | For Presentation tool | With Qt6, OpenGL is separated in 2 modules: core and widgets. |
0292 | Qt::Test | optional | >= 5.14 | >= 6.5 | https://code.qt.io/cgit/qt/qtbase.git/ | To compile test codes (BUILD_TESTING=on) | |
0293 | Qt::Qml | optional | >= 5.14 | >= 6.5 | https://code.qt.io/cgit/qt/qtdeclarative.git/ | To compile test codes (BUILD_TESTING=on) O2 unit tests | |
0294 | Qt::WebView | optional | >= 5.14 | >= 6.5 | https://code.qt.io/cgit/qt/qtwebview.git/ | To compile test codes (BUILD_TESTING=on) O2 unit tests | |
0295 | KF::Config | X | >= 5.95.0 | >= 5.240.0 | https://invent.kde.org/frameworks/kconfig | | |
0296 | KF::XmlGui | X | >= 5.95.0 | >= 5.240.0 | https://invent.kde.org/frameworks/kxmlgui | | |
0297 | KF::I18n | X | >= 5.95.0 | >= 5.240.0 | https://invent.kde.org/frameworks/ki18n | | |
0298 | KF::WindowSystem | X | >= 5.95.0 | >= 5.240.0 | https://invent.kde.org/frameworks/kwindowsystem | | |
0299 | KF::Service | X | >= 5.95.0 | >= 5.240.0 | https://invent.kde.org/frameworks/kservice | TODO: make optional for Linux desktop (DFileOperations)| |
0300 | KF::Solid | X | >= 5.95.0 | >= 5.240.0 | https://invent.kde.org/frameworks/solid | | |
0301 | KF::CoreAddons | X | >= 5.95.0 | >= 5.240.0 | https://invent.kde.org/frameworks/kcoreaddons | Needs for KAboutData and KMemoryInfo | |
0302 | KF::NotifyConfig | optional | >= 5.95.0 | >= 5.240.0 | https://invent.kde.org/frameworks/knotifyconfig | For Linux desktop application notify configuration | |
0303 | KF::Notifications | optional | >= 5.95.0 | >= 5.240.0 | https://invent.kde.org/frameworks/knotifications | For Linux desktop notifications integrations | |
0304 | KF::ThreadWeaver | optional | >= 5.95.0 | >= 5.240.0 | https://invent.kde.org/frameworks/threadweaver | For panorama tool | |
0305 | KF::IconThemes | optional | >= 5.95.0 | >= 5.240.0 | https://invent.kde.org/frameworks/kiconthemes | Optional: only for Linux Desktop (KIconDialog) | |
0306 | KF::FileMetaData | optional | >= 5.95.0 | >= 5.240.0 | https://invent.kde.org/frameworks/kfilemetadata | Plasma desktop files indexer support | (ENABLE_KFILEMETADATASUPPORT=ON) Disabled by default. |
0307 | KF::CalendarCore | optional | >= 5.95.0 | >= 5.240.0 | https://invent.kde.org/frameworks/kcalendarcore | For calendar tool to setup ical special events | |
0308 | KF::KIO | optional | >= 5.95.0 | >= 5.240.0 | https://invent.kde.org/frameworks/kio | Optional: only for Linux Desktop | |
0309 | KF::Sonnet | optional | >= 5.95.0 | >= 5.240.0 | https://invent.kde.org/frameworks/sonnet | To perform spell-cheking in text widget (aka caption) | |
0310 | KF::AkonadiContact | optional | >= 5.95.0 | >= 5.240.0 | https://invent.kde.org/pim/akonadi-contacts | Plasma desktop addess-book support | (ENABLE_AKONADICONTACTSUPPORT=ON) Disabled by default. |
0311 | libopencv | X | >= 3.3 | | https://github.com/opencv/opencv | OpenCV 4 recommended | DNN module required for face management |
0312 | libtiff | X | >= 4.0 | | https://gitlab.com/libtiff/libtiff | For DImg TIFF image loader | |
0313 | libpng | X | >= 1.6 | | https://libpng.sourceforge.io/ | For DImg PNG image loader | |
0314 | libjpeg | X | >= 6b | | https://github.com/libjpeg-turbo/libjpeg-turbo | jpeglib >= 8.0 hightly recommended for RawEngine | |
0315 | libboost | X | >= 1.55.0 | | https://github.com/boostorg/boost | For Versioning support | |
0316 | liblcms | X | >= 2.x | | https://github.com/mm2/Little-CMS | For Color Management support | |
0317 | libexpat | X | >= 2.1.0 | | https://libexpat.github.io/ | For RAW to DNG converter | |
0318 | libexiv2 | X | >= 0.27.0 | | https://github.com/Exiv2/exiv2 | Metadata low level management. | |
0319 | libheif | optional | >= 1.6.0 | | https://github.com/strukturag/libheif | For HEIF file format support. | Library must be compiled with libde265 (read) and optionally with libx265 (write). |
0320 | libx265 | optional | >= 2.2 | | https://github.com/videolan/x265.git | For HEIC encoding support | |
0321 | libxml2 | optional | >= 2.7.0 | | https://gitlab.gnome.org/GNOME/libxml2/ | For HtmlGallery tool | |
0322 | libxslt | optional | >= 1.1.0 | | https://gitlab.gnome.org/GNOME/libxslt | For HtmlGallery tool | |
0323 | Flex | optional | >= 2.5.0 | | https://github.com/westes/flex | For Panorama tool | |
0324 | Bison | optional | >= 2.5.0 | | https://www.gnu.org/software/bison/bison.html | For Panorama tool | |
0325 | libmesa | optional | >= 11.0 | | https://gitlab.freedesktop.org/mesa/mesa/ | For Presentation tools (Linux only) | |
0326 | libksane | optional | >= 21.12.0 | 22.04.2 | https://invent.kde.org/graphics/libksane | Digital scanner support | |
0327 | libjpasper | optional | >= 1.900.1 | | https://github.com/jasper-software/jasper | For JPEG-2000 support | |
0328 | libeigen3 | optional | >= 3.2 | | https://github.com/eigenteam/eigen-git-mirror | For Refocus tool | See if Clapack from OpenCV can be used instead |
0329 | liblensfun | optional | >= 0.2.8 | | https://github.com/lensfun/lensfun | For LensCorrection tool | |
0330 | libglib2 | optional | >= 2.0.0 | | https://developer.gnome.org/glib/ | For Liquid rescale tool | |
0331 | libgphoto2 | optional | >= 2.5 | | https://github.com/gphoto/libgphoto2 | Digital camera drivers support. Need libusb-1 | |
0332 | libgomp | optional | >= 5.0 | | https://gcc.gnu.org/onlinedocs/libgomp | OpenMP support for RawEngine | |
0333 | libimagemagick | optional | >= 6.7.0 | | https://github.com/ImageMagick/ImageMagick.git | ImageMagick codecs support for DImg image loader | Version >= 7.0 recommended |
0334 | DrMingw | optional | >= 0.8.2 | | https://github.com/jrfonseca/drmingw | Mingw crash handler (run-time deps only for windows) | |
0335 | libffmpeg | optional | >= 4.4.x | | https://git.ffmpeg.org/ffmpeg.git | To play video and audio (ENABLE_MEDIAPLAYER=on) | libavformat, libavutil, libavcodec used to extract video metadata. QtAVPlayer |
0336 | libvaapi | optional | >= 2.4 | | https://github.com/01org/intel-vaapi-driver | To play video and audio (ENABLE_MEDIAPLAYER=on) | Intel Video support in QtAVPlayer |
0337
0338 \section getsourcecode Get Source Code
0339
0340 \subsection softcomponents Software Components
0341
0342 digiKam project use a single git repository from GitLab to host whole source code base. The project page is given below:
0343
0344 https://invent.kde.org/graphics/digikam
0345
0346 The digikam handbook source code is hosted in a separate GitLab repository:
0347
0348 https://invent.kde.org/documentation/digikam-doc
0349
0350 \section develenv Development Environment
0351
0352 If you are a developer with push access to the git repositories, it is strongly recommended
0353 to use the "kde:" prefix and let git use the read-only mirrors for pulling.
0354
0355 If you did not clone this repository from "kde:", do it again:
0356
0357 \code
0358 git config --global url.git://anongit.kde.org/.insteadof kde:
0359 git config --global url.ssh://git@git.kde.org/.pushinsteadof kde:
0360 git clone kde:digikam
0361 \endcode
0362
0363 See below an example of \b .gitconfig file working with a developer account :
0364
0365 \code
0366 [url "git://anongit.kde.org/"]
0367 insteadof = kde://
0368
0369 [url "git@git.kde.org:"]
0370 pushinsteadof = kde://
0371
0372 [url "ssh://git@git.kde.org/"]
0373 pushinsteadof = kde://
0374
0375 [alias]
0376 up = pull --rebase -v --stat
0377 ci = commit -a -v
0378 [core]
0379 editor = mcedit
0380
0381 [user]
0382 name = my name
0383 email = my email
0384
0385 [push]
0386 default = tracking
0387
0388 [color]
0389 # turn on color
0390 diff = auto
0391 status = auto
0392 branch = auto
0393 interactive = auto
0394 ui = auto
0395
0396 [color "branch"]
0397 current = green bold
0398 local = green
0399 remote = red bold
0400
0401 [color "diff"]
0402 meta = yellow bold
0403 frag = magenta bold
0404 old = red bold
0405 new = green bold
0406
0407 [color "status"]
0408 added = green bold
0409 changed = yellow bold
0410 untracked = red
0411
0412 [color "sh"]
0413 branch = yellow
0414 [color "sh"]
0415 \endcode
0416
0417 \section cmakeoptions Cmake Configuration Options
0418
0419 To configure the project with CMake, use dedicated "bootstrap" script for your platform where all available configuration
0420 options are present with default values.
0421
0422 There are two configuration sections : the top level and the core.
0423
0424 \subsection topleveloptions Top Level Configuration
0425
0426 - Packaging options:
0427
0428 - \b DIGIKAMSC_COMPILE_DIGIKAM : Build digiKam core (default=ON).
0429 - \b DIGIKAMSC_COMPILE_PO : Build application translations files. (default=OFF).
0430
0431 - Developers only options:
0432
0433 - \b BUILD_TESTING=ON : Build tests code (default=ON).
0434 - \b BUILD_WITH_QT6=ON : Build with Qt6 framework, else Qt5 (default=OFF).
0435
0436 \subsection coreoptions Core Configuration
0437
0438 - Extra feature support options:
0439
0440 - \b ENABLE_KFILEMETADATASUPPORT : Build digiKam with KDE files indexer support (default=OFF).
0441 - \b ENABLE_AKONADICONTACTSUPPORT : Build digiKam with KDE Mail Contacts support (default=OFF).
0442 - \b ENABLE_GEOLOCATION : Build digiKam with Geolocation support (default=ON).
0443 - \b ENABLE_MEDIAPLAYER : Build digiKam with Media Player support (default=ON).
0444 - \b ENABLE_DBUS : Build digiKam with DBUS support (default=ON).
0445 - \b ENABLE_APPSTYLES : Build digiKam with support for changing the widget application style (default=OFF).
0446 - \b ENABLE_QWEBENGINE : Build digiKam with QWebEngine instead of QWebKit (default=ON).
0447
0448 - Experimental support options
0449
0450 - \b ENABLE_MYSQLSUPPORT : Build digiKam with MySQL dabatase support (default=ON).
0451 - \b ENABLE_INTERNALMYSQL : Build digiKam with internal MySQL server executable (default=ON).
0452
0453 - Showfoto application options
0454
0455 - \b ENABLE_SHOWFOTO : Build Showfoto stand-alone image editor application (default=ON).
0456
0457 - Developers only options:
0458
0459 - \b ENABLE_DIGIKAM_MODELTEST : Enable ModelTest on some models for debugging (default=OFF).
0460 - \b ENABLE_SANITIZERS : Enable ASAN and UBSAN sanitizers when available (default=OFF).
0461 - \b BUILD_WITH_CCACHE : Use ccache to speed up compilations (default=OFF)
0462
0463 - Packaging options
0464
0465 - \b ENABLE_DRMINGW : Enable the Dr. Mingw crash handler for windows (default=ON).
0466 - \b ENABLE_MINGW_HARDENING_LINKER : Enable DEP (NX), ASLR, and high-entropy ASLR linker flags for MinGW (default ON).
0467
0468 \section setuplocaldev Setup Local Compilation and Run-Time
0469
0470 This section describes how to install digiKam from the git repository, while keeping a system-wide digiKam install.
0471
0472 This procedure is based on the configure script \b bootstrap.local
0473
0474 1. Set the root directory for your git install in bootstrap.local (DIGIKAM_INSTALL_PREFIX variable)
0475 2. If you want a clean build directory, set CLEANROOT to 1
0476 3. Type the following command in your terminal:
0477
0478 \code
0479 $ ./bootstrap.local # or "./bootstrap.local --eclipse" if you intend to use Eclipse
0480 $ cd build
0481 $ make
0482 $ make install
0483 $ KDESYCOCA="/your/root/directory/var/tmp/kde-$USER/ksycoca5" kbuildsycoca5
0484 \endcode
0485
0486 To run digikam, use the following commands:
0487
0488 \code
0489 $ export KDESYCOCA=/your/root/directory/var/tmp/kde-$USER/ksycoca5
0490 $ export QT_PLUGIN_PATH=/your/root/directory/lib64/plugins:/your/root/directory/lib/plugins:$QT_PLUGIN_PATH
0491 $ export XDG_DATA_DIRS=/your/root/directory/share:$XDG_DATA_DIRS
0492 $ /your/root/directory/bin/digikam
0493 \endcode
0494
0495 The same applies for all binaries in /your/root/directory/bin/
0496
0497 If your shell is bash, you can edit your \b .bashrc file (in $HOME) and add the following alias:
0498
0499 \code
0500 DIGIKAMROOT="/your/root/directory"
0501 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"
0502 \endcode
0503
0504 then you can start your newly installed digikam with
0505
0506 \code
0507 $ digikam-dev
0508 \endcode
0509
0510 \section debugtraces Debug Traces At Run-Time
0511
0512 digiKam uses categorized logging at run-time. By default, all debug messages are printed on the console. To disable output, you can either
0513 fine-grained control by using one or more logging categories listed below.
0514
0515 Note: under Windows, to catch all debug messages you need to install an extra Microsoft application named DebugView available at this url:
0516 http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx
0517
0518 \subsection Enable Logging Using an Environment Variable
0519
0520 You can set the environment variable \b QT_LOGGING_RULES. Rules are divided by semicolons.
0521
0522 E.g. you can start digiKam like this on the command line with thumbnails and core database messages disabled:
0523
0524 \code
0525 export QT_LOGGING_RULES='digikam.thumbsdb=false:digikam.coredb=false'
0526 digikam
0527 \endcode
0528
0529 \subsection digiKamloggincat Logging Categories in digiKam
0530
0531 All logging categories are listed in \ref digikam_debug.cpp source code.
0532
0533 \subsection moreaboutloggincat Further Reading
0534
0535 For more details see the Qt framework documentation about logging categories available at this url:
0536 https://doc.qt.io/qt-5/qloggingcategory.html#details
0537
0538 \section cmakecompilrules Cmake compilation rules
0539
0540 \subsection cmakeintro Introduction
0541
0542 The whole project is written mostly in C++/Qt and the Cmake framework is used to compile under Linux, macOS, and Windows.
0543 The Cmake rules have been configured to reduce the linking overhead and improve CPU utilization with modular design.
0544
0545 Independent Cmake configuration is presents in following folders:
0546
0547 - root source dir
0548 - core
0549 - doc
0550
0551 The Cmake rules will build the following targets:
0552
0553 - digikamcore shared lib
0554 - digikamdatabase shared lib
0555 - digikamgui shared lib
0556 - digikam executable
0557 - showfoto executable
0558 - plugin shared libraries (dplugins)
0559 - various test executables - if testing is enabled
0560 - various unit-tests - if testing is enabled
0561
0562 Each of them depend on various sources which must be compiled before.
0563 A complete description of source code direction is given to the sourcedirs section.
0564
0565 \subsection cmakeimpldetails CMake Implementation Details
0566
0567 \subsubsection includedirs Include Directories
0568
0569 Local include directories are all managed by this snippet of code:
0570
0571 \code
0572 set(DK_INCLUDES_ALL "")
0573 HEADER_DIRECTORIES(DK_LOCAL_INCLUDES_RAW)
0574 \endcode
0575
0576 The libjpeg- folders are all included, so we need to delete them all and include the correct one only:
0577
0578 \code
0579 # This macro will set all paths which do not contain libjpeg-
0580 # We will add later the directory we need
0581
0582 FOREACH(var ${DK_LOCAL_INCLUDES_RAW})
0583 STRING(REGEX MATCH "libjpeg-" item ${var})
0584 IF(item STREQUAL "")
0585 LIST(APPEND DK_LOCAL_INCLUDES ${var})
0586 ENDIF(item)
0587 ENDFOREACH(var)
0588
0589 set(DK_LOCAL_INCLUDES ${DK_LOCAL_INCLUDES}
0590 libs/jpegutils/${DIGIKAM_LIBJPEG_DIR})
0591
0592 include_directories(${DK_LOCAL_INCLUDES})
0593 \endcode
0594
0595 There is no need for manual intervention to add new includes, even if you add a new folder, just keep in mind to use:
0596
0597 \code
0598 #include "tagmngrlistitem.h"
0599 \endcode
0600
0601 instead of :
0602
0603 \code
0604 #include "models/tagmngrlistitem.h"
0605 \endcode
0606
0607 \subsubsection sharedlibs Shared Libraries
0608
0609 To avoid linking overhead and make a better use of sources there are some dynamic libs as these one:
0610
0611 - digikamcore : core components used by almost all executables as digiKam and Showfoto.
0612 - digikamdatabase : database components, also used together with digikamcore but only for digiKam
0613
0614 Please add sources to digikam core or digikam database only if they don't depend on any big component
0615 from digikam main executable. These two shared libs must be kept small because they link in a lot of places
0616
0617 \subsubsection staticlibs Static Libraries
0618
0619 Currently cmake configuration features a lots of shared libraries as:
0620
0621 - metadataedit
0622 - geolocationedit
0623 - digikamfaceengine
0624
0625 This libraries are linked in digikam main executable and some tests tools.
0626
0627 Avoid making static libraries if possible, and use OBJECT libraries instead.
0628 Only make STATIC libraries which does not depend on other digikam code.
0629 Also make sure you put the PRIVATE parameter when setting the target_link_libraries.
0630
0631 \code
0632 target_link_libraries(digikamcore
0633 PRIVATE
0634 Qt{QT_VERSION_MAJOR}::Core
0635 Qt{QT_VERSION_MAJOR}::Gui
0636 Qt{QT_VERSION_MAJOR}::Widgets
0637 )
0638 \endcode
0639
0640
0641 \subsubsection objlibs Object Libraries
0642
0643 While static libraries are still collection of objects, CMake offer a better approach by
0644 allowing to specify an OBJECT library:
0645
0646 \code
0647 set(libslideshow_SRCS
0648 slidetoolbar.cpp
0649 slideosd.cpp
0650 slideproperties.cpp
0651 slideimage.cpp
0652 slideerror.cpp
0653 slideend.cpp
0654 slideshow.cpp
0655 slidehelp.cpp
0656 slideshowsettings.cpp
0657 )
0658
0659 add_library(slideshow_src OBJECT ${libslideshow_SRCS})
0660 \endcode
0661
0662 OBJECT library is a cmake internal implementation feature and allow to easily manage sources.
0663 Here is an example of how to make a shared lib using OBJECT libraries:
0664
0665 \code
0666 add_library(digikamcore
0667 SHARED
0668 $<TARGET_OBJECTS:slideshow_src> # the lib we made few lines above
0669 $<TARGET_OBJECTS:digikamdatabasecore_src>
0670 $<TARGET_OBJECTS:dimg_src>
0671 ....
0672 )
0673 \endcode
0674
0675 \section codecontrib Contribute To The Code
0676
0677 This section's purpose is to guide contributors and developers to help on the
0678 digiKam project.
0679
0680 \subsection startopensource Starting With Open-Source
0681
0682 Before to contribute to digiKam project, please take a look to this link
0683 which provide 10 golden rules for starting with open source project:
0684
0685 http://schlitt.info/opensource/blog/0541_10_golden_rules_for_starting_with_open_source.html
0686
0687 \subsection codeformat Source Code Formatting
0688
0689 Adhere to this style guide strictly while adding new code to digiKam or
0690 working on existing code.
0691
0692 \subsubsection indentlength Indentation length
0693
0694 Indent with 4 spaces exactly.
0695
0696 For example:
0697
0698 \code
0699 void function()
0700 {
0701 ....int a; // 4 spaces from beginning
0702 ....for (int i = 0 ; i < 10 ; ++i) // 4 spaces from beginning
0703 ....{ // 4 spaces from beginning
0704 ........a = i; // 4 spaces from previous indent block
0705 \endcode
0706
0707 Emacs by default will indent to 4 spaces
0708 vim users add this to you .vimrc
0709 set tabstop=4
0710
0711 \subsubsection tabsspaces Tabs vs Spaces
0712
0713 Absolutely no tabs. Use a sensible editor which will convert tabs to spaces.
0714 This will reduce unnecessary changes in your git commits.
0715
0716 Emacs by default will convert tab to spaces.
0717 For vim users, add this to your .vimrc
0718 set expandtab
0719
0720 \subsubsection linelength Line length
0721
0722 Line length should never exceed 80 chars (unless really necessary - these
0723 cases are rare). Having long lines greatly reduces readability of code
0724
0725 \subsubsection bracketing Bracketing
0726
0727 In all cases, {} brackets should start on a newline and should be
0728 aligned with previous line (follow the indentation spaces). For example.
0729
0730 \code
0731 class A
0732 { //new line
0733 ...
0734
0735 for (int i = 0 ; i < 10 ; ++i)
0736 { //new line
0737
0738 if (a == foobar)
0739 { //new line
0740 ...
0741 }
0742 else
0743 { // new line
0744 ..
0745 }
0746 \endcode
0747
0748 \subsubsection accessmod Positioning of Access modifiers
0749
0750 public, private, protected, public slots, ... should be aligned to the
0751 beginning of the line with no margin
0752
0753 \code
0754 class A
0755 {
0756 public: // aligned to left
0757 ...
0758 private Q_SLOTS: // aligned to left
0759 \endcode
0760
0761 Follow a consistent order in defining these attributes. The recommended
0762 order is public, protected (functions), private (functions),
0763 signals, public slots, protected slots, private slots, private (variables)
0764
0765 \subsection itemsnames Class, file and Variable names
0766
0767 \subsubsection classfilenames Class and filenames
0768
0769 - filenames should always be in lower-case
0770 - class names should match the filenames. Capitalize the first letter and
0771 other letters logically to improve readability
0772
0773 \subsubsection protectvars Protected Member variables
0774
0775 - protected member variable names should always be of the form m_varName.
0776 - Capitalize logically so that it becomes easy to read it. Do not capitalize
0777 the first letter after _ (Use m_varName not m_VarName)
0778 - variable names should be indicative of their functionality and also of
0779 the type they belong too if they are instances of qt widgets.
0780 For example, QCheckBox* m_autoRotateCheckBox;
0781
0782 \subsubsection nomembvars Non-Member variables
0783
0784 - non-member variables should follow the same naming convention as the member
0785 variables, except for the leading m_
0786
0787 \subsubsection privmembvars Private Member variables
0788
0789 - private member variables must be stored in a d private container to reduce
0790 compilation time and improve binary compatibility between digiKam components.
0791 See more information how to use a 'd' private class at this url:
0792
0793 https://community.kde.org/Policies/Library_Code_Policy
0794
0795 \subsection commentsspaces Comments and Whitespace
0796
0797 Use whitespaces liberally to improve readability. Add blank lines between logical
0798 sections of the code.
0799
0800 Comment as much as possible. Position comments at the beginning of the
0801 section/line you want to comment, NEVER at the end of the line, excepted for special
0802 cases for ex to describe enum values.
0803
0804 \code
0805 // put your comments here
0806 a = (b == foobar) ? 1 : -1;
0807
0808 a = (b == foobar) ? 1 : -1; // you are asking for trouble by putting comments here
0809 \endcode
0810
0811 \subsection headerfiles Header Files
0812
0813 - Add copyright to top of every file. Use the same header than others digiKam
0814 source code.
0815 - Double inclusion protection defines are all upper case letters and are
0816 composed of the class name and a H suffix separated by underscore
0817
0818 \code
0819 #ifndef DIGIKAM_ANOTHER_NICE_CLASS_H
0820 #define DIGIKAM_ANOTHER_NICE_CLASS_H
0821
0822 class AnotherNiceClass
0823 {
0824 ...
0825 }
0826
0827 #endif // DIGIKAM_ANOTHER_NICE_CLASS_H
0828 \endcode
0829
0830 - Use forward declarations as much as possible.
0831
0832 \code
0833 class QFileInfo;
0834
0835 class A
0836 {
0837 ....QFileInfo* m_fileInfo;
0838 \endcode
0839
0840 \subsection autocodeformat Automatic source code formatting
0841
0842 The above coding style guidelines can be automatically applied with
0843 astyle (http://astyle.sourceforge.net/).
0844
0845 Run it in the directory where the files are located that should be formatted.
0846
0847 To apply the coding guidelines with astyle is to use the
0848 fileformatter.py script in project/scripts directory. This script will also clean up the
0849 source tree and remove backup files that had been created by astyle,
0850 if the appropriate command line argument is given.
0851
0852 To handle the command easier, create a bash function in ~/.bashrc, e.g.
0853
0854 \code
0855 dkfrmcode()
0856 {
0857 astyle --style=allman \
0858 --indent=spaces=4 \
0859 --convert-tabs \
0860 --indent-switches \
0861 --break-blocks \
0862 --break-closing-brackets \
0863 --pad-header \
0864 --align-pointer=type \
0865 --indent-col1-comments \
0866 --add-brackets \
0867 --min-conditional-indent=0 \
0868 `find $1 -type f -name '*.cpp'` `find $1 -type f -name '*.c'` `find $1 -type f -name '*.h'`
0869 }
0870 \endcode
0871
0872 You can pass a parameter to the function, in this case the first parameter is the directory, where
0873 files should be formatted.
0874
0875 Examples:
0876
0877 1. Run astyle in the current directory
0878 \code
0879 $> dkfrmcode
0880 \endcode
0881
0882 2. Run astyle in a different directory
0883 \code
0884 $> dkfrmcode /home/user/code/git/digikam/
0885 \endcode
0886
0887 \subsection generalrecommend General recommendations
0888
0889 Please take a look into this contrib page tips before to write code/patches for
0890 digiKam project : http://techbase.kde.org/Contribute
0891
0892 Use the same .cpp/.h header than the rest of digiKam project.
0893
0894 Use a decent editor which does auto-indentation/syntax-highlighting for you,
0895 as Kate or QtCreator
0896
0897 There are excellent initializer scripts in the kdesdk
0898 package for xemacs and vim which can substantially increase your productivity.
0899
0900 Just to give a taste of what i can do with emacs (and kdesdk):
0901
0902 * automatically insert copyright (and ifdefs) in new files.
0903 * insertion of class function definitions for declared class
0904 functions in header with one keystroke
0905 * switch between header and declaration files with one keystroke
0906 * go to corresponding definition/declaration with one keystroke
0907 * tab completion of variable/function names already declared.
0908
0909 \subsection gdbbacktrace GDB Backtrace
0910
0911 If you found a context to crash digiKam, you can provide a backtrace using GDB debugger.
0912 digiKam need to be compiled with all debug info else the backtrace will not suitable.
0913 There is a configure option for that:
0914
0915 \code
0916 $> cmake . -DCMAKE_BUILD_TYPE=debugfull
0917 $> make
0918 $> su
0919 $> make install/fast
0920 \endcode
0921
0922 To make a backtrace with GDB use following command:
0923
0924 \code
0925 $ gdb digikam
0926 > catch throw
0927 > run
0928 > ...
0929 > _crash here_
0930 > ...
0931 > bt
0932 > _the backtrace is here_
0933 > quit
0934 \endcode
0935
0936 Post this backtrace at the right place (Bugzilla or development mailing list) for investigation by developers.
0937
0938 For Windows users, take a look on this tutorial :
0939
0940 http://techbase.kde.org/Development/Tutorials/Debugging/Debugging_on_MS_Windows
0941
0942 \subsection memleak Memory Leak
0943
0944 To check any memory leak problem in digiKam, valgrind is your friend (http://valgrind.org)
0945 Try this command line to use with valgrind :
0946
0947 \code
0948 valgrind --tool=memcheck --leak-check=full --error-limit=no --suppressions=project/reports/digikam.supp digikam
0949 \endcode
0950
0951 NOTE: digikam.supp file is available in digikam/project sub-folder.
0952
0953 \subsection profilingcode Profiling With Cachegrind
0954
0955 Valgrind also includes a tool to find out in which parts of your code time is spent.
0956
0957 \code
0958 valgrind --tool=callgrind digikam
0959 \endcode
0960
0961 Profiling can be disabled at startup to limit the output to the code you are interested in.
0962 Start with
0963
0964 \code
0965 valgrind --tool=callgrind --instr-atstart=no digikam
0966 \endcode
0967
0968 and prepare the situation you want to profile. Then, in another console, start profiling with
0969 "callgrind_control -i on" and, after the situation has passed, request a profile dump with
0970 "callgrind_control -d".
0971 The resulting callgrind.out files need to be viewed with the kcachegrind program, e.g.:
0972
0973 \code
0974 kcachegrind callgrind.out.16693.1
0975 \endcode
0976
0977 \subsection unittests Unit Testing / Automated Testing
0978
0979 Unit Testing is great way to ensure that software units (in OOP this normally
0980 means classes) work as expected. Wikipedia gives a good introduction to
0981 Unit Testing:
0982
0983 http://en.wikipedia.org/wiki/Unit_testing
0984
0985 It is also worth to follow most of QTTest API rules with digiKam:
0986
0987 http://doc.qt.io/qt-5/qtest-tutorial.html
0988
0989 The digiKam test suite is located under tests and will be compiled if
0990 BUILD_TESTING is turned ON at cmake configuration time. After compiling the source code
0991 the tests can be executed via
0992
0993 \code
0994 make test
0995 \endcode
0996
0997 The console output while running the tests is stored in
0998 Testing/Temporary/LastTest.log in the CMake binary dir.
0999
1000 All tests are simple binaries that can be executed separately if needed.
1001
1002 \subsection corruptedsignalslot Checking For Corrupt Qt Signal Slot Connection
1003
1004 Use this alias for running digikam:
1005
1006 \code
1007 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'"
1008 \endcode
1009
1010 It will print a list of connection warnings after terminating the program.
1011 Moreover the complete console log of the last session is stored in
1012 /tmp/digikam.out.
1013
1014 \subsection dupcodes Finding Duplicated Code
1015
1016 Code duplication should be avoided as bugs have to be fixed for every piece of
1017 duplicated code. The current duplication can be analyzed eg. with Simian:
1018 http://www.redhillconsulting.com.au/products/simian/
1019
1020 In the digikam checkout directory run:
1021
1022 \code
1023 java -jar simian.jar `find . -regex '.*\.cpp\|.*\.h' | grep -v 3rdparty`
1024 \endcode
1025
1026 This prints out a list of duplicated code segments.
1027
1028 \subsection docvalidcodecheck API Documentation Validation, User Documentation Validation, Source Code Checking
1029
1030 The following site check on a daily basis for the a.m. errors:
1031 www.englishbreakfastnetwork.org/krazy/
1032
1033 It can be very useful, in particular before major releases.
1034 Don't trust it blindly! Sometimes they propose too advanced modifications that
1035 are no compatible with the prevailing include files.
1036
1037 \subsection appusability Usability Issues
1038
1039 OpenUsability project has define default menu structure and keyboard shortcuts:
1040
1041 http://wiki.openusability.org/guidelines/index.php/Appendices:Keyboard_Shortcuts
1042
1043 \subsection apidoc Generate API Documentation
1044
1045 To generate API documentation, you need to install:
1046
1047 - Doxygen program (http://www.doxygen.org)
1048 - Dot program (http://www.graphviz.org)
1049
1050 After cmake generated a Makefile you can call 'make doc'. A new subfolder named
1051 'html' will be created. Warning, this can take a while.
1052
1053 For finding documentation errors, doxygen generates a warning log file at the
1054 cmake binary dir called 'doxygen-warn.log'.
1055
1056 \subsection speedupcompil Speed Up The Code-Compile-Test Cycle
1057
1058 Assuming you have setup your environment in ~/.bashrc as is suggested for development,
1059 you can add something like this to your ~/.bashrc:
1060
1061 \code
1062 function digikam_start
1063 {
1064 LD_LIBRARY_PATH=${KDE_BUILD}/extragear/graphics/lib:${LD_LIBRARY_PATH} ${KDE_BUILD}/extragear/graphics/digikam/digikam/digikam
1065 }
1066
1067 function digikam_start_gdb
1068 {
1069 LD_LIBRARY_PATH=${KDE_BUILD}/extragear/graphics/lib:${LD_LIBRARY_PATH} gdb ${KDE_BUILD}/extragear/graphics/digikam/digikam/digikam
1070 }
1071 \endcode
1072
1073 This allows you to run digikam after compiling without the need of a "make install", even
1074 if you changed code in the libraries.
1075
1076 \subsection gitbranches Working With Branches From Git Repository
1077
1078 Example to create a local 'dplugins' development branch based on master:
1079
1080 \code
1081 git checkout master
1082 git checkout -b development/dplugins
1083 \endcode
1084
1085 Example to delete the local 'dplugins' development branch:
1086
1087 \code
1088 git checkout master
1089 git branch -d development/dplugins
1090 \endcode
1091
1092 Example to create a remote 'dplugins' development branch from the local branch:
1093
1094 \code
1095 git push -u origin development/dplugins
1096 \endcode
1097
1098 Example to delete the remote 'dplugins' development branch:
1099
1100 \code
1101 git push origin :development/dplugins
1102 \endcode
1103
1104 \subsection syncgitbranches Sync a Branch With Master From Git Repository
1105
1106 It typical to use a dedicated development branch in Git to keep the
1107 master code stable for production. To synchronize branches with master, use these commands in your
1108 local branch checkout:
1109
1110 \code
1111 $>git checkout master
1112 $>git pull --rebase
1113 $>git checkout -b MY_DEVEL_BRANCH GIT_REMOTE_PATH
1114 Branch 'MY_DEVEL_BRANCH' set up to track remote branch path 'GIT_REMOTE_PATH' from origin.
1115 To list GIT_REMOTE_PATH, use 'git branch -a' command
1116 Switched to a new branch 'MY_DEVEL_BRANCH'
1117 $>git merge master
1118 Merge made by the 'recursive' strategy.
1119 ...
1120 $>git push
1121 ...
1122 \endcode
1123
1124 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".
1125 Merging between master and "MY_DEVEL_BRANCH" branch is done in the 4th line. Git might ask you to resolve conflicts here.
1126 When it's done, it will ask you to provide a commit message. Finally you push your merge into the remote repository.
1127
1128 */