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 */