html/doxygen/4.2.0/index.html
browsing at commit = d359b8303bf7f48a83daa2ba60ccf4414cdc0d9b
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Platform folders: PlatformFolders <a href="https://travis-ci.org/sago007/PlatformFolders"><img src="https://travis-ci.org/sago007/PlatformFolders.svg?branch=master" alt="Build Status"/></a> <a href="https://ci.appveyor.com/project/sago007/platformfolders"><img src="https://img.shields.io/appveyor/ci/sago007/PlatformFolders.svg?label=Windows" alt="AppVeyor"/></a> <a href="https://raw.githubusercontent.com/sago007/PlatformFolders/master/LICENSE"><img src="https://img.shields.io/github/license/sago007/PlatformFolders.svg" alt="license"/></a> <a href="https://gitter.im/PlatformFolders/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"><img src="https://badges.gitter.im/PlatformFolders/Lobby.svg" alt="Join the chat at https://gitter.im/PlatformFolders/Lobby"/></a> <a href="https://www.codacy.com/app/github_43/PlatformFolders?utm_source=github.com&utm_medium=referral&utm_content=sago007/PlatformFolders&utm_campaign=Badge_Grade"><img src="https://api.codacy.com/project/badge/Grade/729e36adcf5c4523bd136de1b33441cb" alt="Codacy Badge"/></a></title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">Platform folders
 <span id="projectnumber">4.2.0</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">PlatformFolders <a href="https://travis-ci.org/sago007/PlatformFolders"><img src="https://travis-ci.org/sago007/PlatformFolders.svg?branch=master" alt="Build Status" style="pointer-events: none;" class="inline"/></a> <a href="https://ci.appveyor.com/project/sago007/platformfolders"><img src="https://img.shields.io/appveyor/ci/sago007/PlatformFolders.svg?label=Windows" alt="AppVeyor" style="pointer-events: none;" class="inline"/></a> <a href="https://raw.githubusercontent.com/sago007/PlatformFolders/master/LICENSE"><img src="https://img.shields.io/github/license/sago007/PlatformFolders.svg" alt="license" style="pointer-events: none;" class="inline"/></a> <a href="https://gitter.im/PlatformFolders/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"><img src="https://badges.gitter.im/PlatformFolders/Lobby.svg" alt="Join the chat at https://gitter.im/PlatformFolders/Lobby" style="pointer-events: none;" class="inline"/></a> <a href="https://www.codacy.com/app/github_43/PlatformFolders?utm_source=github.com&utm_medium=referral&utm_content=sago007/PlatformFolders&utm_campaign=Badge_Grade"><img src="https://api.codacy.com/project/badge/Grade/729e36adcf5c4523bd136de1b33441cb" alt="Codacy Badge" class="inline"/></a> </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a class="anchor" id="md_README"></a> A C++ library to look for directories like <code>My Documents</code>, <code>~/.config</code>, <code>APPDATA%</code>, etc. so that you do not need to write platform-specific code</p>
