wimlib

These are wimlib Rust bindings. wimlib is a C library for creating, modifying, extracting and mounting files in the Windows Imaging Format (WIM files). It provides a free and corss-platform alternative to Microsoft's WIMGAPI, ImageX and DISM.

C library link: https://wimlib.net

Basic WIM handling concepts

Wimlib bindings wrap up a WIM file in a opaque [Wim] type. There are two ways to create its instance

1. [WimLib::open_wim] opens an on-disk WIM file and creates a [Wim] for it
2. [WimLib::create_new_wim] creates a new [Wim] that initially contains no images and does not yet have a backing on-disk file

[Wim] contains zero or more independent directory trees called images. Images may be extracted, added, deleted, exported, and updated using various API functions. You can select these images using [Wim::select_image] and [Wim::select_all_images] as most of methods using them are under structure [Image].

Changes made to a WIM represented by a [Wim] have no persistent effect until the WIM is actually written to an on-disk file. This can be done using [Image::write], but if the WIM was originally opened using [WimLib::open_wim], then [Wim::overwrite] can be used instead.

wimlib's API is designed to let you combine functions to accomplish tasks in a flexible way. Here are some example sequences of function calls:

Apply an image from a WIM file, similar to the command-line program wimapply

1. [WimLib::open_wim]
2. [Image::extract]

Capture an image into a new WIM file, similar to wimcapture:

1. [WimLib::create_new_wim]
2. [Wim::add_image]
3. [Image::write]

Append an image to an existing WIM file, similar to wimappend:

1. [WimLib::open_wim]
2. [Wim::add_image]
3. [Wim::overwrite]

Delete an image from an existing WIM file, similar to wimdelete:

1. [WimLib::open_wim]
2. [Image::delete_self]
3. [Wim::overwrite]

Export an image from one WIM file to another, similar to wimexport:

1. [WimLib::open_wim] (on source)
2. [WimLib::open_wim] (on destination)
3. [Image::export]
4. [Wim::overwrite] (on destination)

The API also lets you do things the command-line tools don't directly allow. For example, you could make multiple changes to a WIM before efficiently committing the changes with just one call to [Wim::overwrite]. Perhaps you want to both delete an image and add a new one; or perhaps you want to customize an image with [Wim::overwrite] after adding it. All these use cases are supported by the API.

You can also visit documentation of modules in [wim] module for detailed documentation of certain scopes.

Additional information and features

Mounting WIM images

See Mounting WIM images.

Progress Messages

See [progress::ProgressMsg].

Non-standalone WIMs

See Creating and handling non-standalone WIMSs.

Pipable WIMs

wimlib supports a special »pipable« WIM format which unfortunately is not compatible with Microsoft's software. To create a pipable WIM, call [Image::write], [Image::write_to_file], or [Wim::overwrite] with [WriteFlags::PIPABLE] specified. Pipable WIMs are pipable in both directions, so [Image::write_to_file] can be used to write a pipable WIM to a pipe, and [WimLib::extract_image_from_pipe] can be used to apply an image from a pipable WIM. wimlib can also transparently open and operate on pipable WIM s using a seekable file descriptor using the regular function calls (e.g. [WimLib::open_wim], [Image::extract]).

See the documentation for the –pipable flag of wimcapture for more information about pipable WIMs.

Custom allocation functions

WimLib allows settings custom allocator functions. I would really like to make [wimlib][crate] bindings support this feature, especially by automatically hooking that to users global allocator, but…

1. It uses C-style allocation APIs, which are very basic compared to Rusts and inherently incompatible. Rust's [allocation APIs][std::alloc::GlobalAlloc] require knowing [Layout][std::alloc::Layout]. which includes alignment. malloc requires only size. For dallocation memory, C's API is even more basic. Just provide a pointer. No size, no alignment. This can be bypassed by having some fixed alignment and allocating a bit more to store the size information and return shifted pointer. Tried this and it lead me to…

2. wimlib calls libc's realpath. That one allocates using libc's allocation facilities (malloc) but wimlib then deallocates the memory by user provided deallocation function. And as my deallocation trick shifted pointer back to the header and tried to read it, it made Address-san sad (of course it did). I could possibly try to do evil things like catch SIGSEGV and then try again with libc::free. Or somehow hook the library and override libc's allocation facilities. But I am (at least for now) not willing to risk such fragile solution.