My project MKVToolNix has used the boost::filesystem
library for a long time. It allows for easy path manipulation (e.g. “what’s the parent directory”, “does the named entry exist & is a file” or “create all directories for this path that don’t exist yet”). The central class of the library is boost::filesystem::path
which encodes an absolute or relative part of an entry in the file system and offers various functions for modifying, querying or formatting it. All utility functions such as the aforementioned “create all directories” take path
instances as arguments.
All of this worked mostly fine.
After release v53 of MKVToolNix a user reported an issue with using Emojis in file names. Turns out this wasn’t trivial to debug and is likely a bug in boost::filesystem
or in the way I handled character encoding (more on that later).
This motivated me to look into converting MKVToolNix from boost::filesystem
to std::filesystem
which had been added to the C++ Standard Library with C++17. Its design is based heavily on boost::filesystem
: a lot of the classes & functions are named identically within the two namespaces and most of their semantics match. As I’m eager to reduce the number of third-party libraries by using C++ standard libraries where it makes sense, converting my code base seemed the obvious step.
I mean, how hard could it be? Right?
Easy changes
A lot of changes were trivial: simply replacing boost::filesystem::
with std::filesystem::
got me pretty far.
Another easy change was to replace deprecated function names with the current ones, e.g. branch_path()
with parent_path()
: look up the deprecated function name in for boost::filesystem
, take its replacement & swap the namespace — done.
Encodings & character set conversions
The most glaring difference in my opinion between the two libraries is how they handle encodings/character set conversions for the path
classes. In both libraries the path
class offer constructors for instances of std::string
and std::wstring
. Internally the classes use either std::string
or std::wstring
for storage depending on the operating system they’re compiled for: wide strings (std::wstring
) for Windows and narrow ones (std::string
) everywhere else.
This means that the constructors taking the string type that doesn’t match the storage type (std::string
on Windows, std::wstring
everywhere else) must do character set conversion, either from narrow to wide (Windows) or wide to narrow (Linux). This is where things get really dicey.
boost::filesystem
solves this by letting the user imbue the whole boost::filesystem::path
class with a C++ locale object. That locale object is used for the conversion. The programmer has to set this up once per program invocation, and that’s it. Easy.
MKVToolNix’s internal string handling uses UTF-8 encoded narrow strings everywhere. For file names, too[1]Yes, I know that’s bad as file systems on Unix aren’t guaranteed to have any type of encoding; file names might contain something that isn’t valid according to any encoding etc. etc.. Therefore the logical choice was to imbue boost::filesystem::path
with an UTF-8 character set conversion locale. It would convert between UTF-8 encoded narrow strings and wide strings.
std::filesystem
does not do it that way. At all. For the constructor taking char
-based narrow strings (pointer-to-char
or std::string
) conversion from the native narrow encoding is done. On POSIX systems this means no conversion which matches how MKVToolNix is coded: std::filesystem::path
receives a UTF-8 encoded narrow string & stores it as-is internally.
On Windows, though, this means that conversion is done from a character set such as Windows-1252 on a German Windows. Oooh boy, this is bad, as that isn’t at all how MKVToolNix encodes narrow strings. So what happens when an UTF-8 encoded narrow string containing non-ASCII characters is passed to std::filesystem::path
? Mangled non-ASCII characters, of course. German Umlaute, French accents, Asian characters, Emojis — doesn’t matter. Encodings don’t match, conversion does bad things, file names are messed up.
In effect this means that I must never, ever use the narrow string constructor of std::filesystem::path
on Windows except for when I know the narrow string only contains ASCII characters.
Implicit conversion
This thing wouldn’t be so bad for me if the constructors std::filesystem::path
were explicit
. They’re not, though, meaning string-to-path can hide in various places and are hard to spot. For example:
void do_stuff(const std::filesystem::path &p) {
// do something with p
}
void chunky_bacon(const std::string &file_name) {
// do chunky things
do_stuff(file_name);
// do bacon things
}
Here’s one of those conversions that absolutely must not happen on Windows, due to the implicit constructor.
Another example:
std::filesystem::path dir;
// set dir somehow
auto full_file_name = dir / sub_dir / "index.txt";
Is this OK? Well, depends on the type of sub_dir
, actually. If it is a path
already, it’s OK; if it’s a wide string, it’s OK, too, but all narrow string types (char arrays, std::string
)? Not so much. And this is really hard to spot or grep
for.[2]The "index.txt" argument is fine. Even though it’s a narrow string, it solely consists of ASCII characters that’ll convert properly to wide strings no matter what Windows’ native … Continue reading
I’d really appreciate if my compiler was able to help me out here. Having the constructors explicit
would mean neither of these examples would compile and I’d need to add an explicit conversion myself. But the C++ committee didn’t make them explicit
, probably for a reason.
Solutions
My solution was to ban the use of the constructors[3]C++20 will improve this situation with the introduction of char8_t
. The constructor taking a char8_t
-based narrow string will always convert from UTF-8, avoiding this mess.. Instead I introduced helper functions to_path()
that take both narrow & wide strings & assume narrow strings are UTF-8 encoded. These helper functions work differently depending on whether I’m compiling for Windows or other systems.
Let’s take the second example from above. I’d convert it as follows:
auto full_file_name = dir / mtx::fs::to_path(sub_dir) / "index.txt";
Ugly as sin.
Bugs in the C++ Standard Library
std::filesystem
is rather new, being added in C++17. I was prepared for bugs to rear their ugly heads. But I wasn’t prepared for how broken certain parts of the gcc standard C++ library are on Windows wrt. to UNC paths[4]I use a gcc/mingw cross-compiler from the MXE project for cross-compiling from Linux to Windows. The same issues would happen compiling with mingw on Windows itself.. A UNC path might look like this: \\server\share\sub_dir\file.txt
Without any particular order, here are a couple of issues I ran into (this is with gcc 10.2.0, the latest release at the time of writing):
- On Windows the
std::filesystem::file_size
function was implemented by calling 32-bit functions that use signed 32-bit variables for storing the file size. Needless to say, this doesn’t work too well with files larger than 2 GB. The corresponding gcc bug 95749 has already been fixed upstream, but it isn’t part of a release yet. My workaround: I cherry-picked the commit fixing the issue into my own copy of gcc I’m using for building MKVToolNix. std::filesystem::exists
doesn’t work correctly with all UNC paths. It works with e.g.\\server\share\sub_dir\file.txt
but not the share\\server\share
itself. I’ve reported this as gcc bug 99311. My workaround: I don’t usestd::filesystem::exists
; instead I test for the type I expect (e.g.std::filesystem::is_directory
orstd::filesystem::is_regular_file
) as those functions do work correctly. Even with UNC paths.- As a consequence
std::filesystem::create_directories
doesn’t work with UNC paths either. It thinks that neither\\server
nor\\server\share
exist and tries to create them. That fails, obviously, andcreate_directories
aborts at the first failure. My workaround: I NIH’ed my owncreate_directories
function that usesstd::filesystem::is_directory
for testing for existence. Only on Windows, of course. Reported in the same bug as the one above. std::filesystem::absolute
andstd::filesystem::path::is_absolute
don’t work on UNC paths. They think those paths aren’t absolute and will do funky things such as returnC:\server\share\file.txt
when asked for the absolute path to\\server\share\file.txt
. Of course I reported this, too; it’s gcc bug 99333 where I was told that it was actually a bug in thestd::filesystem::path::has_root_name
function. My workaround: I NIH’ed some more functions that treat paths starting with\\
or//
as absolute.- UNC paths using forward slashes are only supported if the program is compiled with the cygwin gcc compiler. My workaround: in my NIH’ed functions I normalize forward slashes to backslashes.
- UNC device paths starting with
\\?\…
such as\\?\C:\Path\File.mkv
or\\?\UNC\server\share\file.opus
don’t work at all. Functions such asstd::filesystem::exists()
don’t work, and even my workaround from above (usingstd::filesystem::is_directory()
orstd::filesystem::is_regular_file()
) doesn’t work with these paths. I’ve filed gcc bug 99430 for this. My workaround: at the moment I haven’t implemented one. I might replace\\?\…
with\\.\…
in my conversion functions as those seem to fare better.
As I wrote above, this is gcc 10.2.0. Your compiler might fare better, of course. I suspect that Microsoft’s Visual C++ has fewer of those Windows-specific issues, simply due to the amount of experience its developers have with Windows’s peculiarities.
Bugs in MKVToolNix
Most bugs that were actually bugs in MKVToolNix instead of the standard C++ library turned out to be due to using the implicit conversion of narrow strings to path
objects that I’ve talked about in length above.
There was one bug that was due to changed semantics between the two libraries: what happens if your path
is at the root already (e.g. C:\
on Windows) and you call parent_path()
on it? boost::filesystem
will return an empty path object whereas std::filesystem will return the same path again. This means that loops checking the file system from a point to root have to have their conditions changed. Instead of e.g. while (!path.empty())
you’ll have to do something like while (path.parent_path() != path)
. It gets even nastier wrt. to UNC paths; see this chart for details. I definitely forgot to fix a couple of these cases leading to endless loops.
macOS woes & older Linux versions
One problem on macOS is that different macOS versions have different levels of support for C++17. Until this change I used to build for macOS 10.14 “Mojave” and newer, as those supported all C++17 features I used. However, std::filesystem
, while being a C++17 feature, is only supported on macOS 10.15 “Catalina” and the current 11.0 “Big Sur”. One of the drawbacks of using current technology.
This is a bit different to older Linux distributions. Let’s take CentOS 7, a rather old distribution. I can still compile current MKVToolNix releases there by installing the latest developer toolset which comes with a current gcc
& libc++
. For macOS the compiler version doesn’t suffice, though: even if I install a recent XCode version on macOS 10.14, I cannot build code using std::filesystem
for it as the standard C++ library on macOS 10.14 doesn’t contain that functionality. I haven’t bothered investigating if it’s possible to include a newer standard C++ library itself in the MKVToolNix disk image.
And on Linux? Was it worth it?
Well… I haven’t had a single issue with so far with the conversion on Linux.
And as to the question whether or not it was worth it: hmm… meh. I really like to reduce my number of external dependencies. That is a tangible gain. It simplifies the build process & reduces build times in various situations where Boost isn’t available as I’m now down to solely using header-only libraries from Boost. And I actively take part in improving the gcc standard C++ library implementation. This is still Open Source, after all; you’re expected to give back & help out. This is how all of our projects grow.
Footnotes
↑1 | Yes, I know that’s bad as file systems on Unix aren’t guaranteed to have any type of encoding; file names might contain something that isn’t valid according to any encoding etc. etc. |
---|---|
↑2 | The "index.txt" argument is fine. Even though it’s a narrow string, it solely consists of ASCII characters that’ll convert properly to wide strings no matter what Windows’ native narrow encoding is. I hope. |
↑3 | C++20 will improve this situation with the introduction of char8_t . The constructor taking a char8_t -based narrow string will always convert from UTF-8, avoiding this mess. |
↑4 | I use a gcc/mingw cross-compiler from the MXE project for cross-compiling from Linux to Windows. The same issues would happen compiling with mingw on Windows itself. |