Module wix::stored_path

source ·
Expand description

Utilities for working with paths that need to be stored in files in a cross-platform way.

Big picture: work with paths however you want, as long as any path that gets written to a file (e.g. via a template) always gets converted into a StoredPathBuf first, forcing all the platform-specific differences to get normalized out.

Although both std and camino have excellent support for working with paths, they’re both designed to have host-platform-specific behaviour (which is good/correct) that makes them unsuitable for working with paths that need to stored in persistent cross-platform ways – like writing them to files. The wxs files we generate contain paths to other files, and we want to reliably produce the same wxs file on all machines, so we need something else!

Most notably, std and camino handle path separators differently on different platforms:

  • valid separtors:
    • on windows, \ and / are both valid path separators
    • on unix, only / is a valid separator, and \ can appear in file names
  • auto separators:
    • on windows, using APIs like join will use a \ separator
    • on unix, using APIs like join will use a / separator

Since cargo-wix is fundamentally concerned with producing things that work on windows, we can comfortably force unix to be “like windows” to normalize the behaviour. This normalization is handled by the StoredPath and StoredPathBuf types.

These types have two flavours of entry-point:

  • When making a StoredPathBuf from a String, the input is assumed to be user-provided and is forwarded verbatim without any normalization. Windows is permissive of both kinds of path separator, so we never need to “fix” things up.

  • When making a StoredPathBuf from a Path or Utf8Path, the input is assumed to be tainted with platform-specific behaviour, and all path separators are normalized to \. The net effect is that on windows StoredPathBuf usually doesn’t do anything, but on unix it forces many /’s to \’s. See StoredPathBuf::from_utf8_path for the implementation.

A StoredPath is not intended for doing actual i/o, and as such does not expose a way for it to be turned back into a “real” path, and does not expose APIs like exists. However it is useful/necessary to be able to ask questions like “is this file an RTF”, so we do need to implement basic path parsing functions like file_name and extension.

Notably StoredPath::file_nameconsiders both` and / to be path separators. Ideally it should behave identically to std/camino on windows, making all platforms behave like windows.

Structs