platform-path

What is this?

platform-path is a small tool (and library) that tells you (or your programs) where to put things, according to whatever standard applies to the system you're running it on.

Why does this exist?

Because it encodes domain-specific knowledge in a scriptable tool. It knows the standards, so you don't have to.

Every platform has some sort of standard(ish) set of paths where it expects things to be. Conforming to improves user experience, and OS integration.

As an example, on macOS, caches are excluded from iCloud backups, Spotlight searches, can be purged automatically when disk space is very low (when the app is not running), and should be candidate for the "Optimize Storage" utility.

On Linux, applications installed with FlatPak or AppImage may be sandboxed with application-specific paths. If your application relies on a fixed path, it may not be writable (or even readable) depending on sandbox policies.

On Windows, Roaming Profiles may use different data paths than Local Profiles.

These are just a few examples.

platform-path can tell you where to put things.

How do I get this majestic tool?

cargo install platform-path

How do I use it?

Options can be provided via environment or commandline. These examples assume a user on macOS named "DemoUser", with the following environment:

PROJECT_QUALIFIER="com.suse"
PROJECT_ORGANIZATION="SUSE Software Solutions"

What is the base directory for preferences?

$ platform-path print base preference

/Users/DemoUser/Library/Preferences

Where should NiftyGate put it's cache?

$ platform-path print project cache --project-application NiftyGate

/Users/DemoUser/Library/Caches/com.suse.SUSE-Software-Solutions.NiftyGate

Where should runtime files like sockets be stored?

platform-path print base runtime

Error: platform standard does not define requested directory

(error written to STDERR, exit status is non-zero)

Where is the user's Download folder?

$ platform-path print user download

/Users/DemoUser/Downloads

For a full list, consult the built-in help.

platform-path --help

Optional Features

There are a few less conventional features that are not enabled by default.

Structured Output

If, for some reason, you want the output in a structured format, you can build platform-path with the json and/or yaml features.

These will add some variants to the --format option.

HTTP Service

If you need to access this information in a context where shell output is not ideal, you can build platform-path with the http or https features.

This will add a serve subcommand that exposes the information over HTTP(S).

How does it work (internally)?

Internally, it relies on a series of excellent crates for all the complicated things, and provides a CLI around them.

• Commandline options and argument parsing are provided by clap (and structopt).
• The platform-specific standards knowledge is provided by directories.
• Unicode path validation is provided by camino.
• Structured output is provided by serde generally and format-specific crates (serde_json, and serde_yaml).
• The various failure scenarios are captured in a single Error type (which implements std::error::Error).
• The (optional) HTTP service is built using tide.
• For each way things can fail, an option exists in the CLI to handle it in a reasonable way, such as:
  • a --default option if a directory is not defined by the platform standards.
  • a --unicode=enforced option to coerce non-Unicode paths.

License

platform-path is available under the MIT License. See LICENSE.txt for the full text.