From 4ed44f96210c71f6d1945ae950387bc262a75f20 Mon Sep 17 00:00:00 2001 From: Daan Leijen Date: Fri, 20 Dec 2024 12:52:34 -0800 Subject: [PATCH] update readme to use mimalloc.dll (instead of mimalloc-override.dll) --- bin/readme.md | 38 +++++++++++++++++------------------ readme.md | 55 ++++++++++++++++++++++++++++----------------------- 2 files changed, 49 insertions(+), 44 deletions(-) diff --git a/bin/readme.md b/bin/readme.md index d6c3775ff..bc115ce16 100644 --- a/bin/readme.md +++ b/bin/readme.md @@ -9,20 +9,20 @@ There are four requirements to make the overriding work well: 1. Use the C-runtime library as a DLL (using the `/MD` or `/MDd` switch). -2. Link your program explicitly with the `mimalloc-override.lib` export library for - the `mimalloc-override.dll` -- which contains all mimalloc functionality. - To ensure the `mimalloc-override.dll` is actually loaded at run-time it is easiest +2. Link your program explicitly with the `mimalloc.lib` export library for + the `mimalloc.dll` -- which contains all mimalloc functionality. + To ensure the `mimalloc.dll` is actually loaded at run-time it is easiest to insert some call to the mimalloc API in the `main` function, like `mi_version()` (or use the `/include:mi_version` switch on the linker, or - use `#pragma comment(linker, "/include:mi_version")` in some source file). - See the `mimalloc-override-test` project for an example on how to use this. + similarly, `#pragma comment(linker, "/include:mi_version")` in some source file). + See the `mimalloc-test-override` project for an example on how to use this. 3. The `mimalloc-redirect.dll` must be put in the same folder as the main - `mimalloc-override.dll` at runtime (as it is a dependency of that DLL). + `mimalloc.dll` at runtime (as it is a dependency of that DLL). The redirection DLL ensures that all calls to the C runtime malloc API get - redirected to mimalloc functions (which reside in `mimalloc-override.dll`). + redirected to mimalloc functions (which reside in `mimalloc.dll`). -4. Ensure the `mimalloc-override.dll` comes as early as possible in the import +4. Ensure the `mimalloc.dll` comes as early as possible in the import list of the final executable (so it can intercept all potential allocations). You can use `minject -l ` to check this if needed. @@ -37,8 +37,8 @@ redirected. ### Other Platforms -You always link with `mimalloc-override.dll` but for different platforms you may -need a specific `mimalloc-redirect.dll`: +You always link with `mimalloc.dll` but for different platforms you may +need a specific redirection DLL: - __x64__: `mimalloc-redirect.dll`. - __x86__: `mimalloc-redirect32.dll`. Use for older 32-bit Windows programs. @@ -47,12 +47,12 @@ need a specific `mimalloc-redirect.dll`: mode on Windows arm64. Unfortunately we cannot run x64 code emulated on Windows arm64 with the x64 mimalloc override directly (since the C runtime always uses `arm64ec`). Instead: 1. Build the program as normal for x64 and link as normal with the x64 - `mimalloc-override.lib` export library. - 2. Now separately build `mimalloc-override.dll` in `arm64ec` mode and _overwrite_ your - previous (x64) `mimalloc-override.dll` -- the loader can handle the mix of arm64ec + `mimalloc.lib` export library. + 2. Now separately build `mimalloc.dll` in `arm64ec` mode and _overwrite_ your + previous (x64) `mimalloc.dll` -- the loader can handle the mix of arm64ec and x64 code. Now use `mimalloc-redirect-arm64ec.dll` to match your new - arm64ec `mimalloc-override.dll`. The main program stays as is and can be fully x64 - or contain more arm64ec modules. At runtime, the arm64ec `mimalloc-override.dll` will + arm64ec `mimalloc.dll`. The main program stays as is and can be fully x64 + or contain more arm64ec modules. At runtime, the arm64ec `mimalloc.dll` will run with native arm64 instructions while the rest of the program runs emulated x64. [arm64ec]: https://learn.microsoft.com/en-us/windows/arm/arm64ec @@ -60,11 +60,11 @@ need a specific `mimalloc-redirect.dll`: ### Minject -We cannot always re-link an executable with `mimalloc-override.dll`, and similarly, we +We cannot always re-link an executable with `mimalloc.dll`, and similarly, we cannot always ensure that the DLL comes first in the import table of the final executable. In many cases though we can patch existing executables without any recompilation if they are linked with the dynamic C runtime (`ucrtbase.dll`) -- just put the -`mimalloc-override.dll` into the import table (and put `mimalloc-redirect.dll` in the same +`mimalloc.dll` into the import table (and put `mimalloc-redirect.dll` in the same directory) Such patching can be done for example with [CFF Explorer](https://ntcore.com/?page_id=388). The `minject` program can also do this from the command line @@ -86,8 +86,8 @@ options: -l --list only list imported modules -i --inplace update the exe in-place (make sure there is a backup!) -f --force always overwrite without prompting - --postfix=

