diff --git a/doc/qdoc/common.qdocconf b/doc/qdoc/common.qdocconf index 550a70e04..8812ce294 100644 --- a/doc/qdoc/common.qdocconf +++ b/doc/qdoc/common.qdocconf @@ -17,18 +17,23 @@ codesuffix = "\n" # override/add some things to the stylesheets: HTML.stylesheets += ./pm.css +# the above does not acutally add the stylesheet to the html file, so do it +# manually here. Include the default first. +HTML.headerstyles = \ + " \n" \ + " \n" # assign custom HTML footer to replace Qt's default copyright notice HTML.footer = "
" \ "

Patchmanager Documentation\n" \ - "Copyright (c) 2023 Patchmanager for SailfishOS contributors.\n" \ + "Copyright (c) 2023,2024 Patchmanager for SailfishOS contributors.\n" \ "This document may be used under the terms of the " \ "" \ "Creative Commons Attribution Share Alike 4.0 International " \ "License.

" \ "

" -navigation.homepage = https://github.com/sailfishos-patches/patchmanager/wiki +navigation.homepage = Documentation Home navigation.hometitle = Patchmanager navigation.landingpage = Patchmanager Documentation diff --git a/doc/qdoc/daemon.qdocconf b/doc/qdoc/daemon.qdocconf index 4bdf3ab9d..83e923ec7 100644 --- a/doc/qdoc/daemon.qdocconf +++ b/doc/qdoc/daemon.qdocconf @@ -4,7 +4,9 @@ versionsym = version = 2.0 url = https://github.com/sailfishos-patches/patchmanager -include (common.qdocconf) +include(common.qdocconf) +depends += qtcore qtdbus qtnetwork +depends += patchmanager qml-plugin headerdirs += ../../src/bin/patchmanager-daemon headers.fileextensions = "*.h *.hpp" diff --git a/doc/qdoc/dialog.qdocconf b/doc/qdoc/dialog.qdocconf index 7b5a38dea..bc13b9972 100644 --- a/doc/qdoc/dialog.qdocconf +++ b/doc/qdoc/dialog.qdocconf @@ -4,7 +4,10 @@ versionsym = version = 2.0 url = https://github.com/sailfishos-patches/patchmanager -include (common.qdocconf) +include(common.qdocconf) + +depends += qtdbus qtnetwork +depends += patchmanager daemon qml-plugin sourcedirs = ../../src/bin/dialog diff --git a/doc/qdoc/general.qdocconf b/doc/qdoc/general.qdocconf index 999de6bd1..ff38476bd 100644 --- a/doc/qdoc/general.qdocconf +++ b/doc/qdoc/general.qdocconf @@ -1,10 +1,18 @@ project = patchmanager description = Patchmanager -include (common.qdocconf) +include(common.qdocconf) + +depends += daemon qml-plugin settings-plugin preload dialog ## Sources -sources += ../../src/index.qdoc -# for quoting -exampledirs += ../../src/bin/patchmanager-daemon +sources += ../../src/index.qdoc \ + ../../src/patchdev.qdoc \ + ../../src/user.qdoc \ + ../../src/externalpages.qdoc +# for quoting. WARNING: Setting this wrong, e.g. to +# ../../src/bin/patchmanager-daemon will cause qdoc to create double index.html +# files at the wrong place. +# So, only give paths where the actual files reside: +exampledirs += ../../src/bin/patchmanager-daemon/dbus diff --git a/doc/qdoc/plugin.qdocconf b/doc/qdoc/plugin.qdocconf index a010ead14..144e7fd89 100644 --- a/doc/qdoc/plugin.qdocconf +++ b/doc/qdoc/plugin.qdocconf @@ -4,7 +4,9 @@ versionsym = version = 2.0 url = https://github.com/sailfishos-patches/patchmanager -include (common.qdocconf) +include(common.qdocconf) + +depends += qml-plugin sourcedirs = ../../src/plugin diff --git a/doc/qdoc/pm.css b/doc/qdoc/pm.css index b6759043d..6265706ee 100644 --- a/doc/qdoc/pm.css +++ b/doc/qdoc/pm.css @@ -1,5 +1,82 @@ -a:link { color: #8C001A; text-decoration: none; text-align: left; } +:root { + /* define our own custom color palette. Colors generated by some online + * tool using the Patchmanager icon. + + "Pflaster" means band-aid in German. + */ + --black: #000000ff; + --pm-pflaster-light: #efd1b3ff; + --pm-pflaster-medium-1: #dda267ff; + --pm-pflaster-medium-2: #dda267ff; + --pm-pflaster-darker: #ad7e52ff; + --pm-pflaster-dark: #584029ff; + --pm-red: #EF1C10ff; + --pm-green: #66BC52ff; + --pm-gray-lightest: ##f1f3f2ff; + --pm-gray-light-1: #d6dcd7ff; + --pm-gray-light-2: #b8c9c5ff; + --pm-gray-medium-1: #96a9a1ff; + --pm-gray-medium-2: #71928aff; + --pm-gray-dark: #2d3a37ff; + + color: var(--pm-pflaster-dark); + background-color: var(--pm-gray-lightest); +} +html { + color: var(--pm-pflaster-dark); + background-color: var(--pm-gray-lightest); +} + +body { + margin-left: 3vw; margin-right: 3vw; + font-family: "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji"; +} +code { + font-family: SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace; + font-weight: medium; +} a.qa-mark:target:before { content: "***"; color: #ff0000; } -a:hover { color: #8C0060; text-align: left; } -a:visited { color: #8C001A; text-align: left; } -a:visited:hover { color: #8C0060; text-align: left; } +a:link { color: var(--pm-pflaster-darker); text-decoration: none; text-align: left; } +a:active { color: var(--pm-red); text-align: left; } +a:active:hover { text-decoration: underline; } + +.content a:visited { color: var(--pm-green); text-align: left; } +.content a:visited:hover { text-decoration: underline; } +span.type a:visited { text-decoration: underline; } + +.red { color: var(--pm-red); } + +/* +a:visited { color: var(--pm-pflaster-dark); text-align: left; } +a:active { color: var(--pm-green); text-align: left; } + +*/ + +.header .breadcrumb { background-color: var(--pm-gray-light-2); } + +.generic .odd .alphaChar{ background-color: var(--pm-gray-light-2); } +.generic .even .alphaChar{ background-color: var(--pm-gray-light-1); } + +table tr.odd { background-color: var(--pm-gray-light-2); } +table tr.even { background-color: var(--pm-gray-light-1); } + +table, pre { + background-color: var(--pm-gray-light-1); + color: var(--pm-gray-dark); +} + +hr { background-color: var(--pm-gray-medium-1); + border: 1px solid var(--pm-pflaster-dark); +} +th { + background-color: var(--pm-gray-medium-2); + border-left: 1px solid var(--pm-gray-dark); +} + +/* Margins, padding etc */ +.content ul li { padding-left: 0.5em } +.content ul { padding-left: 2.0em; } +.content h2 { + margin-top: 1.5em; + margin-bottom: 0.5em; +} diff --git a/doc/qdoc/qmlplugin.qdocconf b/doc/qdoc/qmlplugin.qdocconf index caf05f9a2..20ec038d7 100644 --- a/doc/qdoc/qmlplugin.qdocconf +++ b/doc/qdoc/qmlplugin.qdocconf @@ -6,7 +6,8 @@ url = https://github.com/sailfishos-patches/patchmanager include(common.qdocconf) -depends += qtcore qtqml +depends += qtcore qtqml qtnetwork qtdbus qtgui +depends += patchmanager daemon headerdirs = ../../src/qml #headers.fileextensions = "*.h *.hpp" @@ -15,5 +16,5 @@ sourcedirs = ../../src/qml sources += qmlplugin.qdoc #sources.fileextensions = "*.cpp *.qdoc *.qml" -# get rid of warnings about undoicumented stuff in patchmanager.h +# try to get rid of warnings about undocumented stuff in patchmanager.h Cpp.ignoretokens += Q_PROPERTY diff --git a/makedocs b/makedocs index 3208debb8..2c443f16c 100755 --- a/makedocs +++ b/makedocs @@ -52,12 +52,16 @@ if [ -z "$QT_INSTALL_DOCS" ]; then QT_INSTALL_DOCS=/usr/share/doc/qt5 elif [ -f /usr/share/qt5/doc/global/macros.qdocconf ]; then QT_INSTALL_DOCS=/usr/share/qt5/doc + else + printf '## ERROR: global macro config does not exist.\n' + printf "## You probably need to install \'qt5-tools\''\n" + exit 1 fi fi printf '## Generating Docs...\n' [ -d $OUT ] && rm -r $OUT -qdoc --no-examples --outputdir $OUT --outputformat HTML --installdir $QMAKE_INSTALL_ROOT/doc doc/qdoc/master.qdocconf --single-exec $@ +qdoc --no-examples --showinternal --outputdir $OUT --outputformat HTML --installdir $QMAKE_INSTALL_ROOT/doc doc/qdoc/master.qdocconf --single-exec $@ printf '## End of Doc generation at "%s"\n' "$OUT" [ $switched_dirs = "true" ] && popd >/dev/null || cd - diff --git a/src/bin/dialog/dialog.qdoc b/src/bin/dialog/dialog.qdoc index aebc26cb6..31c5af387 100644 --- a/src/bin/dialog/dialog.qdoc +++ b/src/bin/dialog/dialog.qdoc @@ -1,6 +1,6 @@ /*! \title Patchmanager Documentation: Startup Dialog - \page index.html overview + \page index.html \indexpage Patchmanager Documentation This is a very simple Sailfish OS application that upon start checks the state of the Patchmanager Daemon to see whether it needs to launch a GUI. diff --git a/src/bin/patchmanager-daemon/daemon.qdoc b/src/bin/patchmanager-daemon/daemon.qdoc index 943de927b..09eb4c5c4 100644 --- a/src/bin/patchmanager-daemon/daemon.qdoc +++ b/src/bin/patchmanager-daemon/daemon.qdoc @@ -9,7 +9,7 @@ A D-Bus activated background service which manages patch un/installation, listing, de/actvation, and communication with the preload library. - Patchmanager is usually launched by its DBus service. + Patchmanager is usually launched by its D-Bus service. If the \c patchmanager binary is called from command line, it can also serve as a simple CLI to a running daemon. diff --git a/src/bin/patchmanager-daemon/inotifywatcher.cpp b/src/bin/patchmanager-daemon/inotifywatcher.cpp index 79a632ae2..e164e693a 100644 --- a/src/bin/patchmanager-daemon/inotifywatcher.cpp +++ b/src/bin/patchmanager-daemon/inotifywatcher.cpp @@ -73,6 +73,7 @@ INotifyWatcher::INotifyWatcher(QObject *parent) \inmodule PatchManagerDaemon \inherits QSocketNotifier \brief watches a list of files or directories for changes + \internal */ /*! \fn void INotifyWatcher::directoryChanged(const QString &path, bool removed); \fn void INotifyWatcher::fileChanged(const QString &path, bool removed); @@ -80,7 +81,7 @@ INotifyWatcher::INotifyWatcher(QObject *parent) Parameters are the \a path and whether it was \a removed. */ /*! \fn void INotifyWatcher::contentChanged(const QString &path, bool created); - This signal is emitted when directory content has changed + This signal is emitted when directory content has changed. Parameters are the \a path and whether something was \a created. */ INotifyWatcher::~INotifyWatcher() @@ -92,7 +93,7 @@ INotifyWatcher::~INotifyWatcher() ::close(inotifyFd); } -/*! Add \a paths to the list of paths to be watched. */ +/*! This function adds \a paths to the list of paths to be watched and returns the new list. */ QStringList INotifyWatcher::addPaths(const QStringList &paths) { QStringList p = paths; @@ -142,7 +143,7 @@ QStringList INotifyWatcher::addPaths(const QStringList &paths) return p; } -/*! Removes \a paths from the list of paths to be watched. */ +/*! This function removes \a paths from the list of paths to be watched and returns the new path list. */ QStringList INotifyWatcher::removePaths(const QStringList &paths) { QStringList p = paths; diff --git a/src/bin/patchmanager-daemon/journal.cpp b/src/bin/patchmanager-daemon/journal.cpp index a1f89257c..3b9ad3345 100644 --- a/src/bin/patchmanager-daemon/journal.cpp +++ b/src/bin/patchmanager-daemon/journal.cpp @@ -6,9 +6,17 @@ /*! \class Journal \inmodule PatchManagerDaemon + \brief Interface to the systemd Journal. + \internal + + Listens on the systemd Journal for certain messages. + + This is done to be able to detect when Lipstick throws an error on start, + and a file from a patch caused an error. + */ /*! \fn Journal::matchFound() - Emitted when the fileters found a log entry that matched. + Emitted when the filters found a log entry that matched. */ Journal::Journal(QObject *parent) : QObject(parent) @@ -45,7 +53,7 @@ void Journal::wait() thread->start(); } -/*! Attaches itself to the Journal, filetering for \e Lipstick and \e jolla-settings executables. */ +/*! Attaches itself to the Journal, filtering for \e Lipstick and \e jolla-settings executables. */ void Journal::init() { qDebug() << Q_FUNC_INFO; @@ -67,7 +75,7 @@ void Journal::init() wait(); } -/*! Read the message from the Journal, look got certain strings, and emit the matchFound signal if found. +/*! Read the messages, look for certain strings, and emit the matchFound signal if found. Strings looked for are: diff --git a/src/bin/patchmanager-daemon/patchmanagerobject.cpp b/src/bin/patchmanager-daemon/patchmanagerobject.cpp index ac641110b..1da1c9345 100644 --- a/src/bin/patchmanager-daemon/patchmanagerobject.cpp +++ b/src/bin/patchmanager-daemon/patchmanagerobject.cpp @@ -166,8 +166,7 @@ static const QString KEYBOARD_CODE = QStringLiteral("keyboard"); \enum PatchManagerObject::NotifyAction \relates PatchManagerObject::notify() - This enum specifies the type of notification to emit through \c - PatchManagerObject::notify() + This enum is used to signal state changes in the patch list. \value NotifyActionSuccessApply applying was successful @@ -1100,7 +1099,7 @@ QString PatchManagerObject::getRpmName(const QString &rpm) const Handle command line arguments, and may daemonise. If called with any other argument other than \c --daemon, call a method - corresponding to the command line option on the bus and exit. + coresponding to the command line option on D-Bus and exit. Currently supported command line options are: @@ -1123,6 +1122,8 @@ QString PatchManagerObject::getRpmName(const QString &rpm) const \li Calls the "unapply" action for all Patches. \endtable + \note this is called from \c main() via \l{https://doc.qt.io/archives/qt-5.6/qtimer.html#singleShot-prop}{QTimer::singleShot} + */ void PatchManagerObject::process() { @@ -1181,6 +1182,7 @@ void PatchManagerObject::process() QCoreApplication::exit(0); return; } + } @@ -1194,7 +1196,7 @@ QVariantList PatchManagerObject::listPatches() return QVariantList(); } -/*! Returns all versions contained in all Patch metadata. */ +/*! Returns all versions contained in the metadata of all patches, indexed by patch name. */ QVariantMap PatchManagerObject::listVersions() { qDebug() << Q_FUNC_INFO; @@ -1213,9 +1215,8 @@ bool PatchManagerObject::isPatchApplied(const QString &patch) return m_appliedPatches.contains(patch); } -/*! - Calls the corresponding method over D-Bus to activate (apply) \a patch - +/*! Calls the corresponding method over D-Bus to activate (apply) \a patch + \warning This function always returns an empty(!) \c QVariantMap */ QVariantMap PatchManagerObject::applyPatch(const QString &patch) @@ -1385,10 +1386,11 @@ QString PatchManagerObject::checkEaster() return QString(); } -/*! - Calls the corresponding method over D-Bus to update the \l {Patchmanager Web Catalog}{Web Catalog} - metadata. \a params stores the connection properties. -*/ +/*! Calls the corresponding method over D-Bus to update the \l {Patchmanager Web Catalog}{Web Catalog} Metadata. + \a params holds the query properties. + + \sa requestDownloadCatalog_link + * */ QVariantList PatchManagerObject::downloadCatalog(const QVariantMap ¶ms) { DBUS_GUARD(QVariantList()) @@ -1403,7 +1405,7 @@ QVariantList PatchManagerObject::downloadCatalog(const QVariantMap ¶ms) /*! Calls the corresponding method over D-Bus to download metadata for a Patch with the name \a name - \sa requestDownloadPatchInfo + \sa requestDownloadPatchInfo_link */ QVariantMap PatchManagerObject::downloadPatchInfo(const QString &name) { @@ -1438,9 +1440,11 @@ QVariantMap PatchManagerObject::getUpdates() const \fn bool PatchManagerObject::putSettings(const QString &name, const QDBusVariant &value) \fn bool PatchManagerObject::putSettings(const QString &name, const QVariant &value) - Store setting called \a name to the persistent config, \c s_newConfigLocation, and give it value \a value. + Store a setting called \a name to the persistent config, setting it to \a value. Returns \c true if successful. + + \sa {Patchmanager Configuration Files}, inifile */ bool PatchManagerObject::putSettings(const QString &name, const QDBusVariant &value) { @@ -1467,10 +1471,11 @@ bool PatchManagerObject::putSettings(const QString &name, const QVariant &value) \fn QDBusVariant PatchManagerObject::getSettings(const QString &name, const QDBusVariant &def) \fn QVariant PatchManagerObject::getSettings(const QString &name, const QVariant &def) const - Retrieve a setting called \a name from the persistent config, \c s_newConfigLocation - Use \a def as the default value if not present. + Retrieve a setting called \a name from the persistent config, using \a def as the default value if not present. - Returns a \c QDBusVariant or \c QVariant if successful. + Returns a variant containing the value(s) if successful. + + \sa {Patchmanager Configuration Files} */ QDBusVariant PatchManagerObject::getSettings(const QString &name, const QDBusVariant &def) @@ -1529,7 +1534,8 @@ QString PatchManagerObject::maxVersion(const QString &version1, const QString &v For regular processes, \c killall will be performed on them. - Systemd services will be restarted via D-Bus call, or if that fails, via \c systemctl-user. + For systemd services, they will be restarted via D-Bus call, or if that fails, via \c systemctl-user. + */ void PatchManagerObject::restartServices() { @@ -1612,7 +1618,8 @@ QStringList PatchManagerObject::getToggleServicesList() const return m_toggleServices.keys(); } -/*! Returns \c true if there are services that should be restarted, \c false otherwise. */ +/*! Returns \c true when there are services that should be restarted, \c false otherwise. +*/ bool PatchManagerObject::getToggleServices() const { return !m_toggleServices.isEmpty(); @@ -1701,7 +1708,7 @@ void PatchManagerObject::loadRequest(bool apply) \li "restarted" \endlist - See also \c lipstick-patchmanager.service, {Patchmanager Service} + See the documentation for \c lipstick-patchmanager.service under {Patchmanager Services} */ void PatchManagerObject::lipstickChanged(const QString &state) { @@ -2629,6 +2636,9 @@ void PatchManagerObject::downloadPatch(const QString &patch, const QUrl &url, co }); } +/*! Connect to the Web Catalog and retrieve a response configured by \a params. + \target requestDownloadCatalog_link + */ void PatchManagerObject::requestDownloadCatalog(const QVariantMap ¶ms, const QDBusMessage &message) { qDebug() << Q_FUNC_INFO << params; @@ -2671,7 +2681,7 @@ void PatchManagerObject::requestDownloadCatalog(const QVariantMap ¶ms, const /*! Retrieve Patch metadata from the \l {Patchmanager Web Catalog}{Web Catalog}, use Patch \a name, reply with message \a message - \target requestDownloadPatchInfo + \target requestDownloadPatchInfo_link */ void PatchManagerObject::requestDownloadPatchInfo(const QString &name, const QDBusMessage &message) { diff --git a/src/externalpages.qdoc b/src/externalpages.qdoc new file mode 100644 index 000000000..34b9891ae --- /dev/null +++ b/src/externalpages.qdoc @@ -0,0 +1,90 @@ +/*! + \externalpage https://sailfishos-patches.github.io/patchmanager + \title Documentation Home +*/ +/*! + \externalpage https://doc.qt.io/archives/qt-5.6/ + \title Qt 5.6 Documentation +*/ +/*! + \externalpage https://coderus.openrepos.net/pm2/projects/ + \title Web Catalog Site +*/ +/*! + \externalpage https://github.com/CODeRUS/django-test + \title Web Catalog Source Code Repository +*/ +/*! + \externalpage https://github.com/sailfishos-patches/patchmanager + \title Patchmanager GitHub Repository +*/ +/*! + \externalpage https://github.com/sailfishos-patches/patchmanager/blob/master/README.md + \title Patchmanager README +*/ +/*! + \externalpage https://openrepos.net/content/olf/sailfishoschum-gui-installer + \title SailfishOS:Chum GUI Installer +*/ +/*! + \externalpage https://openrepos.net/user/16848/programs + \title OpenRepos repository +*/ +/*! + \externalpage https://openrepos.net/content/olf/storeman-installer + \title Storeman Installer +*/ +/*! + \externalpage https://github.com/sailfishos-patches/patchmanager/releases + \title Releases page +*/ +/*! + \externalpage https://openrepos.net/category/patches + \title Patch RPMs at OpenRepos +*/ + +/****** Try to fix autlinking errors for Silica types*****/ +/*! + \externalpage https://sailfishos.org/develop/docs/silica/qml-sailfishsilica-sailfish-silica-sectionheader.html/ + \title Sailfish.Silica.SectionHeader +*/ +/*! + \externalpage https://sailfishos.org/develop/docs/silica/qml-sailfishsilica-sailfish-silica-viewplaceholder.html/ + \title Sailfish.Silica.ViewPlaceholder +*/ +/*! + \externalpage https://sailfishos.org/develop/docs/silica/qml-sailfishsilica-sailfish-silica-page.html/ + \title Sailfish.Silica.Page +*/ +/****** Try to fix autlinking errors for standard Qt types*****/ +/*! \externalpage https://doc.qt.io/archives/qt-5.6/qml-qtqml-models-listmodel.html + \title ListModel */ +/*! \externalpage https://doc.qt.io/archives/qt-5.6/qstring.html + \title QString */ +/*! \externalpage https://doc.qt.io/archives/qt-5.6/qvariant.html + \title QVariant */ +/*! \externalpage https://doc.qt.io/archives/qt-5.6/qqmlpropertymap.html + \title QQmlPropertyMap */ +/*! \externalpage https://doc.qt.io/archives/qt-5.6/qabstractitemmodel.html + \title QAbstractItemModel */ +/*! \externalpage https://doc.qt.io/archives/qt-5.6/qt.html#ItemDataRole-enum + \title DisplayRole */ +/*! \externalpage https://doc.qt.io/archives/qt-5.6/qt.html#ItemDataRole-enum + \title DecorationRole */ +/*! \externalpage https://doc.qt.io/archives/qt-5.6/qt.html#ItemDataRole-enum + \title EditRole */ +/*! \externalpage https://doc.qt.io/archives/qt-5.6/qml-qtqml-qt.html#qsTranslate-method + \title qsTranslate() */ +/*! \externalpage https://doc.qt.io/archives/qt-5.6/qfile.html + \title QFile + \target Qt::QFile::exists() +*/ + + +/*! \externalpage https://doc.qt.io/archives/qt-5.6/qloggingcategory.html#logging-rules + \title Qt Logging Rules +*/ + +/*! \externalpage https://dbus.freedesktop.org/doc/dbus-daemon.1.html + \title D-Bus Documentation +*/ diff --git a/src/index.qdoc b/src/index.qdoc index 3b86f03e0..0b4a5ce10 100644 --- a/src/index.qdoc +++ b/src/index.qdoc @@ -4,9 +4,19 @@ \title Patchmanager Documentation - For User documentation, see \l {https://github.com/sailfishos-patches/patchmanager/#information-for-users}{User Documentation}. + \section1 User documentation - For Patch Developer documentation, see \l {https://github.com/sailfishos-patches/patchmanager/#information-for-patch-developers}{Developer Documentation}. + See: + + \list + \li \l {Patchmanager for SailfishOS} + \endlist + + \section1 Patch Developers + For information for Patch Developers, see: + \list + \li \l{Patch Developer Documentation} + \endlist \section1 Internals @@ -18,18 +28,28 @@ \li \l {Patchmanager Configuration Files} \endlist - \section1 Applications + \section1 Patchmanager Developers + + \section2 Translations + + If you want to translate ("localise") Patchmanager to a language you know + well or enhance an existing translation, please read Patchmanager's + corresponding Wiki page + + \l{https://github.com/sailfishos-patches/patchmanager/wiki/Translations-(%22i18n%22,-%22l10n%22)}{Translations ("i18n", "l10n")}. + + \section2 Applications The Patchmanager project includes these applications: - \section2 GUI Applications + \section3 GUI Applications \list \li \l {Patchmanager Documentation: Settings Plugin}{Patchmanager Settings Plugin}, a plugin for the Jolla Settings app to launch the Patchmanager application \li \l {Patchmanager Documentation: QML Plugin}{Patchmanager QML Plugin}, the main GUI Application \li \l {Patchmanager Documentation: Startup Dialog}{Patchmanager Startup Dialog}, a GUI shown at Lipstick startup \endlist - \section2 Infrastructure Applications + \section3 Infrastructure Applications \list \li \l {Patchmanager Documentation: Daemon}{Patchmanager Daemon} \li \l {Patchmanager Documentation: Preload Library}{Preload Library} @@ -40,7 +60,7 @@ /****** Overview page *******/ /*! - \title Overview of Patchmanager (PM) + \title Patchmanager Overview \page pmoverview.html overview \indexpage Patchmanager Documentation @@ -54,11 +74,13 @@ When a user activates a Patch via the GUI, a signal is sent to the Patchmanager daemon. - The daemon will then: + When activated, for each file the patch manipulates, a copy of the original + file is put into a cache directory in \c /tmp, and the changes are applied there + instead of on the original file. - For each file a Patch alters, copy the original file into a cache directory in \c /tmp and apply the changes to this copy instead of the original. - - If paths or files are referenced by a Patch which do not yet exist on the filesystem, these will be created in the cache directory, and symlinks pointing to them are placed in the original filesystem. + If there are paths or files involved in the patch which do not exist yet + in the filesystem, they will be created in the cache directory, and a symbolic link + pointing to them is placed in the original filesystem. \section2 2. A patched application is launched. @@ -68,26 +90,35 @@ \list \li Intercepts calls to \l {https://www.man7.org/linux/man-pages/man2/open.2.html}{\c{open()} (or \c{open64()})}, - \li analyses which files the call was meant to open - \li asks the Patchmanager daemon (via socket) if it is aware of a patched version of any of these files. + \li analyzes which files the call was meant to open + \li asks the Patchmanager daemon (via UNIX Socket) whether it knows of a patched version. \endlist - If so, the daemon will return a path to its cache directory, and the library redirects the call to that file instead of the original. Otherwise, the \c{open()} call is executed on the original file. + If yes, the daemon will return a path to its cache directory, and the library + redirects the call to that file instead of the original. Otherwise, the + \c{open()} is executed on the original file. Certain paths are blacklisted for these operations to reduce the risk of critical services, or the Patchmanager binaries proper, stumbling over these redirections. - \note After activating a Patch, the Patchmanager daemon may inform the Patchmanager GUI that some apps or services need to be restarted. As long as the corresponding processes are not restarted, the applied Patch will be not at all or only partially in effect, depending on the "patch history" of the respective process. + \warning After activating a Patch , the daemon may also inform the UI that some + apps or services need restart. The UI client is expected to issue the command + to restart these soon. + As long as the corresponding processes are not restarted, the effect of the + applied patch will not show, or may only show partially, depending on the "patch + history" of the respective process. - \section1 Patch Installation - There are four ways a Patch can be deployed: + \note Due to the nature of the interaction between the daemon and the + library, applications which are executed ... \list - \li Web Catalog - \li RPM package - \li TAR package - \li manual installation + \li without respecting \c /etc/ld.so.preload (e.g. Android binaries in the base system) + \li before the daemon has started and initialised \endlist + ... will obviously not see patched file contents. Patch authors are advised + to use other methods (e.g. proper RPM packages, or e.g. systemd services to + manipulate files in these cases, and refrain from using Patches to do that.) + \section2 Patch folder structure All Patches managed by PM are installed under \c /usr/share/patchmanager/patches/NAME with NAME being a uniquely named directory. @@ -136,6 +167,12 @@ \e{to be continued...} + \section2 Development + + Web Catalog is in production, but its development is in maintainance-only mode. + + The source code is currently maintained at \l {Web Catalog Source Code Repository} + */ /****** Services Documentation page *******/ @@ -154,7 +191,7 @@ It is defined as follows: - \quotefile dbus/org.SfietKonstantin.patchmanager.xml + \quotefile org.SfietKonstantin.patchmanager.xml Calls can be issued this way, for example: @@ -171,17 +208,17 @@ \li Component \li Description \row - \li \c UNITDIR/checkForUpdates-org.SfietKonstantin.patchmanager.service + \li \c checkForUpdates-org.SfietKonstantin.patchmanager.service \li service \li - - \li Calls the \c checkForUpdates() method via D-Bus. + \li Calls the \l {PatchManagerObject::checkForUpdates}{checkForUpdates()} method via D-Bus. \row - \li \c UNITDIR/checkForUpdates-org.SfietKonstantin.patchmanager.timer + \li \c checkForUpdates-org.SfietKonstantin.patchmanager.timer \li timer \li - \li Runs the service above, every two hours. \row - \li \c UNITDIR/dbus-org.SfietKonstantin.patchmanager.service + \li \c dbus-org.SfietKonstantin.patchmanager.service \li dbus-activated service \li \l {Patchmanager Documentation: Daemon}{Daemon} \li Starts / activates the D-Bus service. @@ -198,6 +235,7 @@ \endtable \section2 Systemd User Units + \target sd_userunits \table \header @@ -206,15 +244,15 @@ \li Component \li Description \row - \li \c $USERUNITDIR/dbus-org.SfietKonstantin.patchmanager.service + \li \c dbus-org.SfietKonstantin.patchmanager.service \li dbus-activated service \li \l {Patchmanager Documentation: Startup Dialog}{Dialog} \li Starts the Startup Dialog, if necessary. \row - \li \c $USERUNITDIR/lipstick-patchmanager.service + \li \c lipstick-patchmanager.service \li service \li \l {Patchmanager Documentation: Startup Dialog}{Dialog} - \li Calls the \c lipstickChanged() method via D-Bus. + \li Calls the \l {PatchManagerObject::lipstickChanged}{lipstickChanged()} method via D-Bus. \row \li \c /var/lib/environment/patchmanager-dialog/*.conf \li environment file @@ -222,21 +260,30 @@ \li Configures the environment in which the dialog service is started. \endtable - \c lipstick-patchmanager.service watches the state of the Lipstick service. If Lipstick crashes, the Patchmanager daemon assumes it was caused by a Patch and goes into \c failed state. In this state, all enabled services are disabled, and PM must be reactivated via the GUI. + \c lipstick-patchmanager.service watches the state of the Lipstick service. + If Lipstick crashes, the Patchmanager daemon assumes it was caused by a patch + and goes into \c failed state. In this state, no Patches are activated, and + PM must be reactivated via the GUI. \section1 Manual Invocation - Aside of using appropriate tools as \c systemctl, \c busctl, or \c dbus-send to invoke Patchmanager's functions, the patchmanager binary can also serve as CLI, if called from command line. See the output of \c{patchmanager --help} and PatchManagerObject::process() for more information. + Aside of using appropriate tools as \c systemctl, \c busctl, or \c dbus-send + to invoke Patchmanager's functions, the patchmanager binary can also serve as + CLI, if called from command line. See the output of \c{patchmanager --help} + and PatchManagerObject::process() for more information. - Additionally a shell script called \c patchmanager-tool exists, which builds upon the capabilities of \c patchmanager to provide more sophisticated and generic functions. + There is also a shell script called \c patchmanager-tool, wrapping the + capabilities of \c patchmanager to generate more useful functions. - \note At the time of compiling this documentation, \c patchmanager-tool is not yet distributed as part of the regular RPM packages. It can be obtained from the directory \c src/tools/ in Patchmanager's source code repository. + \note At the time this was written, \c patchmanager-tool is not yet + distributed with the default packages. You can find it in the source + repository though, under \c src/tools/. \section1 Logging and Debugging - Debug logging by the Patchmananger daemon can be configured by setting the \c QT_LOGGING_RULES variable to, e.g., \c{"*.debug=true"} in the environment file \c /var/lib/environment/patchmanager/10-dbus.conf + About the contents of the configuration files, see \l {Patchmanager Configuration Files}. - After changing this, Patchmanager's system service must be restarted for evaluating the new values. + After changing its configuration, Patchmanager's system service must be restarted. */ /****** Services Documentation page *******/ @@ -250,11 +297,14 @@ \target inifile - An INI-style configuration file and state storage. + Stores configuration and state storage for the \l {Patchmanager Documentation: Daemon}{Daemon}. - It consists of two sections: \c settings and \c votes + It is an INI-style configuration file and has two possible sections: \c settings and \c votes. - \section3 \c settings + \note The location of the file is determined by the \c s_newConfigLocation constant + of the daemon source. (See the head of \c{src/bin/patchmanager-daemon/patchmanagerobject.cpp}) + + \section3 Config section \c [settings] \table \header @@ -263,56 +313,88 @@ \li default \li Description \row - \li applied + \li \c applied \li list of strings, comma-separated \li empty \li Stores the list of "activated" Patches. \row - \li workingPatches + \li \c workingPatches \li list of strings, comma-separated \li empty \li Stores a list of Patches, which represent a "last-known-good" / working set of enabled Patches. This list is automatically copied from \c applied after each successful run of auto-apply. \row - \li applyOnBoot - \li Boolean + \li \c applyOnBoot + \li boolean \li \c false \li Whether to activate all enabled Patches during OS startup or to show the {Patchmanager Documentation: Startup Dialog}{Startup Dialog}. \row - \li bitnessMangle - \li Boolean + \li \c bitnessMangle + \li boolean \li \c false \li Convert Patch contents so they are applicable to the local architecture (e.g., \c lib versus \c lib64 path elements). \row - \li developerMode - \li Boolean + \li \c developerMode + \li boolean \li \c false \li \warning \b deprecated. Before Patchmanager 3.2.7, this was used to store the settings for the "Developer Mode". This mode has been split into \c patchDevelMode and \c sfosVersionCheck \row - \li notifyOnSuccess - \li Boolean + \li \c notifyOnSuccess + \li boolean \li \c true \li Whether to show notifications about successful actions on the GUI. \row - \li order + \li \c order \li list of strings, comma-separated \li empty \li The order of Patches, both in the list on the GUI, and the sequence in which they will be activated and hence their patch files applied. \row - \li patchDevelMode - \li Boolean + \li \c patchDevelMode + \li boolean \li \c false \li \row - \li sfosVersionCheck - \li Integer (Enum) + \li \c sfosVersionCheck + \li integer (enum) \li 0 (strict) \li Whether to relax the version checking in the Patchmanager GUI. The default setting will only allow Patches to be downloaded or activated, of which an entry in their compatibility field exactly matches the currently installed OS version. \endtable - \section3 \c [votes] + \section3 Config section [votes] + + Saves the voting state for each patch a user has voted on in the + {Patchmanager Documentation: Settings Plugin}{Settings Plugin}. + + \section2 \c{/var/lib/environment/patchmanager-dialog/} + + This location can contain one or more environment files for a systemd service + (see \l {https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html}{systemd.exec}). + Their filename must end in \c{.conf} and are read by \l {sd_userunits}{dbus-org.SfietKonstantin.patchmanager.service}. - \e{to be written...} + Files placed here can be used to alter logging behaviour of the Dialog by + changing the value of \c QT_LOGGING_RULES. + + \sa {Patchmanager Services} + + \note In default patchmanager installations, this location does not exist. - \section2 \c{/var/lib/environment/patchmanager-dialog/*.conf} \section2 \c{/var/lib/environment/patchmanager/10-dbus.conf} + + This file is read by the \l {Patchmanager Documentation: Daemon}{Daemon}. + + Configures the location of the socket file used to communicate with + applications in user scope via \c DBUS_SESSION_BUS_ADDRESS. + Per default this is \c {unix:path=/run/user/100000/dbus/user_bus_socket}. + + If unset, the Daemon will fallback to a hardcoded default. + + \warning Due to this setting, the socket can only be accessed by applications + runing as the "Device Owner" user (UID 100000), i.e. either \c nemo or \c defaultuser. + + This file can also be used to alter logging behaviour of the Daemon by + changing the value of \c QT_LOGGING_RULES. Per default this is set to + \c{*.debug=false}. + + \sa {Patchmanager Services}, {D-Bus Documentation}, {Qt Logging Rules} + */ + diff --git a/src/patchdev.qdoc b/src/patchdev.qdoc new file mode 100644 index 000000000..cedb79944 --- /dev/null +++ b/src/patchdev.qdoc @@ -0,0 +1,215 @@ +/*! + + \page patchdev.html overview + \indexpage Patchmanager Documentation + + \title Patch Developer Documentation + + \section1 Patch Installation + \target patchdevinstall + + There are three ways a Patch can end up on the system: + + \list + \li Web Catalog + \li RPM package + \li TAR package + \li manual installation + \endlist + + \section2 Web Catalog + + Installation via the Patchmanager Web Catalog is the most common and + recommended way of installing a patch. This is done through the Patchmanager + UI, by selecting \uicontrol install on the \l {WebPatchPage}{Patch Page}. + + PM will download metadata and a tarball from the Web Catalog, extract the + tarball into the patch storage location, and generate the necessary JSON file + from the metadata. + + \sa {Patchmanager Web Catalog}{Web Catalog} + + \section2 RPM package + + Patches may be distributed as RPM files, which assure the placement of files + according to the structure explained above. RPM also provides advanced + features like dependencies and scriptlets which may be necessary for correct + operation or installation of a Patch. + + \section2 TAR package + + Patch developers may sometimes distribute Patches in \c tar format. Usually + they also contain the necessary files, but the contents of the tarball may + differ, and recipients of them must assure the layout given above is set up + correctly. + + \section2 manual installation + + Patch developers or users may want to quickly place a Patch under PM's + supervision without going through the hassle of packaging and installing. + This can be done easily, as long as the formats given above are followed. + + \section1 Patch format + + \section2 Patch folder structure + + All Patches managed by PM are installed under \c /usr/share/patchmanager/patches/$NAME, + where \c $NAME is a directory having a unique name. + + That directory must contain at least two files: a \c JSON file called + \c patch.json containing metadata, and a \c diff file called \c{unified_diff.patch}. + + For information about \c patch.json metadata, see \l{metadata}, and + \l{https://github.com/sailfishos-patches/patchmanager/blob/master/README.md#the-json-metadata-file}{README} + + \c{unified_diff.patch} must be in unified diff format, and must apply against + the filesystem root when using patch with the options \c{ -d / -p 1 --no-backup-if-mismatch } + + It may optionally also contain: + \list + \li Qt translation (.qm) files + \li icon files in PNG format + \li a QML file called \c main.qml (whose root element is a Sailfish Silica \c{Page}). + \li other QML-compatible files which are referenced/loaded from \c main.qml + \endlist + + \note the directory \c $NAME is usually and by convention the same as the + patch metadata field \c name, but that is not a requirement. \c $NAME should + be reasonably unique though, to avoid name clashes with Patches from others. + + \section2 Metadata + + See \l {Patch Metadata} +*/ + +/****** Patch Metadata Documentation page *******/ + +/*! + \title Patch Metadata + + \page patchmeta.html overview + \indexpage Patchmanager Documentation + \previouspage Patch Developer Documentation + + \target metadata + + A JSON file. + + The metadata file contains information about a Patch. It is a simple JSON file, that must be named \c patch.json. + + \warning This files is automatically generated and added to your Patch + distribution if you choose to upload your Patch to the Web Catalog. + You should NOT include one with your Patch if you do that. + + If you distribute your Patch some other way, e.g. as an RPM package, you must + provide a valid \c patch.json file. + + You may use either the \l{newjson}{modern format} or the much simpler \l{legacyjson}{legacy format}. + Both are supported, but the modern one provides more useful features and is recommended. + + \section2 Example patch.json + \target newjson + + This describes the preferred format of \c patch.json. + + \badcode + { + "author": "Jim Example", + "name": "the-internal-patch-name", + "display_name": "Human-facing Patch Name", + "version": "1.0.0", + "category": "calendar", + "description": "This is a long description of what this Patch does.\nIt will be displayed in the Patch page.", + "discussion": "https://example.org/forum/thead?id=9999", + "sources": "https://git.example.org/patch.git", + "donations": "https://example.org/donate", + "compatible": [ "3.2.1.20", "3.3.0.14", "3.3.0.16" ], + "id": NNN, + "last_updated": "2020-04-28T06:56:21.931", + } + \endcode + + \section2 Description of options: + + Required / Recommended: + + \list + \li \c name: An internal name for the Patch. As this is used as a directory name, it should only contain alphanumeric characters, underscores and hyphens. Notably NO spaces, dollar signs or other special characters should be used! + \li \c display_name: The name of the Patch, which will be shown on the patch list. + \li \c version: A version string. It MUST be in the format X.Y.Z + \li \c author: The name of the principal Patch author or maintainer. Either use your real name, as displayed on Github or Twitter, or your usual nickname. + \li \c compatible: A list of SailfishOS releases the Patch works on. Versions MUST be given in full with all four fields populated, e.g. "3.3.0.16" (using just "3.3" is invalid). + \endlist + + Optional: + \list + \li \c description: Explanation of what the Patch does. + \li \c category: This is used to structure the list of Patches in categories, but also certain categories will cause Patchmanager to restart affected system services or applications. For example, Patches in the category "homescreen" will prompt the user to restart Lipstick after their activation. + \li \c discussion, sources, donations: Optional links to websites. + \li \c last_updated: An ISO date string, the Web Catalog sets this. It is used for sorting and update detection. + \endlist + + Reserved: + \list + \li id: A numeric ID used by Web Catalog. This MUST NOT be included in Patches which are not distributed via Web Catalog. + \endlist + + \section2 List of supported categories: + \target jsoncats + + \warning Supplying no category, or a category not on this list will cause the + Patch to be shown in the category "other", and no affected applications will + be restarted after the patch is activated. + + \list + \li "homescreen" - will restart Lipstick + \li "silica" - will restart Lipstick + \li "keyboard" - will restart the keyboard service + \endlist + + These will stop or restart the corresponding system applications (e.g. the + jolla-browser) after activating the Patch. + + \list + \li "browser" + \li "calendar" + \li "camera" + \li "clock" + \li "contacts" + \li "email" + \li "gallery" + \li "media" + \li "messages" + \li "phone" + \li "settings" + \endlist + + \section2 Example patch.json in legacy format + \target legacyjson + + This describes the format of the \c patch.json file in the \e legacy format. + While this is still supported in Patchmanager 3, if possible switch to \l{newjson}{the new format} as it supports more useful information. + + \badcode + { + "name": "Example Patch Name", + "description": "This is a long description of what this Patch does.\nIt will be displayed on the Patch page.", + "category": "email", + "infos": { + "maintainer": "username" + }, + } + \endcode + + \section3 Description of options: + + \list + \li name: The "display name" of the patch, which will be shown on the Patch list. + \li description: Explanation of what the Patch does. + \li maintainer: The name of the principal Patch author or maintainer. Either use your real name, as displayed on Github or Twitter, or your usual nickname. + \li category: see \l{jsoncats}{above} + \endlist + + +*/ + diff --git a/src/plugin/patchmanager.qml b/src/plugin/patchmanager.qml index 4f73623c4..72b67819e 100644 --- a/src/plugin/patchmanager.qml +++ b/src/plugin/patchmanager.qml @@ -1,11 +1,10 @@ import org.SfietKonstantin.patchmanager 2.0 /*! \qmltype patchmanager - \inqmlmodule patchmanager + \inqmlmodule org.SfietKonstantin.patchmanager \brief Jolla Settings Plugin Page - \inherits \l {Page} - This loads the main Patchmanager UI from Jolla Settings. + This is a minimal QML Component that loads the main Patchmanager UI from Jolla Settings. */ PatchManagerPage {} diff --git a/src/plugin/plugin.qdoc b/src/plugin/plugin.qdoc index 4a07a8874..daf88010c 100644 --- a/src/plugin/plugin.qdoc +++ b/src/plugin/plugin.qdoc @@ -7,12 +7,15 @@ The Settings Plugin makes up the main Patchmanager GUI Application. - Jolla Settings loads this page which in turn loads + Jolla Settings loads \l {patchmanager}{this page} which in turn loads PatchManagerPage, a part of \l {Patchmanager Documentation: QML Plugin}{Patchmanager QML Plugin}. \section2 Configuration - The Jolla Settings plugin configuration looks like this: + The Jolla Settings plugin configuration (installed at \c + /usr/share/jolla-settings/entries/) looks like below. It adds an entry to + the Settings application, and optionally can be added to the Top Menu quick + links. \badcode { @@ -33,8 +36,5 @@ } \endcode - \section2 Types - - This plugin provides no types. */ diff --git a/src/preload/src/preloadpatchmanager.qdoc b/src/preload/src/preloadpatchmanager.qdoc index de385c81b..a23ce66fd 100644 --- a/src/preload/src/preloadpatchmanager.qdoc +++ b/src/preload/src/preloadpatchmanager.qdoc @@ -10,7 +10,7 @@ This library \list - \li Intercepts calls to \l {https://www.man7.org/linux/man-pages/man2/open.2.html}{\c{open()} (or \c{open64()})}, + \li Intercepts calls to \l {https://www.man7.org/linux/man-pages/man2/open.2.html}{\c{open()}} (or \c{open64()}), \li analyzes which files the call was meant to open \li asks the Patchmanager Daemon (via socket) whether it knows of a patched version. \endlist @@ -22,11 +22,8 @@ Certain paths are blacklisted for these operations to reduce the risk of critical services, or PM itself, choking on these redirections. - \e{to be continued...} - \section1 Implementation - \e{to be continued...} \section3 Blacklists: The following two "blacklists" cause the lib to back off redirecting calls for paths matching one of the entries in the list: @@ -49,16 +46,16 @@ \li Default \li Description \row - \li NO_INTERCEPT + \li \c NO_INTERCEPT \li undefined - \li Compiles out all of the actual redirection code, leaving the rest in place. Can be used in extreme debugging cases te track what is going on without affecting applications. + \li If defined, compiles out all of the actual redirection code, leaving the rest in place. Can be used in extreme debugging cases to track what is going on without affecting applications. \row - \li ALLOW_ALL_USERS + \li \c ALLOW_ALL_USERS \li defined - \li Only allow preloading for users with an UID >= \c UID_MIN, default 100000 + \li If undefined, only allow preloading for users with an UID >= \c UID_MIN, default 100000 \endtable - \section1 Running + \section1 Execution \section2 Installation Once the library is installed in one of the standard library paths, the following is added to the file \c /etc/ld.so.preload @@ -82,11 +79,11 @@ \li Default \li Description \row - \li NO_PM_PRELOAD + \li \c NO_PM_PRELOAD \li undefined - \li Makes the lib skip finding files to redirect to, effectively diabling it ofr practical purposes. Intended to be set for processes which should operate on unpatched original files. + \li Makes the lib skip finding files to redirect to, effectively diabling it for practical purposes. Intended to be set for processes which should operate on unpatched original files. \row - \li PM_PRELOAD_DEBUG + \li \c PM_PRELOAD_DEBUG \li undefined \li Enables debugging output; messages are prefixed with \c{[pm_name]}, \c{[open]}, or \c{[open64]} depending on operation. \endtable @@ -95,6 +92,6 @@ \section2 Socket - The library will try to open a socket at \c{/tmp/patchmanager-socket} in order to communicate with the Patchmanager Daemon + The library will try to open a socket at \c{/tmp/patchmanager-socket} in order to communicate with the Patchmanager Daemon. */ diff --git a/src/qml/PatchObject.cpp b/src/qml/PatchObject.cpp index 4c86b84e3..2f99f535f 100644 --- a/src/qml/PatchObject.cpp +++ b/src/qml/PatchObject.cpp @@ -53,8 +53,63 @@ /*! \qmlsignal PatchObject::toBeDestroyed(PatchObject object); This signal is emitted when \a object is about to be destroyed. (Duh.) */ -/*! \qmlsignal PatchObject::busyChanged(); - \internal + +/*! \qmlproperty var PatchObject::details + + The patch \l{metadata} mapped to an QML Object. + + \table + \header + \li Name + \li Type + \li Description + + \row + \li \c category + \li string + \li Corresponds to the field of the same name in the patch metadata. + + \row + \li \c display_name + \li string + \li Corresponds to the field of the same name in the patch metadata. + + \row + \li \c name + \li string + \li Corresponds to the field of the same name in the patch metadata. + + \row + \li \c patch + \li string + \li Corresponds to the field of the same name in the patch metadata. + + \row + \li \c section + \li string + \li Corresponds to the field of the same name in the patch metadata. + + \row + \li \c isNewPatch + \li bool + \li \c true if this patches metadata is in current format, \c false if it's legacy data. + + \row + \li \c patched + \li bool + \li \c true if this patch is currently applied, \c false otherwise. + + \row + \li \c ok + \li bool + \li \c true if the last apply process succeeded, \c false otherwise. + + \row + \li \c log + \li string + \li Holds the output from the latest patching process. + + \endtable */ PatchObject::PatchObject(const QVariantMap &data, QObject *parent) @@ -78,6 +133,8 @@ PatchObject::PatchObject(const QVariantMap &data, QObject *parent) /*! \class PatchObject \inmodule org.SfietKonstantin.patchmanager \brief An element to be used as content of an \l {PatchManagerModel} + + Upon construction, the \c data parameter is mapped to PatchObject::details */ PatchObject::~PatchObject() { @@ -85,14 +142,11 @@ PatchObject::~PatchObject() emit toBeDestroyed(this); } -/*! \qmlproperty var PatchObject::details - - Holds the Patch metadata. -*/ /*! \property PatchObject::details - \inheaderfile PatchObject.hpp - \sa {https://doc.qt.io/qt-5/qqmlpropertymap.html}{QQmlPropertyMap} + Maps the internal property names and values to QML properties. + + See QQmlPropertyMap */ QQmlPropertyMap *PatchObject::details() { @@ -104,7 +158,7 @@ QQmlPropertyMap *PatchObject::details() \c true when an internal operation is in progress. */ /*! \property PatchObject::busy - \inheaderfile PatchObject.hpp + \c true when an internal operation is in progress. */ /*! Returns \c true when an internal operation is in progress. */ @@ -114,9 +168,13 @@ bool PatchObject::busy() const } /*! - Fills the PatchObject's properties from \a data. + Populates the \c details property from \a data. + + If there is a \c display_name field in \a data, and \a data is treated as + regular patch metadata (\c isNewPatch is set to \c true). + Otherwise, the field \c name is used for display name, and the data is + treated as legacy metadata. - \note If there is a "display_name" field in \a data, it is used. Otherwise, patch name is used. */ void PatchObject::setData(const QVariantMap &data) { @@ -133,10 +191,9 @@ void PatchObject::setData(const QVariantMap &data) } /*! - Calls PatchManager::applyPatch with the patch name. If \a callback is callable, calls it afterwards. - Does nothing if the \c "patched" property is \c true. + Calls PatchManager::applyPatch with the patch name. Calls \a callback afterwards (if callable). - \sa PatchManager::applyPatch + \note Does nothing if the \c patched property is \c true. */ void PatchObject::apply(QJSValue callback) { @@ -176,10 +233,9 @@ void PatchObject::apply(QJSValue callback) } /*! - Calls PatchManager::unapplyPatch() with the patch name. If \a callback is callable, calls it afterwards. - Does nothing if the \c "patched" property is \c false. + Calls PatchManager::unapplyPatch with the patch name. Calls \a callback afterwards (if callable). - \sa PatchManager::unapplyPatch + \note Does nothing if the \c patched property is \c false. */ void PatchObject::unapply(QJSValue callback) { @@ -240,7 +296,7 @@ void PatchObject::uninstall() }); } -/*! Calls PatchManager::resetState. */ +/*! Calls PatchManager::resetState with the patch name. */ void PatchObject::resetState() { qDebug() << Q_FUNC_INFO; diff --git a/src/qml/WebPatchPage.qml b/src/qml/WebPatchPage.qml index efc1e58bc..4b39de35d 100644 --- a/src/qml/WebPatchPage.qml +++ b/src/qml/WebPatchPage.qml @@ -101,7 +101,7 @@ Page { /*! \qmlproperty bool fetching - Indicates whether data is currently being downloaded. The WebPatchPage will show a ViewPlaceholder if true. + Indicates whether data is currently being downloaded. The WebPatchPage will show a \l{Sailfish.Silica.ViewPlaceholder}{ViewPlaceholder} if true. Default \c true */ diff --git a/src/qml/patchmanager.cpp b/src/qml/patchmanager.cpp index 49d1f2b00..c8afdab44 100644 --- a/src/qml/patchmanager.cpp +++ b/src/qml/patchmanager.cpp @@ -75,7 +75,10 @@ static const char *noop_strings[] = { \brief Patchmanager QML Plugin */ - +/*! + \typedef VersionCheck + \relates PatchManagerVersionCheck + */ PatchManager::PatchManager(QObject *parent) : QObject(parent) , m_nam(new QNetworkAccessManager(this)) @@ -316,9 +319,8 @@ PatchManagerModel *PatchManager::installedModel() } /*! - Helper for SectionHeader titles. Looks up translations for \a category. + Helper for \l{Sailfish.Silica.SectionHeader}{SectionHeader} titles. Looks up translations for \a category. Returns the translated string. - \sa {https://sailfishos.org/develop/docs/silica/qml-sailfishsilica-sailfish-silica-sectionheader.html/} */ QString PatchManager::trCategory(const QString &category) const { @@ -672,7 +674,7 @@ void PatchManager::checkForUpdates() } /*! - Saves the setting \a name to \a value over DBus. + Saves the setting \a name to \a value over D-Bus. Returns \c true when done, \c false otherwise. \sa {} {PatchManagerObject::putSettings(const QString &name, const QDBusVariant &value)} @@ -689,7 +691,7 @@ bool PatchManager::putSettingsSync(const QString &name, const QVariant &value) } /*! - Saves the setting \a name to \a value over DBus. + Saves the setting \a name to \a value over D-Bus. Calls \a callback in success, \a errorCallback on failure. @@ -700,7 +702,7 @@ void PatchManager::putSettingsAsync(const QString &name, const QVariant &value, } /*! - Returns the setting \a name over DBus. + Returns the setting \a name over D-Bus. Defaults to \a def */ QVariant PatchManager::getSettingsSync(const QString &name, const QVariant &def) const @@ -714,7 +716,7 @@ QVariant PatchManager::getSettingsSync(const QString &name, const QVariant &def) } /*! - Retrieves the setting \a name over DBus. + Retrieves the setting \a name over D-Bus. Defaults to \a def Calls \a callback in success, \a errorCallback on failure. @@ -749,7 +751,7 @@ void PatchManager::errorCall(QJSValue errorCallback, const QString &message) } /*! - Handler for the DBus signal. Sets the internal list to \a updates if different. + Handler for the D-Bus signal. Sets the internal list to \a updates if different. Emits signal /e updatesChanged() */ @@ -766,7 +768,7 @@ void PatchManager::onUpdatesAvailable(const QVariantMap &updates) } /*! - Handler for the DBus signal. Sets the internal list to \a toggle if different. + Handler for the D-Bus signal. Sets the internal list to \a toggle if different. Emits signal /e toggleServicesChanged(bool toggle) */ @@ -784,7 +786,7 @@ void PatchManager::onToggleServicesChanged(bool toggle) /*! - Handler for the DBus signal. Sets the internal property to \a failed if different. + Handler for the D-Bus signal. Sets the internal property to \a failed if different. Emits \e failureChanged(bool failed) */ @@ -801,7 +803,7 @@ void PatchManager::onFailureChanged(bool failed) } /*! - Handler for the DBus signal. Sets the internal list to \a loaded if different. + Handler for the D-Bus signal. Sets the internal list to \a loaded if different. Emits \e loadedChanged(bool loaded) */ @@ -842,7 +844,7 @@ void PatchManager::resolveFailure() } /*! - Helper to translate a DBus reply object \a val to a valid/usable QVariant + Helper to translate a D-Bus reply object \a val to a valid/usable QVariant Recurse up to \a depth (max. 32). @@ -1058,7 +1060,7 @@ bool PatchManagerTranslator::installTranslator(const QString &patch) /*! Returns \e true if \a filename exists, \e false otherwise. - \sa https://doc.qt.io/qt-5/qfile.html#exists-1 + \sa Qt::QFile::exists() */ bool PatchManager::fileExists(const QString &filename) { diff --git a/src/qml/patchmanagermodel.cpp b/src/qml/patchmanagermodel.cpp index d8e60570f..95272c8c6 100644 --- a/src/qml/patchmanagermodel.cpp +++ b/src/qml/patchmanagermodel.cpp @@ -58,17 +58,17 @@ PatchManagerModel::PatchManagerModel(QObject *parent) \li Qt Role \li QML Role Name \row - \li \l{https://doc.qt.io/qt-5/qt.html#ItemDataRole-enum}{Qt::DisplayRole} - \li name + \li {Qt::DisplayRole} + \li \c name \row - \li \l{https://doc.qt.io/qt-5/qt.html#ItemDataRole-enum}{Qt::DecorationRole} - \li section + \li {Qt::DecorationRole} + \li \c section \row - \li \l{https://doc.qt.io/qt-5/qt.html#ItemDataRole-enum}{Qt::EditRole} - \li patchObject + \li {Qt::EditRole} + \li \c patchObject \endtable - \sa {https://doc.qt.io/qt-5/qabstractitemmodel.html}{Qt::QAbstractItemModel} + \sa QAbstractItemModel */ PatchManagerModel::PatchManagerModel(const QList &data, QObject *parent) : QAbstractListModel(parent) diff --git a/src/qml/plugin.cpp b/src/qml/plugin.cpp index 327ed7d0d..45172ead8 100644 --- a/src/qml/plugin.cpp +++ b/src/qml/plugin.cpp @@ -76,7 +76,7 @@ static QObject *patchmanagertransalator_singleton(QQmlEngine *engine, QJSEngine This property holds the Operating System version. This is used for version checking. */ /*! \qmlproperty bool PatchManager::patchDevelMode - \sa {Patchmanager Configuration Files}, inifile + \sa {Patchmanager Configuration Files}, {inifile}{\c{/etc/patchmanager2.conf}} */ /*! \qmlproperty string PatchManager::patchmanagerVersion This property holds our own version @@ -90,11 +90,11 @@ static QObject *patchmanagertransalator_singleton(QQmlEngine *engine, QJSEngine */ /*! \qmlproperty var PatchManager::updates Map of internal names and metadata of patches which can be updated. - \sa PatchManagerObject::getUpdates, dbus-sys + \sa PatchManagerObject::getUpdates, {dbus-sys}{D-Bus System Service} */ /*! \qmlproperty var PatchManager::updatesNames List of display names of patches which can be updated. - \sa PatchManagerObject::getUpdates, dbus-sys + \sa PatchManagerObject::getUpdates, {dbus-sys}{D-Bus System Service} */ /***** PatchManagerTranslator ******/ diff --git a/src/qml/qmlplugin.qdoc b/src/qml/qmlplugin.qdoc index 155d9edfa..4043df1db 100644 --- a/src/qml/qmlplugin.qdoc +++ b/src/qml/qmlplugin.qdoc @@ -5,11 +5,10 @@ \section1 Overview - The QML Plugin makes up the main Patchmanager GUI Application. + The QML Plugin provides the main Patchmanager GUI Application elements. + It is designed to be invoked through the \l {Patchmanager Documentation: Settings Plugin}{Settings Plugin}. - Jolla Settings loads PatchManagerPage from the QML Plugin. - - It is a both a front-end to the Daemon and a Patch management application. + It serves as a both a front-end to the Daemon, and a Patch management application. It allows to: diff --git a/src/qml/webpatchesmodel.cpp b/src/qml/webpatchesmodel.cpp index 270ad2613..a074cfb2b 100644 --- a/src/qml/webpatchesmodel.cpp +++ b/src/qml/webpatchesmodel.cpp @@ -50,31 +50,31 @@ \li QML Role Name \row \li {Qt::UserRole} - \li description + \li \c description \row \li {Qt::UserRole} - \li last_updated + \li \c last_updated \row \li {Qt::UserRole} - \li name + \li \c name \row \li {Qt::UserRole} - \li display_name + \li \c display_name \row \li {Qt::UserRole} - \li category + \li \c category \row \li {Qt::UserRole} - \li author + \li \c author \row \li {Qt::UserRole} - \li rating + \li \c rating \row \li {Qt::UserRole} - \li total_activations + \li \c total_activations \endtable - \sa {https://doc.qt.io/qt-5/qabstractitemmodel.html}{Qt::QAbstractItemModel} + \sa QAbstractItemModel */ /*! \fn virtual QHash WebPatchesModel::roleNames() const Returns the model's role names. @@ -118,10 +118,10 @@ WebPatchesModel::~WebPatchesModel() */ /*! \property WebPatchesModel::queryParams - Query parameters + Parameters used to perform the web catalog query. */ /*! \qmlproperty var WebPatchesModel::queryParams - Query parameters + Parameters used to perform the web catalog query. */ /*! \qmlsignal WebPatchesModel::queryParamsChanged() Emitted when query parameters change @@ -172,7 +172,7 @@ bool compareStrings(const QString &a, const QString &b) Retrieves the list of patches from the \l {Patchmanager Web Catalog}{Web Catalog}, and populates the model with its contents, sorting them if necessary. - \sa setSorted() + \sa setSorted(), PatchManagerObject::downloadCatalog() */ void WebPatchesModel::componentComplete() { diff --git a/src/user.qdoc b/src/user.qdoc new file mode 100644 index 000000000..99930da11 --- /dev/null +++ b/src/user.qdoc @@ -0,0 +1,51 @@ +/*! + + \page user.html overview + \indexpage Patchmanager Documentation + + \title Patchmanager for SailfishOS + + Patchmanager is a tool for transparently modifying installed files by the + patch utility and for managing the special patch files ("Patches") for doing + so. + + Since version 3.0, Patchmanager does not modify original files on mass + storage, it merely alters their content when they are loaded into RAM to be + executed. + + \section1 Launching + + Patchmanager does not install an application icon on the launcher, but + creates a new entry in SailfishOS' Settings app. + + \section1 Installing + + To install a recent Patchmanager the SailfishOS:Chum community repository can + be used, which is easily accessed with the SailfishOS:Chum GUI application, + which in turn can be installed via the \l{SailfishOS:Chum GUI Installer} + + Alternatively Patchmanager can be installed from its \l{OpenRepos repository} + using Storeman, which can be installed via the \l{Storeman Installer}. + + While these two sources can also be used to manually download and install + Patchmanager, you may alternatively obtain Patchmanager RPMs from its + \l{Releases page} at GitHub. + + \note The Patchmanager's OpenRepos repository and GitHub releases page also + offer the final releases of Patchmanager 3.0 for SailfishOS < 3.4.0 and + Patchmanager 2.3.3 for SailfishOS < 2.2.x. + + \section1 Getting Patches + + Modern Patches for Patchmanager 3 are provided via the \l{Web Catalog Site} + while older Patches were provided as + \l{Patch RPMs at OpenRepos} + and some of them are still maintained. + + Mind that many Patches were first released at OpenRepos but later migrated to + the Web Catalog: For these you will find outdated RPMs, hence always search + in the Web Catalog first. + + For other, more advanced methods of installing patches, see \l{patchdevinstall}{Patch Installation} + +*/