<p><a href="https://github.com/sago007/PlatformFolders">Source code</a> • <a href="https://github.com/sago007/PlatformFolders/releases/latest">Latest release</a> • <a href="https://sago007.github.io/PlatformFolders/html/doxygen/">Doxygen documentation</a></p>
<h1><a class="anchor" id="autotoc_md1"></a>
Rationale</h1>
<p>There are a lot of platform abstraction libraries available. You can get graphics abstraction libraries, GUI abstraction libraries and file abstraction libraries.</p>
<p>But folder abstraction seems to be more difficult. My 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.</p>
<p><a href="https://sago007.blogspot.dk/2015/10/abstraction-for-special-folders.html">I have written a bit more about it here.</a></p>
<p>There are some alternatives that you might consider instead:</p>
<ul>
<li><a href="https://doc.qt.io/qt-5/qstandardpaths.html">QStandardPaths</a></li>
<li><a href="https://developer.gnome.org/glib/stable/glib-Miscellaneous-Utility-Functions.html">glib</a></li>
</ul>
<p>Both 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.</p>
<h1><a class="anchor" id="autotoc_md2"></a>
Operating System Support</h1>
<h2><a class="anchor" id="autotoc_md3"></a>
Windows</h2>
<p>For Windows, the current version fetches the folders using SHGetKnownFolderPath. This requires Vista or newer.</p>
<h2><a class="anchor" id="autotoc_md4"></a>
Linux</h2>
<p>This library uses the <a href="https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG user-dirs.</a></p>
<p>It should work on any Unix system that has the following headers available: <code>pwd.h</code>, <code>unistd.h</code>, and <code>sys/types.h</code></p>
<h2><a class="anchor" id="autotoc_md5"></a>
macOS</h2>
<p>Version 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. The versions 2.X and 3.X uses the deprecated FSFindFolder, which requires the CoreServices framework during linking. Version 1.X simple used the XDG specification.</p>
<h1><a class="anchor" id="autotoc_md6"></a>
Usage</h1>
<p>This project should be compatible with things like <a href="https://cmake.org/cmake/help/latest/module/ExternalProject.html?highlight=externalproject_add#command:externalproject_add">Cmake's ExternalProject_Add</a> if you wish to use it in your project.</p>
<p>You can also follow the <a href="#building">build step</a> below to install at a system level, and use <a href="https://cmake.org/cmake/help/latest/command/find_package.html">Cmake's find_package</a>.</p>
<div class="fragment"><div class="line"># Specifying a version is optional -- note it follows Semver</div>
<div class="line">find_package(platform_folders 3.1.0 REQUIRED)</div>
<div class="line"># Which imports the linkable library "sago::platform_folders"</div>
<div class="line"># Use it like so...</div>
<div class="line">target_link_libraries(EXEORLIBNAME PRIVATE sago::platform_folders)</div>
</div><!-- fragment --><p>Alternatively, you can just copy the <a href="https://github.com/sago007/PlatformFolders/tree/master/sago">sago</a> folder into your program and manually link everything. If 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.</p>
<p>Note that if you build in-tree, you can link against the Cmake alias <code>sago::platform_folders</code> just like if you had used find_package.</p>
<h2><a class="anchor" id="autotoc_md7"></a>
Building</h2>
<p><b>Notes:</b></p>
<ul>
<li>Until 4.0.0 macOS required the CoreServices framework during linking.</li>
<li>If you don't want to install, remove the <code>--target install</code> command.</li>
</ul>
<p>Linux/macOS:</p>
<div class="fragment"><div class="line">mkdir -p build && cd build</div>
<div class="line">cmake -DBUILD_TESTING=OFF -DCMAKE_BUILD_TYPE=Release ..</div>
<div class="line">sudo cmake --build . --target install</div>
</div><!-- fragment --><p>Windows:</p>
<div class="fragment"><div class="line">mkdir build && cd build</div>
<div class="line">cmake -DBUILD_TESTING=OFF ..</div>
<div class="line">runas /user:Administrator "cmake --build . --config Release --target install"</div>
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md8"></a>
Example Usage</h1>
<p>This sample program gets all folders from the system:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include <sago/platform_folders.h></span></div>
<div class="line"><span class="preprocessor">#include <iostream></span></div>
<div class="line"><span class="preprocessor">#include <string></span></div>
<div class="line"> </div>
<div class="line"><span class="keywordtype">int</span> main()</div>
<div class="line">{</div>
<div class="line"> std::cout << <span class="stringliteral">"Config: "</span> << <a class="code" href="namespacesago.html#aa6c6da4e6fe460076ac069e176622f59">sago::getConfigHome</a>() << <span class="stringliteral">"\n"</span>;</div>
<div class="line"> std::cout << <span class="stringliteral">"Data: "</span> << <a class="code" href="namespacesago.html#a85c382a039426b76aa408961ac2149ee">sago::getDataHome</a>() << <span class="stringliteral">"\n"</span>;</div>
<div class="line"> std::cout << <span class="stringliteral">"State: "</span> << <a class="code" href="namespacesago.html#a8ffd6a057a03d7bd41932bf3fed69874">sago::getStateDir</a>() << <span class="stringliteral">"\n"</span>;</div>
<div class="line"> std::cout << <span class="stringliteral">"Cache: "</span> << <a class="code" href="namespacesago.html#a426458c0e30383f23ecab17bdf55a407">sago::getCacheDir</a>() << <span class="stringliteral">"\n"</span>;</div>
<div class="line"> std::cout << <span class="stringliteral">"Documents: "</span> << <a class="code" href="namespacesago.html#aa44dc2057a9acdb38a10e41a60b7bb82">sago::getDocumentsFolder</a>() << <span class="stringliteral">"\n"</span>;</div>
<div class="line"> std::cout << <span class="stringliteral">"Desktop: "</span> << <a class="code" href="namespacesago.html#ac9fc8e0a8f97b7066548223d43720ce8">sago::getDesktopFolder</a>() << <span class="stringliteral">"\n"</span>;</div>
<div class="line"> std::cout << <span class="stringliteral">"Pictures: "</span> << <a class="code" href="namespacesago.html#a45b407f0581bf3ac349682eb2481c630">sago::getPicturesFolder</a>() << <span class="stringliteral">"\n"</span>;</div>
<div class="line"> std::cout << <span class="stringliteral">"Music: "</span> << <a class="code" href="namespacesago.html#aef0ecc52b536a96e2f3096b43acbfcbe">sago::getMusicFolder</a>() << <span class="stringliteral">"\n"</span>;</div>
<div class="line"> std::cout << <span class="stringliteral">"Video: "</span> << <a class="code" href="namespacesago.html#a8eda16d34cba4c0f82a6e80077660780">sago::getVideoFolder</a>() << <span class="stringliteral">"\n"</span>;</div>
<div class="line"> std::cout << <span class="stringliteral">"Download: "</span> << <a class="code" href="namespacesago.html#a650b888f2d54cadfbe3347f3c9c40059">sago::getDownloadFolder</a>() << <span class="stringliteral">"\n"</span>;</div>
<div class="line"> std::cout << <span class="stringliteral">"Save Games 1: "</span> << <a class="code" href="namespacesago.html#ab568df2aa5ea8492975bbefb206a6145">sago::getSaveGamesFolder1</a>() << <span class="stringliteral">"\n"</span>;</div>
<div class="line"> std::cout << <span class="stringliteral">"Save Games 2: "</span> << <a class="code" href="namespacesago.html#afc7986187926c19b217427a73bdae16e">sago::getSaveGamesFolder2</a>() << <span class="stringliteral">"\n"</span>;</div>
<div class="line"> <span class="keywordflow">return</span> 0;</div>
<div class="line">}</div>
<div class="ttc" id="anamespacesago_html_a426458c0e30383f23ecab17bdf55a407"><div class="ttname"><a href="namespacesago.html#a426458c0e30383f23ecab17bdf55a407">sago::getCacheDir</a></div><div class="ttdeci">std::string getCacheDir()</div></div>
<div class="ttc" id="anamespacesago_html_a45b407f0581bf3ac349682eb2481c630"><div class="ttname"><a href="namespacesago.html#a45b407f0581bf3ac349682eb2481c630">sago::getPicturesFolder</a></div><div class="ttdeci">std::string getPicturesFolder()</div></div>
<div class="ttc" id="anamespacesago_html_a650b888f2d54cadfbe3347f3c9c40059"><div class="ttname"><a href="namespacesago.html#a650b888f2d54cadfbe3347f3c9c40059">sago::getDownloadFolder</a></div><div class="ttdeci">std::string getDownloadFolder()</div></div>
<div class="ttc" id="anamespacesago_html_a85c382a039426b76aa408961ac2149ee"><div class="ttname"><a href="namespacesago.html#a85c382a039426b76aa408961ac2149ee">sago::getDataHome</a></div><div class="ttdeci">std::string getDataHome()</div></div>
<div class="ttc" id="anamespacesago_html_a8eda16d34cba4c0f82a6e80077660780"><div class="ttname"><a href="namespacesago.html#a8eda16d34cba4c0f82a6e80077660780">sago::getVideoFolder</a></div><div class="ttdeci">std::string getVideoFolder()</div></div>
<div class="ttc" id="anamespacesago_html_a8ffd6a057a03d7bd41932bf3fed69874"><div class="ttname"><a href="namespacesago.html#a8ffd6a057a03d7bd41932bf3fed69874">sago::getStateDir</a></div><div class="ttdeci">std::string getStateDir()</div></div>
<div class="ttc" id="anamespacesago_html_aa44dc2057a9acdb38a10e41a60b7bb82"><div class="ttname"><a href="namespacesago.html#aa44dc2057a9acdb38a10e41a60b7bb82">sago::getDocumentsFolder</a></div><div class="ttdeci">std::string getDocumentsFolder()</div></div>
<div class="ttc" id="anamespacesago_html_aa6c6da4e6fe460076ac069e176622f59"><div class="ttname"><a href="namespacesago.html#aa6c6da4e6fe460076ac069e176622f59">sago::getConfigHome</a></div><div class="ttdeci">std::string getConfigHome()</div></div>
<div class="ttc" id="anamespacesago_html_ab568df2aa5ea8492975bbefb206a6145"><div class="ttname"><a href="namespacesago.html#ab568df2aa5ea8492975bbefb206a6145">sago::getSaveGamesFolder1</a></div><div class="ttdeci">std::string getSaveGamesFolder1()</div></div>
<div class="ttc" id="anamespacesago_html_ac9fc8e0a8f97b7066548223d43720ce8"><div class="ttname"><a href="namespacesago.html#ac9fc8e0a8f97b7066548223d43720ce8">sago::getDesktopFolder</a></div><div class="ttdeci">std::string getDesktopFolder()</div></div>
<div class="ttc" id="anamespacesago_html_aef0ecc52b536a96e2f3096b43acbfcbe"><div class="ttname"><a href="namespacesago.html#aef0ecc52b536a96e2f3096b43acbfcbe">sago::getMusicFolder</a></div><div class="ttdeci">std::string getMusicFolder()</div></div>
<div class="ttc" id="anamespacesago_html_afc7986187926c19b217427a73bdae16e"><div class="ttname"><a href="namespacesago.html#afc7986187926c19b217427a73bdae16e">sago::getSaveGamesFolder2</a></div><div class="ttdeci">std::string getSaveGamesFolder2()</div></div>
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md9"></a>
Example Output</h2>
<h3><a class="anchor" id="autotoc_md10"></a>
On Linux</h3>
<div class="fragment"><div class="line">Config: /home/poul/.config</div>
<div class="line">Data: /home/poul/.local/share</div>
<div class="line">State: /home/poul/.local/state</div>
<div class="line">Cache: /home/poul/.cache</div>
<div class="line">Documents: /home/poul/Dokumenter</div>
<div class="line">Desktop: /home/poul/Skrivebord</div>
<div class="line">Pictures: /home/poul/Billeder</div>
<div class="line">Music: /home/poul/Musik</div>
<div class="line">Video: /home/poul/Videoklip</div>
<div class="line">Download: /home/poul/Hentede filer</div>
<div class="line">Save Games 1: /home/poul/.local/share</div>
<div class="line">Save Games 2: /home/poul/.local/share</div>
</div><!-- fragment --><h3><a class="anchor" id="autotoc_md11"></a>
On Windows</h3>
<div class="fragment"><div class="line">Config: C:\users\poul\Application Data</div>
<div class="line">Data: C:\users\poul\Application Data</div>
<div class="line">State: C:\users\poul\Local Settings\Application Data</div>
<div class="line">Cache: C:\users\poul\Local Settings\Application Data</div>
<div class="line">Documents: C:\users\poul\Mine dokumenter</div>
<div class="line">Desktop: C:\users\poul\Skrivebord</div>
<div class="line">Pictures: C:\users\poul\Mine Billeder</div>
<div class="line">Music: C:\users\poul\Min Musik</div>
<div class="line">Video: C:\users\poul\Mine Film</div>
<div class="line">Download: C:\users\poul\Downloads</div>
<div class="line">Save Games 1: C:\users\poul\Mine dokumenter\My Games</div>
<div class="line">Save Games 2: C:\users\poul\Saved Games</div>
</div><!-- fragment --><h3><a class="anchor" id="autotoc_md12"></a>
On macOS</h3>
<div class="fragment"><div class="line">Config: /Users/poul/Library/Application Support</div>
<div class="line">Data: /Users/poul/Library/Application Support</div>
<div class="line">State: /Users/poul/Library/Application Support</div>
<div class="line">Cache: /Users/poul/Library/Caches</div>
<div class="line">Documents: /Users/poul/Documents</div>
<div class="line">Desktop: /Users/poul/Desktop</div>
<div class="line">Pictures: /Users/poul/Pictures</div>
<div class="line">Music: /Users/poul/Music</div>
<div class="line">Video: /Users/poul/Movies</div>
<div class="line">Download: /Users/poul/Downloads</div>
<div class="line">Save Games 1: /Users/poul/Library/Application Support</div>
<div class="line">Save Games 2: /Users/poul/Library/Application Support</div>
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md13"></a>
Compiler Compatibility</h1>
<p>Versions up to 3.X.X should compile with any C++98 compiler.\ Versions from 4.0.0 and up require a C++11 compatible compiler.</p>
<p>The 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.</p>
<h1><a class="anchor" id="autotoc_md14"></a>
Encoding</h1>
<p>From version 3.0, Windows always encodes to UTF-8, and this will be the default on almost any other system. Before version 3.0, Windows was encoded in ANSI. Although the user may use any characters they want, I recommend that the program should have only ASCII characters in the source code itself.</p>
<h1><a class="anchor" id="autotoc_md15"></a>
Licence</h1>
<p>Provided 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. </p>
</div></div><!-- PageDoc -->
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Sun Feb 6 2022 18:17:54 for Platform folders by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1
</small></address>
</body>
</html>