{"id":21528522,"url":"https://github.com/fibercrypto/simpleinstallerframework","last_synced_at":"2025-03-17T18:45:27.015Z","repository":{"id":68136252,"uuid":"214939301","full_name":"fibercrypto/SimpleInstallerFramework","owner":"fibercrypto","description":"A Simple, easy-to-use, highly customizable Installer Framework built with Qt","archived":false,"fork":false,"pushed_at":"2019-11-05T19:09:02.000Z","size":53,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-01-24T06:11:19.420Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fibercrypto.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.GPLv3","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-14T03:24:07.000Z","updated_at":"2019-11-05T19:09:04.000Z","dependencies_parsed_at":null,"dependency_job_id":"7362868d-5898-4e13-99c5-128906551ac3","html_url":"https://github.com/fibercrypto/SimpleInstallerFramework","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fibercrypto%2FSimpleInstallerFramework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fibercrypto%2FSimpleInstallerFramework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fibercrypto%2FSimpleInstallerFramework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fibercrypto%2FSimpleInstallerFramework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fibercrypto","download_url":"https://codeload.github.com/fibercrypto/SimpleInstallerFramework/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244092029,"owners_count":20396724,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-24T01:53:33.127Z","updated_at":"2025-03-17T18:45:27.010Z","avatar_url":"https://github.com/fibercrypto.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SIF: Simple Installer Framework\n\n*A Simple, easy-to-use, highly customizable Installer Framework built with Qt*\n\nCopyright © 2019 Simelo.Tech\n\n*This project is under the GPLv3 license*\n\n---------------------------------------------\n\n\n## Description\n\n**Simple Installer Framework** (**SIF** for short) is an alternative to Qt Installer Framework. It is intended to be used as a statically compiled library. It is a non-GUI library, what means that you must provide the graphics by using either `Qt Widgets` or `Qt Quick`.\n\n**SIF** features:\n\n* Asynchronous fetching and extraction operations\n* Make your own custom UI\n* Designed to work well with both Qt Widgets and Qt Quick\n* Logic separated from the view\n\n\n## Requirements\n\nThe framework uses Qt. Any Qt 5 version should work, but I always recommend having the latest LTS release.\n\n\n## How to add it to my project?\n\nYou can compile **SIF** from Qt Creator or running `qmake` then `make` (or equivalent) in the root of the project, and link the resulting static library to your project. For example, if you have the library `SimpleInstallerFramework.a` and its header file copied in `lib/SimpleInstallerFramework/` inside the root of your project, then you can link to it by simply adding to your `.pro` file:\n\n```\nLIBS += -L$$PWD/lib/SimpleInstallerFramework/ -lSimpleInstallerFramework\n```\n\nOtherwise, you can add the class `Installer` (i.e. the files `installer.h` and `installer.cpp`) to your project.\n\n\n## How to interact with it?\n\nFirst, set the organization and the application name:\n\n```c++\n    QCoreApplication::setOrganizationName(\"MyOrg\");\n    QCoreApplication::setApplicationName(\"MyApp\");\n```\n\nYou can also set the organization domain and the application version.\n\nSecond, the installer search for files to extract in the following resource locations:\n\n* *Windows*: `\":/windows/data\"`\n* *macOS*: `\":/macos/data\"`\n* *Unix*: `\":/unix/data\"`\n\nSo you must **ensure that such paths can be found**. As a tip, the following folder structure is followed in our examples:\n\n```\nroot/\n|\n|――resources/\n|  |\n|  |――windows/\n|  |  |\n|  |  |――data/\n|  |\n|  |――macos/\n|  |  |\n|  |  |――data/\n|  |\n|  |――unix/\n|  |  |\n|  |  |――data/\n```\n\n... and then, in each operating system folder, we create a `data.qrc` Qt resource file with the prefix `/os_name` and add it to the project (`.pro`) file.\n\n**Simple Installer Framework** consists in just one class: `Installer`. Its properties, methods and signals are explained bellow.\n\n\n### Properties:\n\n* `installationPath: QString`\n\n  Access descriptors: `getInstallationPath()` and `setInstallationPath()`\n\n  Notifier signal: `installationPathChanged(const QString \u0026)`\n    \n    This is the path where you want to install your software. By default, it chooses the appropriate path for you Operating System:\n\n    - *Windows*:\n      - `C:/Program files/Organization/ApplicationName` (if OS x86 and app x86 or OS x64 and app x64) or,\n      - `C:/Program files (x86)/Organization/ApplicationName` (if OS x64 and app x86)\n    - *macOS*:\n      - `/Applications`\n    - *Unix*:\n      - `~/Applications`\n\n    Observe that *Windows* and *macOS* default installation paths are not writable without elevated privilegies.  \n    *Unix* refers to Linux or any other Unix-based OS except Darwin systems.\n\n    Every time this property is set, it triggers an update of the property `installationPathIsValid`, so you must check the validity of the new path.\n\n* `[read-only] installationPathIsValid: bool`\n\n  Access descriptors: `getInstallationPathIsValid()`\n\n  Notifier signal: `installationPathIsValidChanged(bool)`\n\n    This property is updated when the `installationPath` changes. It is `true` when the installation path is valid, and `false` otherwise. You must check the state of this property when you set the installation path:\n\n    ```c++\n    // We'll assume we're on Windows x64 and app x64\n    Installer inst; // installationPath = \"C:/Program files/MyOrg/MyApp\"\n    QString newPath = QString(\"D:/My Games/\") + QCoreApplication::setOrganizationName() + \"/\" + QCoreApplication::setApplicationName();\n    inst.setInstallationPath(newPath);\n    if (inst.getInstallationPathIsValid()) {\n        // do the thing\n    } else {\n        // show a warning, ask again, etc...\n    }\n    ```\n\n* `[read-only] installationPathError: Installer::InstallationPathError`\n\n  Access descriptors: `getInstallationPathError()`\n\n  Notifier signal: `installationPathErrorChanged(Installer::InstallationPathError)`\n\n    The error code of the last operation that failed. You should use `installationPathErrorString` to show human-readable error messages. Can be one of:\n\n    InstallationPathError    | Description\n    ------------------------ | --------------------\n    `NoPathError`            | No error, all is Ok\n    `PathNotSpecified`       | No path specified\n    `PathIsAFile`            | Path is a file\n    `PathIsNotAbsolute`      | Path is not absolute\n    `PathIsNotEmpty`         | Path is not empty\n\n* `[read-only] installationPathErrorString: QString`\n\n  Access descriptors: `getInstallationPathErrorString()`\n\n  Notifier signal: `installationPathErrorStringChanged(const QString \u0026)`\n\n    Human-readable description of the error code represented by `installationPathError`.\n\n* `[read-only] installerStatus: Installer::InstallerStatus`\n\n  Access descriptors: `getInstallerStatus()`\n\n  Notifier signal: `installerStatusChanged(Installer::InstallerStatus)`\n\n    The status of the installer. Can be one of:\n\n    InstallerInstallerStatus | Description\n    ------------------------ | ---------------\n    `Idle`                   | The installer is idle (i.e., in stand-by)\n    `FetchingFiles`          | Searching for files to install\n    `ExtractingPackages`     | Extracting files to the selected installation path\n    `ExtractionFinished`     | The extraction finished successfully\n    `ExtractionCanceled`     | The extraction was canceled\n    `RevertingInstallation`  | The installation has been canceled and it's being reverted\n    `ErrorOccurred`          | An error occurred\n\n* `[read-only] totalSize: long long int`\n\n  Access descriptors: `getTotalSize()`\n\n  Notifier signal: `totalSizeChanged(long long int)`\n\n    The total size of all files that are going to be installed.\n\n* `[const] [read-only] currentOS: QOperatingSystemVersion::OSType`\n\n  Access descriptors: `getCurrentOS()`\n\n    The version of the operating system the application is running on. This property exists for convenience with Qt Quick UIs, because from C++ you can always use `QOperatingSystemVersion::currentType()` directly to get the same result.\n\n\n### Methods:\n\n* `Installer::Installer(QObject *parent = nullptr)`\n\n    Constructs a new instance of an `Installer`.\n\n* `[virtual] Installer::~Installer()`\n\n    Destructs an `Installer` instance.\n\n* `QString Installer::getDataPath()`\n\n    Returns the path where the installer search for files to install, by default in the resource path `\":/os_name/data\"`. For example, if you're on *Windows*, it search in `\":/windows/data\"`, if you're on *macOS*, it search in `\":/macos/data\"` and under a *Unix* (not *Darwin*) system it search in `\":/unix/data\"`.\n\n* `Installer::setDataPath(const QString \u0026newDataPath)`\n\n    As explained earlier, by default, **SIF** search for files to install in the resource path `\":/os_name/data\"`. It is strongly recommended to **not** change the default path because it wipes out the cross-platform behavior, but you can still call this function if you really want to do so.\n\n* `[slot] void Installer::extractAll()`\n\n    Calling this method starts asynchronous fetching and extraction of all files. After this function is called, the `installerStatus` property is set to `InstallerStatus::FetchingFiles`. If any error occur, the `installerStatus` is set to `InstallerStatus::ErrorOccurred`. If the operation completes successfully, `installerStatus` is set to `InstallerStatus::ExtractionFinished`.\n\n* `[slot] void Installer::requestProgress()`\n\n    After calling this method, the signal `progressReported()` will be emitted with the progress of the extraction/reversion. A handle must then capture the signal and react accordingly. GUI applications should call this function periodically (i.e. using a `QTimer` or `Timer`) while the status of the installer is `InstallerInstallerStatus::ExtractingPackages` or `InstallerInstallerStatus::RevertingInstallation`.\n\n* `[slot] void Installer::cancel()`\n\n    Call this function to cancel the extraction process. The installer will then enter the `InstallerInstallerStatus::RevertingInstallation` status and start deleting the installed files. After that, the `installerStatus` property will be set to `InstallerInstallerStatus::ExtractionCanceled`.\n\n* `[slot] bool Installer::addFileToExtract(const QString \u0026from, const QString \u0026to)`\n\n    Call this function to add more files to the extraction list. During installation, the file will be copied from the filepath pointed by `from` to the filepath pointed by `to`.  \n    This is useful to install optional components, for example, you may want to optionally install the source code of your application in a zipped folder or a tarball. Another good use is to reduce the installer size if the same file must be copied to multiple locations, because you can include the file only once in resources, and add various destinations.  \n    This function must be called **before** the fetching or extraction starts, i.e. when the installer is in the `Idle` status.  \n    The total size of the files added with this function is also added to the total size of the installation.  \n    Returns `true` if the file pointed by `from` exists, `false` otherwise.\n\n* `[slot] bool Installer::addDesktopShortcut(const QString \u0026linkName = QCoreApplication::applicationName(), const QString \u0026executableEntryFilePath = QString())`\n\n    Call this function to add a shortcut file named `linkName` in the desktop. The links points to `executableEntryFilePath`. By default, `linkName` is the application's name, and `executableEntryFilePath` is empty, which means that it points to the appropriate files depending of the operating system where the installer is running:\n\n    OS      | Executable entry file path\n    ------- | ------------------------------------------------------------------------\n    Windows | `\u003cInstallation path\u003e/\u003cApplication Name\u003e.exe`\n    macOS   | `\u003cInstallation path\u003e/\u003cApplication Name\u003e.app`\n    Unix    | `\u003cApplications Location\u003e/\u003cApplication Name\u003e.desktop`\n\n    We strongly recommend to not specify a value to `executableEntryFilePath`, unless the name of the executable do not match the name of the application as set with `QCoreApplication::setApplicationName()`.  \n    On Unix, a desktop entry must be previously created with `addDesktopEntry` for this function to work.  \n    Returns `true` if the shortcut is created, `false` otherwise.\n\n* `[slot] bool Installer::addWindowsStartMenuEntry(const QString \u0026linkName = QCoreApplication::applicationName(), const QString \u0026filePath = QString())`\n\n    Call this function to add an entry named `linkName` (the application's name by default) that points to `filePath` to the Windows Start Menu. If the `filePath` is not specified, it defaults to `\u003cInstallation path\u003e/\u003cApplication Name\u003e.exe`. Returns `true` on success, `false` otherwise. This function does nothing on non-Windows operating systems and returns `false`.\n\n* `[slot] bool Installer::addDesktopEntry(const QString \u0026name = QCoreApplication::applicationName())`\n\n    Call this function to add a desktop entry named `name` (the application's name by default).  \n    The installer search for desktop entries in `:/os_name/desktop_entries`. For example, on Linux, a desktop entry named `My App` should be in `:/linux/desktop_entries/My App.desktop`.  \n    If an entry with name `name` is found, it is copied to an appropriate location (currently `\u003cApplications Location\u003e`, i.e. `~/.local/share/applications`) and returns `true`. If the entry is not found or cannot be copied, returns `false`.\n    This function does nothing on Windows or macOS operating systems and returns `false`.\n\n* `[slot] void Installer::addWindowsControlPanelUninstallerEntry(const QString \u0026applicationDescription, const QString \u0026applicationFilePath = QString(), const QString \u0026uninstallerFilePath = QString(), const QString \u0026modifierApplicationFilePath = QString(), const QString \u0026repairerApplicationFilePath = QString(), const QString \u0026moreInfoUrl = QString())`\n\n    Call this function to add an entry (usually for an uninstaller) in the Control Panel of a Windows operating system. A brief description of the application must be provided in `applicationDescription`. The rest of arguments are optional and will be explained bellow:\n\n    * `applicationFilePath` is the application which icon will be shown in the entry, and if not specified, defaults to `\u003cInstallation path\u003e/\u003cApplication Name\u003e.exe`.\n    * `uninstallerFilePath` is the path to the executable that will be used as uninstaller. If not specified, defaults to `\u003cInstallation path\u003e/uninstall.exe`.\n    * `modifierApplicationFilePath` is the path to the executable that will be used to modify the existing installation, usually an updater. By default, it's empty, which means that no application is provided.\n    * `repairerApplicationFilePath` is the path to the executable that will be used to repair the existing installation. By default, it's empty, which means that no application is provided.\n    * `moreInfoUrl` is an URL that will be used to obtain more information about the application. Empty by default.\n\n    This function does nothing on non-Windows operating systems.\n\n\n### Signals:\n\n* `[signal] fetchingStarted()`\n    \n    This signal is emitted just before the installer starts searching files to extract.\n\n* `[signal] extractionStarted()`\n    \n    This signal is emitted just before the installer starts extracting files.\n\n* `[signal] progressReported(double progress)`\n    \n    This signal is emitted after `requestProgress()` is called. `progress` is the value of the progress of extraction/reversion.\n\n* `[signal] extractionFinished()`\n    \n    This signal is emitted just after the installer finished extracting files.\n\n* `[signal] reversionFinished()`\n    \n    This signal is emitted just after the installer finished deleting the installed files.\n\n* `[signal] extractionError(QFile::FileError errorCode, const QString \u0026errorString)`\n\n    This signal is emitted when an error occur while extracting files. `errorCode` is the code of the error, and `errorString` is its description.\n\n* `[signal] void reversionFailed()`\n\n    This signal is emitted if occur an error during reversion.\n\n\n## TODO\n\nThere's my *TODO* list:\n\n* **All platforms**\n    * Allow system-wide installation\n\n\n## Licensing\n\nThis project is under the GPLv3 license (see [http://fsf.org/](http://fsf.org/) for more information).\n\n\n## Contact information\n\ne-mail: [contact@fibercryp.to](mailto:contact@fibercryp.to)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffibercrypto%2Fsimpleinstallerframework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffibercrypto%2Fsimpleinstallerframework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffibercrypto%2Fsimpleinstallerframework/lists"}