commit 0863f4b8
Clean up the README, add missing badges, and more
I tried to "nest" relevant content under headings, added notes about Cmake usage, and fixed some grammatical errors.
I added a section about installation, and made the build step system-agnostic.
Also changed the README's Cmake command to not build tests.
It's a lot quicker to not build them, and I doubt everyone wants to build/run tests.
Hopefully it's all an improvement :smile:
Changed files
| M | README.md before |
diff --git a/README.md b/README.md
index ba1e811..696da84 100644
--- a/README.md
+++ b/README.md
@@ -1,81 +1,117 @@
-# PlatformFolders [](https://travis-ci.org/sago007/PlatformFolders) [](https://ci.appveyor.com/project/sago007/platformfolders) [](https://raw.githubusercontent.com/sago007/PlatformFolders/master/LICENSE) [](https://gitter.im/PlatformFolders/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [](https://www.codacy.com/app/github_43/PlatformFolders?utm_source=github.com&utm_medium=referral&utm_content=sago007/PlatformFolders&utm_campaign=Badge_Grade)
+# PlatformFolders [](https://travis-ci.org/sago007/PlatformFolders) [](https://ci.appveyor.com/project/sago007/platformfolders) [](https://raw.githubusercontent.com/sago007/PlatformFolders/master/LICENSE) [](https://gitter.im/PlatformFolders/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [](https://www.codacy.com/app/github_43/PlatformFolders?utm_source=github.com&utm_medium=referral&utm_content=sago007/PlatformFolders&utm_campaign=Badge_Grade)
-A C++ library to look for special directories like "My Documents" and "%APPDATA%" so that you do not need to write Linux, Windows and Mac OS X specific code
+A C++ library to look for directories like `My Documents`, `~/.config`, `%APPDATA%`, etc. so that you do not need to write platform-specific code
-Can be found at: https://github.com/sago007/PlatformFolders
+[Source code](https://github.com/sago007/PlatformFolders) • [Latest release](https://github.com/sago007/PlatformFolders/releases/latest) • [Doxygen documentation](http://sago007.github.io/PlatformFolders/html/doxygen/)
-Releases can be downloaded here: https://github.com/sago007/PlatformFolders/releases
+## Rationale
-# Rationale
There are a lot of platform abstraction libraries available. You can get graphics abstraction libraries, GUI abstraction libraries and file abstraction libraries.
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.
-I have written a bit more about it here: http://sago007.blogspot.dk/2015/10/abstraction-for-special-folders.html
+[I have written a bit more about it here.](http://sago007.blogspot.dk/2015/10/abstraction-for-special-folders.html)
There are some alternatives that you might consider instead:
- * QStandardPaths - http://doc.qt.io/qt-5/qstandardpaths.html
- * glib - https://developer.gnome.org/glib/stable/glib-Miscellaneous-Utility-Functions.html
+
+* [QStandardPaths](http://doc.qt.io/qt-5/qstandardpaths.html)
+* [glib](https://developer.gnome.org/glib/stable/glib-Miscellaneous-Utility-Functions.html)
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.
-# Documentation
+## Operating System Support
+
+### Windows
+
+For Windows, the folders are fetched using SHGetFolderPath.
+
+The amount of supported folders differ from Windows version and this library targets XP and newer.\
+XP support will be dropped very soon.
+
+"Save Games" and "Downloads" should not be used, as they are undefined on XP.
+
+### Linux
+
+This library uses the [XDG user-dirs.](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)
+
+It should work on any Unix system that has the following headers available: `pwd.h`, `unistd.h`, and `sys/types.h`
+
+### macOS
+
+Uses the deprecated FSFindFolder (there is no C++ alternative), which requires the CoreServices framework during linking.
+
+## Usage
+
+This 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.
+
+You 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).
+
+```cmake
+# Specifying a version is optional -- note it follows by Semver
+find_package(platform_folders 3.1.0 REQUIRED)
+# Which creates the IMPORTED lib "sago::platform_folders"
+# Use it like so...
+target_link_libraries(EXEORLIBNAME PRIVATE sago::platform_folders)
+```
+
+Alternatively, you can just copy the [sago](https://github.com/sago007/PlatformFolders/tree/master/sago) folder into your program and manually link everything.
-Aside from this page there are also Doxygen available at http://sago007.github.io/PlatformFolders/html/doxygen/
+### Building
-# Windows support
-For Windows the folders are fetched using SHGetFolderPath.
-The amount of supported folders differ from Windows version and this library targets XP and newer... and I'll drop XP support very soon.
-Currently "Save Games" and "Downloads" should not be used as they are undefined on XP.
+**Notes:**
+* macOS requires the CoreServices framework during linking.
+* If you don't want to install, remove the `--target install` command.
-# Linux support
-In Linux a lot of these folders are not official defined. However this library uses XDG user dirs.
+Linux/macOS:
-# Mac OS X support
-Uses the deprecated FSFindFolder (there is no C++ alternative). It requires "-framework CoreServices" during linking.
+```
+mkdir -p build && cd build
+cmake -DBUILD_TESTING=OFF -DCMAKE_BUILD_TYPE=Release ..
+sudo cmake --build . --target install
+```
-# Usage
-Copy "sago/platform_files.cpp" and "sago/platform_fildes.h" to your program and make sure that the cpp file is compiled and linked.
+Windows:
-It is also possible to compile and it like:
```
-mkdir -p build
-cd build
-cmake ..
-make
+mkdir build && cd build
+cmake -DBUILD_TESTING=OFF ..
+runas /user:Administrator "cmake --build . --config Release --target install"
```
-Just be aware that Mac OS X requires "-framework CoreServices" during linking no matter the choice.
-# Hello World
+## Example Usage
This sample program gets all folders from the system:
-```
-#include <iostream>
-#include <stirng>
-#include <vector>
-#include "sago/platform_folders.h"
-using std::cout;
+```cpp
+#include <sago/platform_folders.h>
+#include <iostream>
+#include <string>
int main()
{
- cout << "Config: " << sago::getConfigHome() << "\n";
- cout << "Data: " << sago::getDataHome() << "\n";
- cout << "Cache: " << sago::getCacheDir() << "\n";
- cout << "Documents: " << sago::getDocumentsFolder() << "\n";
- cout << "Desktop: " << sago::getDesktopFolder() << "\n";
- cout << "Pictures: " << sago::getPicturesFolder() << "\n";
- cout << "Music: " << sago::getMusicFolder() << "\n";
- cout << "Video: " << sago::getVideoFolder() << "\n";
- cout << "Download: " << sago::getDownloadFolder1() << "\n";
- cout << "Save Games 1: " << sago::getSaveGamesFolder1() << "\n";
+ using std::cout;
+
+ cout << "Config: " << sago::getConfigHome() << '\n';
+ cout << "Data: " << sago::getDataHome() << '\n';
+ cout << "Cache: " << sago::getCacheDir() << '\n';
+ sago::PlatformFolders p;
+ cout << "Documents: " << p.getDocumentsFolder() << "\n";
+ cout << "Desktop: " << p.getDesktopFolder() << "\n";
+ cout << "Pictures: " << p.getPicturesFolder() << "\n";
+ cout << "Music: " << p.getMusicFolder() << "\n";
+ cout << "Video: " << p.getVideoFolder() << "\n";
+ cout << "Download: " << p.getDownloadFolder1() << "\n";
+ cout << "Save Games 1: " << p.getSaveGamesFolder1() << "\n";
return 0;
}
```
-The output on Linux would look like this:
+### Example Output
+
+#### On Linux
+
```
Config: /home/poul/.config
Data: /home/poul/.local/share
@@ -89,7 +125,8 @@ Download: /home/poul/Hentede filer
Save Games 1: /home/poul/.local/share
```
-On Windows it could be:
+#### On Windows
+
```
Config: C:\users\poul\Application Data
Data: C:\users\poul\Application Data
@@ -103,7 +140,8 @@ Download: C:\users\poul\Skrivebord
Save Games 1: C:\users\poul\Mine dokumenter\My Games
```
-On Mac OS X it could be:
+#### On macOS
+
```
Config: /Users/poul/Library/Application Support
Data: /Users/poul/Library/Application Support
@@ -117,16 +155,19 @@ Download: /Users/poul/Downloads
Save Games 1: /Users/poul/Library/Application Support
```
-# C++ support
-Versions up to 3.X.X should compile with any C++98 compiler.
-Versions from 4.0.0 and up requires a C++11 compatible compiler.
+## Compiler Compatibility
+
+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.
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.
-# Encoding
-From version 3.0 UTF-8 is always used on Windows and will also be the default on almost any other system.
-Before version 3.0 Windows used ANSI encoding. Microsoft's default choice of UTF-16 is not compatible with platform independent code.
-Although the user may use an characters they want I recommend, that the program should not have non ASCII characters in the source code itself.
+## Encoding
+
+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.
# Licence
+
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.