RESUME
------
Scripts to build binary digiKam package for MacOS

These scripts build a binary digiKam package for MacOS using HomeBrew
environment and Packages application.

** NOTE ** The official digiKam MacOS packages are built with Macports.  The Homebrew bundle is experimental,
and may have additional issues not found with the Macports bundle. The benefit of the Homebrew bundle is it is
significantly faster to build from scratch than Macports.

These scripts follow instructions from Qt bundle deployment for MacOS as shared libraries
available at this url: https://doc.qt.io/qt-6/macos-deployment.html

Current known issues with Homebrew bundle:
* Functionality:
    * General - Unable to play multimedia files
    * DB - MariaDB works as initial DB, but unable to use migration tool to MariaDB
* UI:
    * Unable to use Breeze icon set
    * digiKam icon changes to plain icon after loading


AUTHORS
-------

(c)      2015 by Shanti <listaccount at revenant dot org>
(c) 2015-2024 by Gilles Caulier <caulier dot gilles at gmail dot com>
(c) 2024 by Michael Miller <michael underscore miller at msn dot com>


DESCRIPTION
-----------
These files and scripts are used to make a binary package of the digiKam
Software Collection for MacOS. In addition to this README, there are
comments in the scripts that provide some additional explanations for
how they work.


BUNDLE CONTENTS
---------------

Note: the bundle is relocatable.

Bundle is composed of two main application containers (digikam and showfoto), to start from the macOS lauchpad.
The digikam sub-container include all resources shared with showfoto.
The showfoto sub-container directories are linked to the digikam sub-container to reduce used-space.
The host directory is called "digiKam.org" and not "digiKam" to allow Showfoto icon to be show on macOS lauchpad,
else only digiKam is visible.

digiKam.org
├── digikam.app                             digiKam sub-container
│   └── Contents
│       ├── bin                             Extra binaries
│       ├── etc                             Extra configuration
│       ├── lib                             Libraries and extra dependencies
│       ├── libexec                         Run time dependencies
│       │   └── qt5
│       │       ├── lib
│       │       └── plugins                 Plugins
│       │           ├── bearer
│       │           ├── designer
│       │           ├── digikam             digiKam and Showfoto DPlugins
│       │           │   ├── bqm
│       │           │   ├── dimg
│       │           │   ├── editor
│       │           │   ├── generic
│       │           │   └── rawimport
│       │           ├── generic
│       │           ├── iconengines
│       │           ├── imageformats
│       │           ├── kauth
│       │           ├── kf5
│       │           ├── platforms
│       │           ├── platformthemes
│       │           ├── printsupport
│       │           ├── sqldrivers
│       │           └── styles
│       ├── MacOS                           digiKam binary
│       ├── Resources                       Data and resource files
│       │   ├── applications
│       │   ├── data
│       │   ├── digikam
│       │   ├── kf5
│       │   ├── knotifications5
│       │   ├── kservices5
│       │   ├── kservicetypes5
│       │   ├── kxmlgui5
│       │   ├── lensfun                     Lens auto correction profiles
│       │   ├── locale
│       │   ├── mime
│       │   ├── opencv4
│       │   ├── plugins
│       │   ├── showfoto
│       │   └── solid
│       └── share                           Shared files
└── showfoto.app                            Showfoto sub-container
    └── Contents
        ├── bin                             -> ../../digikam.app/Contents/bin
        ├── etc                             -> ../../digikam.app/Contents/etc
        ├── lib                             -> ../../digikam.app/Contents/lib
        ├── libexec                         -> ../../digikam.app/Contents/libexec
        ├── MacOS                           Showfoto binary
        ├── Resources                       -> ../../digikam.app/Contents/Resources
        └── share                           -> ../../digikam.app/Contents/share

REQUIREMENTS
------------

To build bundle you need a macOS install in a real computer (best) or in a VM.
This Github project have been tested to install automatically BigSur in VirtualBox and work as expected:

https://github.com/myspaghetti/macos-virtualbox

The scripts build digiKam with HomeBrew, so you will need Xcode and the other
prerequisites for HomeBrew.

See this url for details: https://docs.brew.sh/Xcode.

For all other HomeBrew requirements, see https://docs.brew.sh/Installation.

You will also need to install Packages software which does the actual packaging of the files needed to install digiKam:

http://s.sudre.free.fr/Software/Packages/about.html

IMPORTANT:
- You must set the minimal MacOS target with relevant SDK installed for backward compatibility.
- You must set the digiKam git tags to checkout right source code to package.
- You must set the option to host debug symbols or not in package.

NOTE: Look in config.sh file for settings details.


HERE THERE BE DRAGONS
---------------------
Use these scripts at your own risk. For example, both scripts contain
"rm -rf" (to clear previous builds) -- a mistake could wipe your drive.


COMPONENTS
----------
There are 4 main scripts to be run by the user. 2 first ones installs
HomeBrew and all dependencies, next one digiKam, and last one makes a
PKG binary installer for MacOS using Packages.


SCRIPT DESCRIPTIONS
-------------------
All scripts should be run from within the digikam-package directory.

* 01-build-homebrew.sh:

This script downloads and configures a custom non-root install
of HomeBrew to /opt/homebrew.

* 02-build-extralibs.sh:

This script configures, and compile a custom non-root install to /opt/homebrew
of extra libraries, including KF6 frameworks, and most important photo management
libs used by digiKam as Exiv2 and LensFun.

* 03-build-digikam.sh:

This script configures, and compile a custom non-root install of digiKam to
/opt/homebrew.

* 04-build-installer.sh:

Once you've successfully built digiKam, /opt/homebrew may contain over 10GB of files.
This script grabs the ~250MB needed to run digiKam and Showfoto,
and places them in ./installer/opt. These include applications documentations
and translations.

This script creates Applescript launch applications for the programs that will
be run by the user (digiKam, Showfoto, etc), and preinstall/postinstall
scripts in ./installer.

The launcher applications:
     1) Update desktop.org files cache system with kbuildsyscoca5.
     2) set "DYLD_IMAGE_SUFFIX=_debug" if the digikam port was built with the
        +debug variant.

This script also create the pre-install and post-install scripts that are run
when the package is installed. They delete any pre-existing /opt/homebrew,
delete and recreate /Applications/digiKam.org.

Finally, this script sets the version number, and runs Packages to
put everything together in the bundle.

Depending of configuration done in config.sh, this script is able to upload automatically
the bundle file on files.kde.org digiKam area through ssh. A valid ssh key configured
with remote KDE server need to be set previously with the account. You can load ssh key
at startup following instruction give at this url:

https://unix.stackexchange.com/questions/90853/how-can-i-run-ssh-add-automatically-without-password-prompt

Note: the bundle can be signed with GPG. You must setup your private and public keys before
and put your passphare to a text file (~/.gnupg/dkorg-gpg-pwd.txt)

* rll.py

Run by 04-build-installer.sh. It is a Python script that takes a list of binaries
and libraries supplied by 04-build-installer.sh and recursively lists the dylibs on
which they depend, and their dependencies, etc.. Adapted with minimal
modification (mostly deleting stuff) from
https://github.com/mixxxdj/mixxx/blob/master/build/osx/otool.py.

* makeall.sh

This script permit to build whole package from scratch (all stages).

* update.sh

This script re-build only digiKam and package (2 last stages).


LICENSES
--------
rll.py, like the otool.py source from which it has been adapted, is licensed
under GNU General Public License version 2.

The scripts and other contents that we have created are licensed
under the GNU General Public License version 2, or any later version.
