Skip to content

USAGE.md

Latest commit

 

History

History
155 lines (120 loc) · 6.5 KB

USAGE.md

File metadata and controls

155 lines (120 loc) · 6.5 KB
Raw

Usage

Initialization

ManagedWimLib requires the explicit loading of a wimlib library.

You must call Wim.GlobalInit() before using ManagedWimLib.

To configure behaviors of wimlib, pass InitFlags to Wim.GlobalInit().

Init Code Snippet

Please put this code snippet in your application init code:

WARNING: The caller process and callee library must have the same architecture!

On .NET/.NET Core

public static void InitNativeLibrary()
{
    string libBaseDir = AppDomain.CurrentDomain.BaseDirectory;
    string libDir = "runtimes";
    if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
        libDir = Path.Combine(libDir, "win-");
    else if (RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
        libDir = Path.Combine(libDir, "linux-");
    else if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
        libDir = Path.Combine(libDir, "osx-");

    switch (RuntimeInformation.ProcessArchitecture)
    {
        case Architecture.X86:
            libDir += "x86";
            break;
        case Architecture.X64:
            libDir += "x64";
            break;
        case Architecture.Arm:
            libDir += "arm";
            break;
        case Architecture.Arm64:
            libDir += "arm64";
            break;
    }
    libDir = Path.Combine(libDir, "native");

    // Some platforms require a native library custom path to be an absolute path.
    string libPath = null;
    if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
        libPath = Path.Combine(libBaseDir, libDir, "libwim-15.dll");
    else if (RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
        libPath = Path.Combine(libBaseDir, libDir, "libwim.so");
    else if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
        libPath = Path.Combine(libBaseDir, libDir, "libwim.dylib");

    if (libPath == null)
        throw new PlatformNotSupportedException($"Unable to find native library.");
    if (!File.Exists(libPath))
        throw new PlatformNotSupportedException($"Unable to find native library [{libPath}].");

    Wim.GlobalInit(libPath, InitFlags.None);
}

On .NET Framework

public static void InitNativeLibrary()
{
    string arch = null;
    switch (RuntimeInformation.ProcessArchitecture)
    {
        case Architecture.X86:
            arch = "x86";
            break;
        case Architecture.X64:
            arch = "x64";
            break;
        case Architecture.Arm64:
            arch = "arm64";
            break;
    }
    string libPath = Path.Combine(arch, "libwim-15.dll");

    if (!File.Exists(libPath))
        throw new PlatformNotSupportedException($"Unable to find native library [{libPath}].");

    Wim.GlobalInit(libPath, InitFlags.None);
}

Embedded binary

ManagedWimLib comes with sets of binaries of wimlib 1.14.4. They will be copied into the build directory at build time.

On .NET/.NET Core & .NET Standard

Platform Minimum Target Binary License C Runtime
Windows x86 Windows 7 SP1 $(OutDir)\runtimes\win-x86\native\libwim-15.dll LGPLv3 Universal CRT
Windows x64 Windows 7 SP1 $(OutDir)\runtimes\win-x64\native\libwim-15.dll LGPLv3 Universal CRT
Windows arm64 Windows 7 SP1 $(OutDir)\runtimes\win-arm64\native\libwim-15.dll LGPLv3 Universal CRT
Linux x64 Ubuntu 20.04 $(OutDir)\runtimes\linux-x64\native\libwim.so LGPLv3 (w/o NTFS-3G) glibc
Linux armhf Ubuntu 20.04 $(OutDir)\runtimes\linux-arm\native\libwim.so LGPLv3 (w/o NTFS-3G) glibc
Linux arm64 Ubuntu 20.04 $(OutDir)\runtimes\linux-arm64\native\libwim.so LGPLv3 (w/o NTFS-3G) glibc
macOS x64 macOS 11 $(OutDir)\runtimes\osx-x64\native\libwim.dylib LGPLv3 (w/o NTFS-3G) libSystem
macOS arm64 macOS 11 $(OutDir)\runtimes\osx-arm64\native\libwim.dylib LGPLv3 (w/o NTFS-3G) libSystem
  • Linux binaries are not portable by nature. Included binaries may not work on your distribution.
    • On Linux, wimlib depends on system-installed libfuse3-3.
  • If you call Wim.GlobalInit() without the libPath parameter on Linux or macOS, ManagedWimLib will search for system-installed wimlib.
  • Linux binaries were compiled without NTFS-3G/fuse support to make them LGPLv3-licensed.
    • If you want NTFS-3G/fuse functionality, load the system-installed library or prepare library yourself. Make sure your program is compatible with GPLv3!

On .NET Framework

Platform Binary License C Runtime
Windows x86 $(OutDir)\x86\libwim-15.dll LGPLv3 Universal CRT
Windows x64 $(OutDir)\x64\libwim-15.dll LGPLv3 Universal CRT
Windows arm64 $(OutDir)\arm64\libwim-15.dll LGPLv3 Universal CRT
  • Create an empty file named ManagedWimLib.Precompiled.Exclude in the project directory to prevent a copy of the package-embedded binary.

Build Command

Platform Binary Source Dependency
Windows x86 Compiled with MSYS2 and llvm-mingw -
Windows x64 Compiled with MSYS2 and llvm-mingw -
Windows arm64 Compiled with MSYS2 and llvm-mingw -
Linux x64 Compiled without NTFS-3G/fuse3 -
Linux armhf Compiled without NTFS-3G/fuse3 -
Linux arm64 Compiled without NTFS-3G/fuse3 -
macOS x64 Compiled without NTFS-3G/fuse3 -
macOS arm64 Compiled without NTFS-3G/fuse3 -

Custom binary

To use the custom wimlib binary instead, call Wim.GlobalInit() with a path to the custom binary.

Cleanup

To unload the wimlib library explicitly, call Wim.GlobalCleanup().

API

ManagedWimLib provides a set of APIs matched to its original. Most of the use cases follow this flow:

  1. Create Wim instance with Wim.OpenWim()
  2. Do your job by calling APIs of your interest.
  3. Clean up Wim instance with the Disposable pattern.

ManagedWimLib.Tests provides a lot of examples of how to use ManagedWimLib.