use

as a postfix to the mimalloc dll (default is 'override') - e.g. use --postfix=override-debug to link with mimalloc-override-debug.dll + --postfix=

use

as a postfix to the mimalloc dll. + e.g. use --postfix=debug to link with mimalloc-debug.dll notes: Without '--inplace' an injected is generated with the same name ending in '-mi'. diff --git a/readme.md b/readme.md index 564ac6d7a..11f62da47 100644 --- a/readme.md +++ b/readme.md @@ -428,43 +428,48 @@ Note that certain security restrictions may apply when doing this from the [shell](https://stackoverflow.com/questions/43941322/dyld-insert-libraries-ignored-when-calling-application-through-bash). -### Dynamic Override on Windows +# Windows Override Dynamically overriding on mimalloc on Windows -is robust and has the particular advantage to be able to redirect all malloc/free calls that go through -the (dynamic) C runtime allocator, including those from other DLL's or libraries. -As it intercepts all allocation calls on a low level, it can be used reliably +is robust and has the particular advantage to be able to redirect all malloc/free calls +that go through the (dynamic) C runtime allocator, including those from other DLL's or +libraries. As it intercepts all allocation calls on a low level, it can be used reliably on large programs that include other 3rd party components. -There are four requirements to make the overriding work robustly: +There are four requirements to make the overriding work well: 1. Use the C-runtime library as a DLL (using the `/MD` or `/MDd` switch). -2. Link your program explicitly with `mimalloc-override.dll` library. - To ensure the `mimalloc-override.dll` is loaded at run-time it is easiest to insert some - call to the mimalloc API in the `main` function, like `mi_version()` - (or use the `/INCLUDE:mi_version` switch on the linker). See the `mimalloc-override-test` project - for an example on how to use this. -3. The [`mimalloc-redirect.dll`](bin) (or `mimalloc-redirect32.dll`) must be put - in the same folder as the main `mimalloc-override.dll` at runtime (as it is a dependency of that DLL). - The redirection DLL ensures that all calls to the C runtime malloc API get redirected to - mimalloc functions (which reside in `mimalloc-override.dll`). -4. Ensure the `mimalloc-override.dll` comes as early as possible in the import + +2. Link your program explicitly with the `mimalloc.lib` export library for the `mimalloc.dll`. + (which must be compiled with `-DMI_OVERRIDE=ON`, which is the default though). + To ensure the `mimalloc.dll` is actually loaded at run-time it is easiest + to insert some call to the mimalloc API in the `main` function, like `mi_version()` + (or use the `/include:mi_version` switch on the linker command, or + similarly, `#pragma comment(linker, "/include:mi_version")` in some source file). + See the `mimalloc-test-override` project for an example on how to use this. + +3. The `mimalloc-redirect.dll` must be put in the same folder as the main + `mimalloc.dll` at runtime (as it is a dependency of that DLL). + The redirection DLL ensures that all calls to the C runtime malloc API get + redirected to mimalloc functions (which reside in `mimalloc.dll`). + +4. Ensure the `mimalloc.dll` comes as early as possible in the import list of the final executable (so it can intercept all potential allocations). + You can use `minject -l ` to check this if needed. For best performance on Windows with C++, it is also recommended to also override the `new`/`delete` operations (by including -[`mimalloc-new-delete.h`](include/mimalloc-new-delete.h) +[`mimalloc-new-delete.h`](../include/mimalloc-new-delete.h) a single(!) source file in your project). The environment variable `MIMALLOC_DISABLE_REDIRECT=1` can be used to disable dynamic -overriding at run-time. Use `MIMALLOC_VERBOSE=1` to check if mimalloc was successfully redirected. - -We cannot always re-link an executable with `mimalloc-override.dll`, and similarly, we cannot always -ensure the the DLL comes first in the import table of the final executable. -In many cases though we can patch existing executables without any recompilation -if they are linked with the dynamic C runtime (`ucrtbase.dll`) -- just put the `mimalloc-override.dll` -into the import table (and put `mimalloc-redirect.dll` in the same folder) -Such patching can be done for example with [CFF Explorer](https://ntcore.com/?page_id=388) or -the [`minject`](bin) program. +overriding at run-time. Use `MIMALLOC_VERBOSE=1` to check if mimalloc was successfully +redirected. + +For different platforms than x64, you may need a specific [redirection dll](bin). +Furthermore, we cannot always re-link an executable or ensure `mimalloc.dll` comes +first in the import table. In such cases the [`minject`](bin) tool can be used +to patch the executable's import tables. + ## Static override