{"id":13730917,"url":"https://github.com/sago007/PlatformFolders","last_synced_at":"2025-05-08T03:32:12.202Z","repository":{"id":44806756,"uuid":"42786320","full_name":"sago007/PlatformFolders","owner":"sago007","description":"A C++ library to look for special directories like \"My Documents\" and \"%APPDATA%\" so that you do not need to write Linux, Windows or Mac OS X specific code","archived":false,"fork":false,"pushed_at":"2024-03-26T03:29:15.000Z","size":513,"stargazers_count":174,"open_issues_count":4,"forks_count":34,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-08-04T02:09:51.707Z","etag":null,"topics":["cpp","library","multi-platform","platform-independent","special-folders","standardpaths","xdg"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sago007.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-09-19T19:15:57.000Z","updated_at":"2024-07-08T15:58:30.000Z","dependencies_parsed_at":"2022-09-02T14:25:16.337Z","dependency_job_id":null,"html_url":"https://github.com/sago007/PlatformFolders","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sago007%2FPlatformFolders","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sago007%2FPlatformFolders/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sago007%2FPlatformFolders/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sago007%2FPlatformFolders/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sago007","download_url":"https://codeload.github.com/sago007/PlatformFolders/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224695787,"owners_count":17354480,"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":["cpp","library","multi-platform","platform-independent","special-folders","standardpaths","xdg"],"created_at":"2024-08-03T02:01:21.373Z","updated_at":"2024-11-14T21:31:49.208Z","avatar_url":"https://github.com/sago007.png","language":"C++","readme":"# PlatformFolders [![Build Status](https://travis-ci.org/sago007/PlatformFolders.svg?branch=master)](https://travis-ci.org/sago007/PlatformFolders) [![AppVeyor](https://img.shields.io/appveyor/ci/sago007/PlatformFolders.svg?label=Windows)](https://ci.appveyor.com/project/sago007/platformfolders) [![license](https://img.shields.io/github/license/sago007/PlatformFolders.svg)](https://raw.githubusercontent.com/sago007/PlatformFolders/master/LICENSE) [![Join the chat at https://gitter.im/PlatformFolders/Lobby](https://badges.gitter.im/PlatformFolders/Lobby.svg)](https://gitter.im/PlatformFolders/Lobby?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/729e36adcf5c4523bd136de1b33441cb)](https://www.codacy.com/app/github_43/PlatformFolders?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=sago007/PlatformFolders\u0026amp;utm_campaign=Badge_Grade)\n\nA C++ library to look for directories like `My Documents`, `~/.config`, `%APPDATA%`, etc. so that you do not need to write platform-specific code\n\n[Source code](https://github.com/sago007/PlatformFolders) • [Latest release](https://github.com/sago007/PlatformFolders/releases/latest) • [Doxygen documentation](https://sago007.github.io/PlatformFolders/html/doxygen/)\n\n## Rationale\n\nThere are a lot of platform abstraction libraries available. You can get graphics abstraction libraries, GUI abstraction libraries and file abstraction libraries.\n\nBut folder abstraction seems to be more difficult.\nMy problem was that the code that found the place to save data was platform dependent. This cluttered my code and often I would not discover that it did not compile until moving it to the different platforms.\n\n[I have written a bit more about it here.](https://sago007.blogspot.dk/2015/10/abstraction-for-special-folders.html)\n\nThere are some alternatives that you might consider instead:\n\n* [QStandardPaths](https://doc.qt.io/qt-5/qstandardpaths.html)\n* [glib](https://developer.gnome.org/glib/stable/glib-Miscellaneous-Utility-Functions.html)\n\nBoth are properly more mature than this library. However they are both parts of large frameworks and using them with libraries outside the framework may not be that simple.\n\n## Operating System Support\n\n### Windows\n\nFor Windows, the current version fetches the folders using SHGetKnownFolderPath. This requires Vista or newer.\n\n### Linux\n\nThis library uses the [XDG user-dirs.](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)\n\nIt should work on any Unix system that has the following headers available: `pwd.h`, `unistd.h`, and `sys/types.h`\n\n### macOS\n\nVersion 4.0.0 and forward uses hardcoded values for the directories on Mac OS X. Unlike the other operating systems the folders cannot be moved on a Mac and the translation is done in the UI.\nThe versions 2.X and 3.X uses the deprecated FSFindFolder, which requires the CoreServices framework during linking.\nVersion 1.X simple used the XDG specification.\n\n## Usage\n\nThis project should be compatible with things like [Cmake's ExternalProject_Add](https://cmake.org/cmake/help/latest/module/ExternalProject.html?highlight=externalproject_add#command:externalproject_add) if you wish to use it in your project.\n\nYou can also follow the [build step](#building) below to install at a system level, and use [Cmake's find_package](https://cmake.org/cmake/help/latest/command/find_package.html).\n\n```cmake\n# Specifying a version is optional -- note it follows Semver\nfind_package(platform_folders 3.1.0 REQUIRED)\n# Which imports the linkable library \"sago::platform_folders\"\n# Use it like so...\ntarget_link_libraries(EXEORLIBNAME PRIVATE sago::platform_folders)\n```\n\nAlternatively, you can just copy the [sago](https://github.com/sago007/PlatformFolders/tree/master/sago) folder into your program and manually link everything.\nIf you use the last option and are using a library version from before 4.0.0: Remember to link to the CoreServices lib when compiling on Mac. This typically means passing \"-framework CoreServices\" during the linking phase.\n\nNote that if you build in-tree, you can link against the Cmake alias `sago::platform_folders` just like if you had used find_package.\n\n### Building\n\n**Notes:**\n\n* Until 4.0.0 macOS required the CoreServices framework during linking.\n* If you don't want to install, remove the `--target install` command.\n\nLinux/macOS:\n\n```\nmkdir -p build \u0026\u0026 cd build\ncmake -DBUILD_TESTING=OFF -DCMAKE_BUILD_TYPE=Release ..\nsudo cmake --build . --target install\n```\n\nWindows:\n\n```\nmkdir build \u0026\u0026 cd build\ncmake -DBUILD_TESTING=OFF ..\nrunas /user:Administrator \"cmake --build . --config Release --target install\"\n```\n\n## Example Usage\n\nThis sample program gets all folders from the system:\n\n```cpp\n#include \u003csago/platform_folders.h\u003e\n#include \u003ciostream\u003e\n#include \u003cstring\u003e\n\nint main()\n{\n\tstd::cout \u003c\u003c \"Config: \" \u003c\u003c sago::getConfigHome() \u003c\u003c \"\\n\";\n\tstd::cout \u003c\u003c \"Data: \" \u003c\u003c sago::getDataHome() \u003c\u003c \"\\n\";\n\tstd::cout \u003c\u003c \"State: \" \u003c\u003c sago::getStateDir() \u003c\u003c \"\\n\";\n\tstd::cout \u003c\u003c \"Cache: \" \u003c\u003c sago::getCacheDir() \u003c\u003c \"\\n\";\n\tstd::cout \u003c\u003c \"Documents: \" \u003c\u003c sago::getDocumentsFolder() \u003c\u003c \"\\n\";\n\tstd::cout \u003c\u003c \"Desktop: \" \u003c\u003c sago::getDesktopFolder() \u003c\u003c \"\\n\";\n\tstd::cout \u003c\u003c \"Pictures: \" \u003c\u003c sago::getPicturesFolder() \u003c\u003c \"\\n\";\n\tstd::cout \u003c\u003c \"Music: \" \u003c\u003c sago::getMusicFolder() \u003c\u003c \"\\n\";\n\tstd::cout \u003c\u003c \"Video: \" \u003c\u003c sago::getVideoFolder() \u003c\u003c \"\\n\";\n\tstd::cout \u003c\u003c \"Download: \" \u003c\u003c sago::getDownloadFolder() \u003c\u003c \"\\n\";\n\tstd::cout \u003c\u003c \"Save Games 1: \" \u003c\u003c sago::getSaveGamesFolder1() \u003c\u003c \"\\n\";\n\tstd::cout \u003c\u003c \"Save Games 2: \" \u003c\u003c sago::getSaveGamesFolder2() \u003c\u003c \"\\n\";\n\treturn 0;\n}\n```\n\n### Example Output\n\n#### On Linux\n\n```\nConfig: /home/poul/.config\nData: /home/poul/.local/share\nState: /home/poul/.local/state\nCache: /home/poul/.cache\nDocuments: /home/poul/Dokumenter\nDesktop: /home/poul/Skrivebord\nPictures: /home/poul/Billeder\nMusic: /home/poul/Musik\nVideo: /home/poul/Videoklip\nDownload: /home/poul/Hentede filer\nSave Games 1: /home/poul/.local/share\nSave Games 2: /home/poul/.local/share\n```\n\n#### On Windows\n\n```\nConfig: C:\\users\\poul\\Application Data\nData: C:\\users\\poul\\Application Data\nState: C:\\users\\poul\\Local Settings\\Application Data\nCache: C:\\users\\poul\\Local Settings\\Application Data\nDocuments: C:\\users\\poul\\Mine dokumenter\nDesktop: C:\\users\\poul\\Skrivebord\nPictures: C:\\users\\poul\\Mine Billeder\nMusic: C:\\users\\poul\\Min Musik\nVideo: C:\\users\\poul\\Mine Film\nDownload: C:\\users\\poul\\Downloads\nSave Games 1: C:\\users\\poul\\Mine dokumenter\\My Games\nSave Games 2: C:\\users\\poul\\Saved Games\n```\n\n#### On macOS\n\n```\nConfig: /Users/poul/Library/Application Support\nData: /Users/poul/Library/Application Support\nState: /Users/poul/Library/Application Support\nCache: /Users/poul/Library/Caches\nDocuments: /Users/poul/Documents\nDesktop: /Users/poul/Desktop\nPictures: /Users/poul/Pictures\nMusic: /Users/poul/Music\nVideo: /Users/poul/Movies\nDownload: /Users/poul/Downloads\nSave Games 1: /Users/poul/Library/Application Support\nSave Games 2: /Users/poul/Library/Application Support\n```\n\n## Compiler Compatibility\n\nVersions up to 3.X.X should compile with any C++98 compiler.\\\nVersions from 4.0.0 and up require a C++11 compatible compiler.\n\nThe aim is to always support the default C++ compiler on the oldest supported version of Ubuntu. This is a very basic library and it is not supposed to force you to upgrade.\n\n## Encoding\n\nFrom version 3.0, Windows always encodes to UTF-8, and this will be the default on almost any other system.\nBefore version 3.0, Windows was encoded in ANSI.\nAlthough the user may use any characters they want, I recommend that the program should have only ASCII characters in the source code itself.\n\n# Licence\n\nProvided under the MIT license for the same reason XDG is licensed under it. So that you can quickly copy-paste the methods you need or just include the \"sago\"-folder.\n","funding_links":[],"categories":["C++"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsago007%2FPlatformFolders","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsago007%2FPlatformFolders","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsago007%2FPlatformFolders/lists"}