{"id":18365779,"url":"https://github.com/martchus/cpp-utilities","last_synced_at":"2025-04-09T17:26:24.381Z","repository":{"id":42613683,"uuid":"34401443","full_name":"Martchus/cpp-utilities","owner":"Martchus","description":"Common C++ classes and routines used by my applications such as argument parser, IO and conversion utilities","archived":false,"fork":false,"pushed_at":"2025-03-13T16:00:08.000Z","size":2258,"stargazers_count":54,"open_issues_count":0,"forks_count":18,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-02T15:08:57.035Z","etag":null,"topics":["argument-parser","cmake","conversion-utilities","cpp-library","cppunit","hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Martchus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2015-04-22T16:20:07.000Z","updated_at":"2025-03-13T16:00:12.000Z","dependencies_parsed_at":"2023-11-25T23:23:42.072Z","dependency_job_id":"943fae8b-6cc5-4911-84ab-a34848997401","html_url":"https://github.com/Martchus/cpp-utilities","commit_stats":{"total_commits":1261,"total_committers":5,"mean_commits":252.2,"dds":0.007930214115781098,"last_synced_commit":"4d86993942aed207941b33df0651fdca9b86585c"},"previous_names":[],"tags_count":88,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Martchus%2Fcpp-utilities","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Martchus%2Fcpp-utilities/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Martchus%2Fcpp-utilities/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Martchus%2Fcpp-utilities/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Martchus","download_url":"https://codeload.github.com/Martchus/cpp-utilities/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248076237,"owners_count":21043733,"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":["argument-parser","cmake","conversion-utilities","cpp-library","cppunit","hacktoberfest"],"created_at":"2024-11-05T23:14:31.129Z","updated_at":"2025-04-09T17:26:24.359Z","avatar_url":"https://github.com/Martchus.png","language":"C++","readme":"# C++ utilities\nUseful C++ classes and routines such as argument parser, IO and conversion utilities.\n\n## Features\nThe library contains helpers for:\n\n* parsing command-line arguments and providing Bash completion\n    - supports nested arguments\n    - supports operations (no `--` or `-` prefix, eg. `git status`)\n    - can check for invalid or uncombinable arguments\n    - can print help automatically\n    - provides automatic Bash completion for argument names\n    - allows customizing Bash completion for argument values\n* dealing with dates and times\n* conversion of primitive data types to byte-buffers and vice versa (litte-endian and big-endian)\n* common string conversions/operations, eg.\n    - character set conversions via iconv\n    - split, join, find and replace\n    - conversion from number to string and vice verca\n    - encoding/decoding base-64\n    - building string without multiple heap allocations (\"string builder\")\n* using standard IO streams\n    - reading/writing primitive data types of various sizes (little-endian and big-endian)\n    - reading/writing terminated strings and size-prefixed strings\n    - reading/writing INI files\n    - reading bitwise (from a buffer; not using standard IO streams)\n    - writing formatted output using ANSI escape sequences\n    - instantiating a standard IO stream from a native file descriptor to support UTF-8 encoded\n      file paths under Windows and Android's `content://` URLs\n* using SFINAE by providing additional traits, eg. for checking whether a type is iterable\n* testing with *CppUnit*\n    - finding testfiles and make working copies of testfiles\n    - assert standard output\n    - various helper\n* building with CMake by providing some modules and templates\n\nBesides, the library provides a few useful algorithms and data structures:\n\n* min(), max() for any number of arguments\n* digitsum(), factorial(), powerModulo(), inverseModulo(), orderModulo()\n* Damerau–Levenshtein distance\n* *N*-dimensional array\n\n## API/ABI stability\nThe following counts for `c++utilities` and my other libraries unless stated otherwise:\n\n* Different major versions are incompatible (API- and ABI-wise). Different major versions can be\n  installed within the same prefix using the CMake variable `CONFIGURATION_NAME` (see documentation\n  about build variables mentioned below).\n* Minor versions are backwards compatible (API- and ABI-wise) to previous ones within the same major\n  version.\n* Patch versions are interchangeable (API- and ABI-wise) within the same major/minor version.\n* Some functions or classes are experimental. They might be modified in an incompatible way or even\n  removed in the next minor or patch release.\n\n## Build instructions\nThese build instructions apply to `c++utilities` but also to my other projects using it.\n\n### Requirements\n#### Build-only dependencies\n* C++ compiler supporting C++17, tested with\n    - g++ to compile for GNU/Linux and Windows\n    - clang++ to compile for GNU/Linux and Android\n* CMake (at least 3.17.0) and Ninja or GNU Make\n* cppunit for unit tests (optional)\n* Doxygen for API documentation (optional)\n* Graphviz for diagrams in the API documentation (optional)\n* clang-format and cmake-format for tidying (optional)\n* llvm-profdata, llvm-cov and cppunit for source-based code coverage analysis (optional)\n* [appstreamcli](https://www.freedesktop.org/wiki/Distributions/AppStream/) for validation\n  of generated AppStream files (optional)\n\n#### Runtime dependencies\n* The `c++utilities` library itself only needs\n    * C++ standard library supporting C++17, tested with\n        - libstdc++ under GNU/Linux and Windows\n        - libc++ under GNU/Linux and Android\n    * glibc with iconv support or standalone iconv library\n    * libstdc++ or Boost.Iostreams for `NativeFileStream` (optional, use `USE_NATIVE_FILE_BUFFER=OFF` to disable)\n    * Boost.Process for `execApp()` test helper under Windows (optional, use `USE_BOOST_PROCESS=OFF` to disable)\n    * libarchive (optional, for archiving utilities only, use `USE_LIBARCHIVE=ON` to enable)\n* My other projects have further dependencies such as Qt. Checkout the README of these\n  projects for further details.\n\n### How to build\nGeneric example using Ninja:\n```\ncmake -G Ninja \\\n      -S \"path/to/source/directory\" \\\n      -B \"path/to/build/directory\" \\\n      -DCMAKE_BUILD_TYPE=Release \\\n      -DCMAKE_INSTALL_PREFIX=\"/final/install/location\"\n# build the binaries\ncmake --build \"path/to/build/directory\"\n# format source files (optional, must be enabled via CLANG_FORMAT_ENABLED)\ncmake --build \"path/to/build/directory\" --target tidy\n# build and run tests (optional)\ncmake --build \"path/to/build/directory\" --target check\n# build and run tests measuring test coverage (optional, must be enabled via CLANG_SOURCE_BASED_COVERAGE_ENABLED)\ncmake --build \"path/to/build/directory\" --target coverage\n# build API documentation (optional)\ncmake --build \"path/to/build/directory\" --target apidoc\n# install binaries, headers and additional files\nDESTDIR=\"/temporary/install/location\" \\\n  cmake --install \"path/to/build/directory\"\n```\n\nThis example is rather generic. For a development build I recommended using CMakePresets as\ndocumented in the \"[CMake presets](#cmake-presets)\" section below. It also contains more concrete\ninstructions for building on Windows.\n\n#### General notes\n* By default the build system will *build* static libs. To *build* shared libraries *instead*, set\n  `BUILD_SHARED_LIBS=ON`.\n* By default the build system will prefer *linking against* shared libraries. To force *linking against*\n  static libraries set `STATIC_LINKAGE=ON`. However, this will only affect applications. To force linking\n  statically when building shared libraries set `STATIC_LIBRARY_LINKAGE=ON`.\n* If thread local storage is not supported by your compiler/platform (might be the case on MacOS), you can\n  disable making use of it via `ENABLE_THREAD_LOCAL=OFF`.\n* To disable use of `std::filesystem`, set `USE_STANDARD_FILESYSTEM=OFF`. Note that the Bash completion will\n  not be able to suggest files and directories and the archiving utilities cannot be enabled with\n  `USE_STANDARD_FILESYSTEM=OFF`. Note that this will only help with `c++utilities` itself. My other projects\n  might use `std::filesystem` unconditionally.\n* To disable `NativeFileStream` (and make it just a regular `std::fstream`), set `USE_NATIVE_FILE_BUFFER=OFF`.\n  This can be safely done when building `c++utilities` *only* for applications that don't use `std::fstream`\n  anyway such as Syncthing Tray. Then disabling makes sense to avoid depending on a `libstdc++` vendor\n  extension or Boost.Iostreams. Otherwise disabling is not recommended as it will lead to the following\n  limitations:\n    * Error messages when opening files will not contain the cause of the error.\n    * Opening files under paths with non-ASCII characters will not work on Windows.\n    * Password Manager will not compile for Android.\n* The Qt-based applications support bundling icon themes by specifying e.g.\n  `BUILTIN_ICON_THEMES=breeze;breeze-dark`.\n    * This variable must be set when building the application (not when building any of the libraries).\n    * The specified icon themes need to be installed in the usual location. Otherwise, use e.g.\n      `BUILTIN_ICON_THEMES_SEARCH_PATH=D:/programming/misc/breeze-icons/usr/share/icons` to specify the\n      search path.\n* For more details, checkout the documentation about build variables (in the\n  [directory `doc`](https://github.com/Martchus/cpp-utilities/blob/master/doc/buildvariables.md) and\n  in the Doxygen version accessible under \"Related Pages\").\n* The repository [PKGBUILDs](https://github.com/Martchus/PKGBUILDs) contains build scripts for GNU/Linux,\n  Android, Windows and MacOS X in form of Arch Linux packages using `ninja`. These scripts can be used as an\n  example also when building under/for other platforms.\n\n#### Windows-specific notes\n* To create application icons the tool `ffmpeg`/`avconv` is required.\n* Windows builds are mainly conducted using mingw-w64/GCC/LLVM so using them is recommended. Building with\n  MSVC should be possible as well but it is not as well tested.\n* When using `BUILTIN_ICON_THEMES`, the icon theme still needs to be installed as if it was installed on a\n  GNU/Linux system. So simply grab e.g. the Arch Linux package `breeze-icons` and extract it somewhere. Do\n  *not* use the package from MSYS2 or what comes with builds from KDE's binary factory.\n\n#### MacOS-specific notes\n* To create application icons the tool `png2icns` is required.\n* Building for MacOS X under GNU/Linux is possible using [osxcross](https://github.com/tpoechtrager/osxcross).\n* MacOS X builds are not tested regularly but should generally work (maybe with minor tweaks necassary).\n* There is a [Homebrew formula](https://gist.github.com/rakkesh/0b13b8fca5dd1d57d98537ef1dd2e0dd) to\n  build Tag Editor (without GUI).\n* There are [MacPorts packages](https://www.macports.org/ports.php?by=name\u0026substr=syncthingtray-devel)\n  to build Syncthing Tray.\n\n#### Development builds\nDuring development I find it useful to build all required projects (for instance c++utilities, qtutilities,\ntagparser and tageditor) as one big project.\n\nThis can be easily achieved by using CMake's `add_subdirectory()` function. For project files see the repository\n[subdirs](https://github.com/Martchus/subdirs). For an example, see\n[build instructions for Syncthing Tray](https://github.com/Martchus/syncthingtray#building-this-straight) or\n[build instructions for Tag Editor](https://github.com/Martchus/tageditor#building-this-straight). The `subdirs`\nrepository also contains the script `sync-all.sh` to clone all possibly relevant repositories and keep them\nup-to-date later on.\n\nFor a debug build, use `-DCMAKE_BUILD_TYPE=Debug`. To tweak various settings (e.g. warnings) for development,\nuse `-DENABLE_DEVEL_DEFAULTS=ON`.\n\n#### Using Visual Studio Code\nThe following sections document useful extensions. Most of them require the \"vscode marketplace\" which might\nnot be available in all distributions of Visual Studio Code (e.g. when using the Arch Linux `code` package one\nneeds to install the `code-marketplace` package in addition).\n\nNote that most of this has only been tested under GNU/Linux so far.\n\n##### clangd\nTo use `clangd` via Visual Studio Code install the\n[extension](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) and\nadd `-DCMAKE_EXPORT_COMPILE_COMMANDS=1` to the CMake arguments. Then link the `compile_commands.json` file\nfrom the build directory into the source directory. When using the `subdirs` project you can create a symlink\nto the subdirs project in the individual projects (e.g.\n`compile_commands.json -\u003e ../subdirs/syncthingtray/compile_commands.json`) and a symlink to the actual build\ndirectory in the subdirs project (e.g.\n`compile_commands.json -\u003e /…/build/presets/syncthingtray/arch-android-x86_64/compile_commands.json`).\n\n##### Building and debugging\nInstall the extension [C/C++](https://github.com/microsoft/vscode-cpptools) from Microsoft. To avoid having\nto create manual build tasks and launch configurations, install the\n[CMake extension](https://github.com/microsoft/vscode-cmake-tools) from Microsoft.\n\nThe extension [Native Debug](https://github.com/WebFreak001/code-debug) works as well.\n\nPresumably [CodeLLDB](https://github.com/vadimcn/codelldb) (which also supports Rust) would work as well\nbut I haven't tested that yet.\n\nThe repository [subdirs](https://github.com/Martchus/subdirs) contains example configuration covering\nSyncthing Tray and a few other projects. It configures many tasks and launcher configurations for building and\nmore manually. Not all projects and targets are covered, though. So it makes most sense to rely on the CMake\nextension to configure and build the various projects (using presets, see section below). A launcher config to \nlaunch the active/selected CMake target exists.\n\n##### Qt\nTo work on my C++ projects that use Qt it might be useful to install their\n[extension pack](https://marketplace.visualstudio.com/items?itemName=TheQtCompany.qt).\nCompile the code with `-DQT_QML_GENERATE_QMLLS_INI=ON` for the QML language server to work.\n\nThe repository [subdirs](https://github.com/Martchus/subdirs) also contains a GDB init script and\nconfiguration for the extension [C/C++](https://github.com/microsoft/vscode-cpptools) to make pretty printing\nof Qt data types work in GDB using the printers from KDevelop.\n\n#### CMake presets\nThere are some generic [presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html) available.\n\nUse `cmake --list-presets` to list all presets. Note that some presets\n\n* are specific to certain Arch Linux packaging found in the AUR and my PKGBUILDs repository. Those presets\n  start with `arch-`.\n* are specific to certain build setups/toolchains under Windows. Those presets start with `win-`.\n\nAll `cmake` commands need to be executed within the source directory. Builds will be created within a\nsub-directory of the path specified via the environment variable `BUILD_DIR`.\n\nThe most useful presets for development are likely `devel`, `devel-qt6` and `debug`. Note that the `devel`\npreset (and all presets inheriting from it) use `ccache` which therefore needs to be installed.\n\nHere is a simple example to build with the `devel-qt6` preset:\n```\nexport BUILD_DIR=$HOME/builds                    # set build directory via environment variable\ncmake --preset devel-qt6                         # configure build\ncmake --build --preset devel-qt6 -- -v           # conduct build\ncmake --build --preset devel-qt6 --target check  # run tests\ncmake --build --preset devel-qt6 --target tidy   # apply formatting\n```\n\nNote that these presets are supposed to cover all of my projects (so some of them aren't really making a\ndifference when just building `c++utilities` itself). To use presets in other projects, simply symlink the\nfile `CMakePresets.json` into the source directory of those projects. This is also done by the \"subdirs\"\nprojects mentioned in the previous section.\n\nAfter invoking the configuration via the command-line, you can also open the project in Qt Creator and import\nit as an existing build (instead of adding a new build configuration).\n\n##### Remarks about special presets\nThe presets starting with `arch-` are for use under Arch Linux (or an Arch Linux container). Do *not* use them\nunless you know what you are doing. When creating a normal build under Arch Linux it is recommended to still\nuse e.g. `devel-qt6`.\n\nUse the preset `arch-android` to cross-compile for Android using `android-*` packages (see next section for\ndetails).\n\nUse the presets starting with `arch-*-w64-mingw32` to cross-compile for Windows (i686/x86_64) using\n`mingw-w64` packages. Use the presets starting with `arch-mingw-w64-clang` to cross compile for Windows\n(aarch64) using `mingw-w64-clang-aarch64` packages.\n\nUse the presets starting with `arch-static-compat-devel` to create a self-contained executable that is also\nusable under older GNU/Linux distributions using `static-compat` packages (see\n[PKGBUILDs](https://github.com/Martchus/PKGBUILDs#static-gnulinux-libraries) for details about it).\n\n##### Remarks about building for Android\nNote that this might not be necassary; one can usually develop and test most parts of the mobile UI of e.g.\nSyncthing Tray natively on the development host thanks to the cross-platform nature of Qt.\n\nI recommended building for Android under Arch Linux (or an Arch Linux container, see last paragraphs of this\nsection) using `android-*` packages found on the AUR and my\n[binary repository](https://martchus.dyn.f3l.de/repo/arch/ownstuff). The commands in this section assume this\nkind of build environment. For building on Windows, checkout the section\n\"[Building under Windows for Android](#building-under-windows-for-android)\" below.\n\n---\n\nFirst, create a key for signing the APK (always required; otherwise the APK file won't install):\n```\n# set variables for creating a keystore and allowing androiddeployqt to find it\nexport QT_ANDROID_KEYSTORE_PATH=/path/to/keystore-dir/$USER-devel QT_ANDROID_KEYSTORE_ALIAS=$USER-devel QT_ANDROID_KEYSTORE_STORE_PASS=$USER-devel QT_ANDROID_KEYSTORE_KEY_PASS=$USER-devel\n\n# create keystore (do this only once)\nmkdir -p \"${QT_ANDROID_KEYSTORE_PATH%/*}\"\npushd \"${QT_ANDROID_KEYSTORE_PATH%/*}\"\nkeytool -genkey -v -keystore \"$QT_ANDROID_KEYSTORE_ALIAS\" -alias \"$QT_ANDROID_KEYSTORE_ALIAS\" -keyalg RSA -keysize 2048 -validity 10000\npopd\n```\n\nNote that `QT_ANDROID_KEYSTORE_PATH` needs to point to a particular keystore *file* (and *not* the containing\ndirectory).\n\n---\n\nExample for building `c++utilities`, `passwordfile`, `qtutilities` and `passwordmanager` in one step to create\nan Android APK for aarch64 assuming required `android-*` packages are already installed:\n\n```\n# unset any potentially problematic Java options\nexport _JAVA_OPTIONS=\n\n# configure and build using CMake presets and helpers from android-cmake package\nsource android-env aarch64\nexport BUILD_DIR=…\ncd \"$SOURCES/subdirs/passwordmanager\"\ncmake --preset arch-android -DBUILTIN_ICON_THEMES='breeze;breeze-dark'\ncmake --build --preset arch-android\n\n# install the app\nadb install \"$BUILD_DIR/passwordmanager/arch-android-arm64-v8a/android-build//build/outputs/apk/release/android-build-release-signed.apk\"\n```\n\n---\n\nTo use a container you can create a suitable image using the `imgbuild` script from the PKGBUILDs repo, see\nits [README](https://github.com/Martchus/PKGBUILDs/blob/master/README.md#container-image-building-packages-within-a-container).\n\nAfter creating a container from that image like it is done in\n[the example script from the PKGBUILDs repo](https://github.com/Martchus/PKGBUILDs/blob/master/devel/container/create-devel-container-example)\nyou can install required dependencies via `pacman`, e.g. for Syncthing Tray one would install:\n\n```\npodman container exec -it archlinux-devel-container \\\n  pacman -Syu clang ninja git extra-cmake-modules qt6-{base,tools,declarative,shadertools} android-cmake android-aarch64-qt6-{base,declarative,tools,translations,svg} go perl-yaml-libyaml\n```\n\nYou use `keytool` from within the container in the same way as shown above:\n```\npodman container exec -it -e QT_ANDROID_KEYSTORE_PATH -e QT_ANDROID_KEYSTORE_ALIAS -e QT_ANDROID_KEYSTORE_STORE_PASS -e QT_ANDROID_KEYSTORE_KEY_PASS \\\n  archlinux-devel-container keytool …\n```\n\nWhen setting the environment variables, make sure `QT_ANDROID_KEYSTORE_PATH` points to the path of the kestore\nfile *within* the container.\n\n\nThen the build can be invoked like this:\n\n```\npodman container exec -it -e QT_ANDROID_KEYSTORE_PATH -e QT_ANDROID_KEYSTORE_ALIAS -e QT_ANDROID_KEYSTORE_STORE_PASS -e QT_ANDROID_KEYSTORE_KEY_PASS \\\n archlinux-devel-container \\\n bash -c '\n  cd /src/c++/cmake/subdirs/syncthingtray\n  source android-env aarch64\n  export BUILD_DIR=/build/presets\n  cmake --preset arch-android\n  cmake --build --preset arch-android'\n```\n\nYou can also use `adb` from the container, see the\n[examples in the PKGBUILDs repo](https://github.com/Martchus/PKGBUILDs/blob/master/README.md#deploydebug-android-package-using-tooling-from-android-sdk-package).\n\n###### Further details\n* The Android packages for the dependencies Boost, Qt, iconv, OpenSSL and Kirigami are provided on the AUR and\n  by my [PKGBUILDs](http://github.com/Martchus/PKGBUILDs) repo.\n* The latest Java version that is currently supported is version 17, see QTBUG-119223.\n* Use `QT_QUICK_CONTROLS_STYLE=Material` and `QT_QUICK_CONTROLS_MOBILE=1` to test the Qt Quick GUI like it would\n  be shown under Android via a normal desktop build.\n* One can open the Gradle project that is created within the build directory in Android Studio and run the app in\n  the emulator.\n\n##### Remarks for building on Windows\nTo create a development build on Windows, it is most straight forward to use the `devel-qt6` preset. To create\na debug build (e.g. to debug with GDB) use the `debug-qt6` preset. Set the `BUILD_DIR` environment variable to\nspecify the directory to store build artefacts.\n\nI recommended to conduct the build in an MSYS2 mingw64/ucrt64/… shell. There are different\n[environments](https://www.msys2.org/docs/environments) to choose from. I recommended UCRT64 for my projects\nbut MINGW64 will work as well. In theory CLANG64 and CLANGARM64 will work as well but `libc++` is not tested as\nmuch (especilly on Windows) so expect some tough edges. The 32-bit environments will not work for anything\nrequiring Qt 6 or later.\n\nRun the following commands to build one of my applications and its `c++utilities`/`qtutilities` dependencies\nin one go (in this example Syncthing Tray):\n```\n# set prefix of package names depending on what env you want to use, see https://www.msys2.org/docs/environments\nprefix=mingw-w64-ucrt-x86_64      # in UCRT64 shell, recommended and used in all further examples\nprefix=mingw-w64-x86_64           # in MINGW64 shell\nprefix=mingw-w64-i686             # in MINGW32 shell\nprefix=mingw-w64-clang-x86_64     # in CLANG64 shell\nprefix=mingw-w64-clang-aarch64    # in CLANGARM64 shell\n\n# install dependencies; you may strip down this list depending on the application and features to enable\npacman -Syu git perl-YAML-Tiny $prefix-gcc $prefix-ccache $prefix-cmake $prefix-boost $prefix-cppunit $prefix-qt6-base $prefix-qt6-declarative $prefix-qt6-tools $prefix-qt6-svg $prefix-clang-tools-extra $prefix-doxygen $prefix-ffmpeg $prefix-go $prefix-libarchive\n\n# clone repositories as mentioned under \"Building this straight\" in the application's README file\ncd /path/to/store/sources\n...\ngit clone ...\n...\n\n# configure and invoke the build\ncd subdirs/syncthingtray\ncmake --preset devel-qt6\ncmake --build \"$BUILD_DIR/syncthingtray/devel-qt6\" devel-qt6 -- -v\n```\n\nRun the following commands to build libraries individually (in this example `tagparser`) and\ninstalling them in some directory (in this example `$BUILD_DIR/install`) for use in another\nproject:\n```\n# install dependencies\nprefix=mingw-w64-ucrt-x86_64\npacman -Syu git $prefix-gcc $prefix-ccache $prefix-cmake $prefix-boost $prefix-cppunit\n\n# clone relevant repositories, e.g. here just tagparser and its dependency c++utilities\ncd /path/to/store/sources\ngit config core.symlinks true\ngit clone https://github.com/Martchus/cpp-utilities.git c++utilities\ngit clone https://github.com/Martchus/tagparser.git\n\n# configure and invoke the build and installation of the projects individually\ncmake --preset devel-qt6 -S c++utilities -DCMAKE_INSTALL_PREFIX=\"$BUILD_DIR/install\"\ncmake --build \"$BUILD_DIR/c++utilities/devel-qt6\" --target install -- -v\nln -rs c++utilities/CMakePresets.json tagparser/CMakePresets.json\ncmake --preset devel-qt6 -S tagparser -DCMAKE_INSTALL_PREFIX=\"$BUILD_DIR/install\"\ncmake --build \"$BUILD_DIR/tagparser/devel-qt6\" --target install -- -v\n```\n\nNote that:\n* Not all those dependencies are required by all my projects and some are just optional.\n    * The second example to just build `c++utilities` and `tagparser` already shows a stripped-down list\n      of dependencies.\n    * Especially `…-go` is only required when building Syncthing Tray with built-in Syncthing-library enabled.\n      To build in an MSYS2 shell one needs to invoke e.g. `export GOROOT=/ucrt64/lib/go` or\n      `export GOROOT=/mingw64/lib/go` so Go can find its root.\n    * All Qt-related dependencies are generally only required for building with Qt GUI, e.g. Tag Editor\n      and Password Manager can be built without Qt GUI. The libraries `c++utilities` and `tagparser` don't\n      require Qt at all.\n* To run the binaries from the Windows terminal, you need to add the mingw-w64 libraries from the MSYS2\n  installation to the path, e.g. `$Env:PATH = \"$Env:MSYS2_ROOT\\ucrt64\\bin\"` or\n  `$Env:PATH = \"$Env:MSYS2_ROOT\\mingw64\\bin\"`.\n* You can also easily install Qt Creator via MSYS2 using `pacman -S $prefix-qt-creator`. In Qt\n  Creator you can import the build configured via presets on the command-line as existing build. This also\n  works for the MSVC build mentioned below. This way not much tinkering in the Qt Creator settings is\n  required. I had to set the debugger path to use GDB, though.\n* You must *not* use the presets containing `mingw-w64` in their name as those are only intended for\n  cross-compilation on Arch Linux.\n\n###### Building with MSVC\nTo build with MSVC you can use the `win-x64-msvc-static` preset. This preset (and all presets inheriting from it) need\nvarious additional environment variables to be set and you need to install dependencies from various sources:\n* `MSYS2_ROOT` and `MSYS2_PREFIX`: for Perl (only used by `qtforkawesome` so far), `clang-format`, Doxygen, FFmpeg and\n  Go (only used by `libsyncthing`) provided via MSYS2 packages; install the following packages:\n  ```\n  prefix=mingw-w64-ucrt-x86_64 # see \"Remarks for building on Windows\" for details and other options\n  pacman -Syu perl-YAML $prefix-clang-tools-extra $prefix-doxygen $prefix-ffmpeg $prefix-go\n  ```\n    * `MSYS2_ROOT` must be set to the main install directory of MSYS2 (that also contains all the executables for the\n      different shells/environments).\n    * `MSYS2_PREFIX` must be set to the prefix of the environment you want to use. That is one of the values mentioned\n      in the \"Prefix\" column on the [table of MSYS2 environments](https://www.msys2.org/docs/environments), e.g.\n      `MSYS2_PREFIX=/ucrt64` for the UCRT64 environment.\n* `MSVC_ROOT`: for compiler and stdlib usually installed as part of Visual Studio setup, e.g.\n  `C:/Program Files/Microsoft Visual Studio/2022/Community/VC/Tools/MSVC/14.34.31933`\n* `WIN_KITS_ROOT`: for Windows platform headers/libraries usually installed as part of Visual Studio setup,\n  e.g. `C:/Program Files (x86)/Windows Kits/10`\n* `WIN_KITS_VERSION`: the relevant subdirectory within `WIN_KITS_ROOT`, usually a version number like `10.0.22621.0`\n* `QT_ROOT`: for Qt libraries provided by the official Qt installer, e.g. `D:/programming/qt/6.5.0/msvc2019_64`\n* `QT_TOOLS`:  for additional build tools provided by the official Qt installer, e.g. `D:/programming/qt/Tools`\n* `VCPKG_ROOT`: directory of VCPKG checkout used for other dependencies; install the following packages:\n  ```\n  vcpkg install boost-system:x64-windows-static boost-iostreams:x64-windows-static boost-filesystem:x64-windows-static boost-hana:x64-windows-static boost-process:x64-windows-static boost-asio:x64-windows-static libiconv:x64-windows-static zlib:x64-windows-static openssl:x64-windows-static cppunit:x64-windows-static libarchive'[bzip2,crypto,zstd]':x64-windows-static\n  ```\n\nWhen building with MSVC, do *not* use any of the MSYS2 shells. The environment of those shells leads to\nbuild problems. You can however use CMake and Ninja from MSYS2's mingw-w64 packaging (instead of the CMake\nversion from Qt's installer). Then you need to specify the Ninja executable manually so the CMake invocation\nwould become something like this for UCRT64:\n```\n`\u0026 \"$Env:MSYS2_ROOT\\ucrt64\\bin\\cmake.exe\" --preset win-x64-msvc-static -DCMAKE_MAKE_PROGRAM=\"$Env:MSYS2_ROOT\\ucrt64\\bin\\ninja.exe\" .\n```\nor for MINGW64:\n```\n`\u0026 \"$Env:MSYS2_ROOT\\mingw64\\bin\\cmake.exe\" --preset win-x64-msvc-static -DCMAKE_MAKE_PROGRAM=\"$Env:MSYS2_ROOT\\mingw64\\bin\\ninja.exe\" .\n```\n\nTo run the resulting binaries, you'll need to make sure the Qt libraries are in the search path, e.g. using\n`$Env:PATH = \"$Env:QT_ROOT\\bin\"`.\n\nNote that you don't need to install all Visual Studio has to offer. A customized installation with just\nC++ core features, MSVC x86/x64 build tools, Windows SDK and vcpkg should be enough. In Qt's online installer\nyou can also uncheck everything except the MSVC build of Qt.\n\nIf the compilation of the resource file doesn't work you can use `-DWINDOWS_RESOURCES_ENABLED=OFF` to continue\nthe build regardless.\n\n###### Building under Windows for Android\nBuilding for Android under Windows is still experimental and not regularly tested. It is generally supported\nby CMake, Android tooling and Qt, though. So as long as all dependencies are installed correctly by *some*\nmeans it is supposed to work. The following instructions describe how one could approach the installation of\nthe required dependencies.\n\n---\n\nTo build for Android under Windows one needs to install the Android NDK and additional libraries depending\non the concrete library/app and wanted features. To build anything that depends on Qt one also needs the\nAndroid SDK and Qt for Android.\n\n\u003cdetails\u003e\n\u003csummary\u003eInstall Android SDK and NDK\u003c/summary\u003e\n\nThe easiest way to install the SDK is to install [Android Studio](https://developer.android.com/studio).\nIts setup wizard allows to install the SDK and other useful tools. The Gradle project files created by Qt can\nalso be opened with it. This setup will also use the version of Java that comes with Android Studio.\n\nThe NDK needs to be [downloaded separately](https://developer.android.com/ndk/downloads).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eInstall Qt\u003c/summary\u003e\n\nThe easiest way to install Qt is via the official [Qt installer](https://www.qt.io/download-qt-installer-oss).\nThe open source version is sufficient but a Qt account is required.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eInstall additional native libraries for Android\u003c/summary\u003e\n\nAdditional libraries can be installed via MSYS2 using my Arch Linux packaging. Note that this is not generally\nrequired to build Syncthing Tray as use of libiconv, Boost, OpenSSL and CppUnit is optional (so only Qt is\nrequired besides the C/C++ standard libraries). However, the following instructions and the CMake preset make\nuse of MSYS2 and the `android-cmake` package. The OpenSSL package is also very likely wanted for TLS support.\n\nTo install additional libraries via MSYS2, add my Arch Linux repository to\n`/etc/pacman.conf`:\n\n```\n[ownstuff]\nSigLevel = Required DatabaseOptional\nServer = https://ftp.f3l.de/~martchus/$repo/os/$arch\nServer = https://martchus.dyn.f3l.de/repo/arch/$repo/os/$arch\n```\n\nAfter following [instructions for importing my GPG key](https://martchus.dyn.f3l.de/repo/arch/ownstuff) you\ncan install Android packages, e.g.:\n\n```\npacman -Syu android-cmake android-{x86-64,aarch64}-{boost,libiconv,openssl,cppunit} \\\n  --assume-installed android-ndk --assume-installed android-sdk\n````\n\nYou may even install a few KDE libraries like Kirigami:\n```\npacman -S android-{aarch64,x86-64}-kirigami --assume-installed=android-{aarch64,x86-64}-qt6-{base,declarative,shadertools,svg,5compat}\n```\n\nWhether this will actually work at runtime hasn't been tested yet. One definitely has to make sure that the\nused version of Qt is at least as new as the version the KDE libraries from my repo have been linked against.\n\nThe libraries will end up under `/opt/android-libs` within your MSYS2 installation. Do not install any non\n`android-*-` packages, though. They will have file conflicts with packages provided by MSYS2 and are not usable\nunder Windows anyway.\n\nThe Qt packages for Android cannot be used as well because they rely on the Qt packaging provided by Arch Linux\nfor tooling. (Maybe the Qt packages provided by MSYS2 mingw-w64 packages could be used for tooling. This hasn't\nbeen tested yet, though.)\n\nTo search for available Android packages on my repo per architecture one can use e.g.\n`pacman -Ss android-aarch64-`.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eConduct build\u003c/summary\u003e\n\nSet the following environment variables:\n\n* `ANDROID_HOME`: path to the Android SDK\n* `ANDROID_NDK_HOME`: path to the Android NDK\n* `ANDROID_STUDIO_HOME`: Android studio install directory (for adding Java to `PATH` and setting `JAVA_HOME`)\n* `QT_PLATFORMS_ROOT`: directory containing Qt platform directories installed via the official Qt installer,\n  e.g. `D:/programming/qt/6.8.0`\n* `QT_ANDROID_ARCH`: `x86_64`/`arm64_v8a`/`armv7`/`x86`\n* `QT_ANDROID_KEYSTORE_PATH`: path of directory containing Android keystores\n* `QT_ANDROID_KEYSTORE_ALIAS`: name of Android keystore to use\n* `QT_ANDROID_KEYSTORE_STORE_PASS`: keystore store password\n* `QT_ANDROID_KEYSTORE_KEY_PASS`: keystore key password\n* `MSYS2_ROOT`: install directory of MSYS2\n\nThen the build can be conducted in a MSYS2 shell, e.g.:\n\n```\nsource android-env x86-64 # or aarch64\ncmake --preset win-android\ncmake --build --preset win-android\n```\n\u003c/details\u003e\n\n### Packaging\nThe repositories mentioned below contain packages for `c++utilities` itself but also for my other projects.\nFor a more comprehensive list of repositories providing my other projects such as Syncthing Tray, checkout\nthe README of those projects instead.\n\n#### Arch Linux package\nThe repository [PKGBUILDs](https://github.com/Martchus/PKGBUILDs) contains files for building Arch Linux\npackages of the latest release and the Git master.\n\nPKGBUILDs to cross compile for Android, Windows (using mingw-w64) and for MacOS X (using osxcross) are\nincluded as well.\n\n#### RPM packages for openSUSE and Fedora\nRPM \\*.spec files can be found at [openSUSE Build Servide](https://build.opensuse.org/project/show/home:mkittler).\nPackages are available for several architectures.\n\nThere is also a [sub project](https://build.opensuse.org/project/show/home:mkittler:vcs) containing the builds\nfrom the Git master branch.\n\n#### Gentoo\nCheckout [Case_Of's overlay](https://codeberg.org/Case_Of/gentoo-overlay)\nor [perfect7gentleman's overlay](https://gitlab.com/Perfect_Gentleman/PG_Overlay).\n\n## Copyright notice and license\nCopyright © 2015-2025 Marius Kittler\n\nAll code is licensed under [GPL-2-or-later](LICENSE).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartchus%2Fcpp-utilities","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmartchus%2Fcpp-utilities","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartchus%2Fcpp-utilities/lists"}