Tag Archives: Programming

Converting a C++ code base from boost::filesystem to std::filesystem

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):

  1. 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.
  2. 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 use std::filesystem::exists; instead I test for the type I expect (e.g. std::filesystem::is_directory or std::filesystem::is_regular_file) as those functions do work correctly. Even with UNC paths.
  3. 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, and create_directories aborts at the first failure. My workaround: I NIH’ed my own create_directories function that uses std::filesystem::is_directory for testing for existence. Only on Windows, of course. Reported in the same bug as the one above.
  4. std::filesystem::absolute and std::filesystem::path::is_absolute don’t work on UNC paths. They think those paths aren’t absolute and will do funky things such as return C:\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 the std::filesystem::path::has_root_name function. My workaround: I NIH’ed some more functions that treat paths starting with \\ or // as absolute.
  5. 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.
  6. UNC device paths starting with \\?\… such as \\?\C:\Path\File.mkv or \\?\UNC\server\share\file.opus don’t work at all. Functions such as std::filesystem::exists() don’t work, and even my workaround from above (using std::filesystem::is_directory() or std::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

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.

MKVToolNix v5.7.0 released

Hey,

I’ve released v5.7.0. It’s purely a bug fix release. The most important bug fixed was the excessive CPU usage during muxing.

Unfortunately the bug fix for the CPU usage brought on a new bug. Due to timing issues between the child process (mkvmerge) ending and the GUI reading its output the very last line(s) of mkvmerge’s output might not be shown by mmg. The progress bar might also not be updated to full. However, this is purely a cosmetic issue: the output file has been written completely by that point. See also issue 774.

Here are the usual links: the home page, the source code and the Windows installer and 7zip archive.

All of the binaries that I provide myself are already available.

Here’s the full ChangeLog since release 5.6.0:

  • 2012-07-08 Moritz Bunkus <moritz@bunkus.org>
    • Released v5.7.0.
    • mmg: bug fix: mmg will no longer print false warnings about a chapter UID not being unique. Fixes #760.
    • mkvmerge, mkvpropedit, mmg: bug fix: All tools can now deal with 64bit UID values (chapter UIDs, edition UIDs etc).
    • mkvmerge: new feature: If "splitting by parts" is active and the last split part has a finite end point then mkvmerge will finish muxing after the last part has been completed. Implements #768.
  • 2012-06-29 Moritz Bunkus <moritz@bunkus.org>
    • mkvmerge: bug fix: The DTS and TrueHD packetizers were not flushed correctly. In some rare circumstances this could lead to mkvmerge aborting with an error message about the packet queue not being empty at the end of the muxing process. Fixes #772.
  • 2012-06-17 Moritz Bunkus <moritz@bunkus.org>
    • mmg, mkvinfo’s GUI, all .exes: enhancement: Added new icons by Ben Humpert based on the ones by Eduard Geier (see AUTHORS).
  • 2012-06-05 Moritz Bunkus <moritz@bunkus.org>
    • mkvmerge: bug fix: Fixed handling of tracks in QuickTime/MP4 files with a constant sample size. This fixes the other reason for the "constant sample size and variable duration not supported" error. Fixes issue 764.
    • mkvmerge: bug fix: Tracks in QuickTime/MP4 files with empty chunk offset tables (STCO and CO64 atoms) are ignored. This fixes one of the reasons for the "constant sample size and variable duration not supported" error.
  • 2012-06-03 Moritz Bunkus <moritz@bunkus.org>
    • mmg: bug fix: Fixed mmg’s excessive CPU usage during muxing.
  • 2012-06-01 Moritz Bunkus <moritz@bunkus.org>
    • mkvmerge: bug fix: Reading DTS from AVI files often resulted in the error message that DTS headers could not be found in the first frames. This has been fixed. Fixes issue 759.
  • 2012-05-31 Moritz Bunkus <moritz@bunkus.org>
    • Documentation: Updated the cross-compilation guide and fixed the "setup_cross_compilation_env.sh" script.

Have fun.

MKVToolNix v5.0.1 released

Hey,

I’ve released mkvtoolnix v5.0.1. It’s a release with a few improvements/bug fixes and one important fix for a regression introduced in v5.0.0 regarding PGS subtitles.

There were no changes that concern package maintainers.

Here are the usual links: the home page, the source code and the Windows installer and 7zip archive.

All of the binaries that I provide myself are already available.

Here’s the full ChangeLog since release 5.0.0:

  • 2011-10-09 Moritz Bunkus <moritz@bunkus.org>
    • Released v5.0.1.
  • 2011-10-08 Moritz Bunkus <moritz@bunkus.org>
    • build system: Updated the Debian/Ubuntu files to debhelper v7/quilt 3.0 format.
    • mkvmerge: enhancement: Implemented support for yet another way of storing EAC3 and DTS in MPEG transport streams.
  • 2011-10-05 Moritz Bunkus <moritz@bunkus.org>
    • mkvinfo: bug fix: Track information was not reset when opening more than one file in the GUI.
  • 2011-10-03 Moritz Bunkus <moritz@bunkus.org>
    • mkvmerge: bug fix: The PGS subtitle output module was not outputting any packet in certain cases due to uninitialized variables.
  • 2011-09-27 Moritz Bunkus <moritz@bunkus.org>
    • mkvmerge: bug fix: Fixed mkvmerge not finding any track in TS streams whose first PMT packet could not be parsed (e.g. invalid CRC).
    • mkvmerge: bug fix: Fixed detection of TS streams that only contain one PAT or PMT packet within the first few KB but no others within the first 10 MB.

Have fun.

Managing tasks with Remember The Milk and Emacs

These days I’ve got a lot of stuff to do. There are basics like cleaning the flat or fertilizing plants. There are things connected to my hobbies: remembering to fix a bug or implement a feature in my programs, answering forum posts and emails, practice my choir pieces. And then there’s everything going on at my job: do this for a customer, implement that in a program, and that other internal thing has to be remembered as well.

Too bad I’m forgetting more of those things than I’d like to admit. Fortunately someone invented TODO lists for people like myself.

I’m using the excellent Remember The Milk service (short: RTM) for this kind of thing. The one thing I find absolutely fascinating about RTM is its fast, single keystroke based web interface. Being an avid Emacs user as well I always wanted to be able to access RTM directly from Emacs in nearly the same way. Web searches only turned up an integration into Org mode, which I don’t use and don’t want to learn, I decided to write this myself: SimpleRTM – An Interactive Emacs mode for Remember The Milk. The code is over on github, and installation is trivial.

Have fun.