mirror of
https://github.com/microsoft/mimalloc.git
synced 2025-05-03 14:09:31 +03:00
update readme to use mimalloc.dll (instead of mimalloc-override.dll)
This commit is contained in:
Daan Leijen
parent
4b7313914e
commit
4ed44f9621
2 changed files with 48 additions and 43 deletions
|
|
@ -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 <exe>` 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=<p> use <p> as a postfix to the mimalloc dll (default is 'override')
|
||||
e.g. use --postfix=override-debug to link with mimalloc-override-debug.dll
|
||||
--postfix=<p> use <p> as a postfix to the mimalloc dll.
|
||||
e.g. use --postfix=debug to link with mimalloc-debug.dll
|
||||
|
||||
notes:
|
||||
Without '--inplace' an injected <exe> is generated with the same name ending in '-mi'.
|
||||
|
|
|
|||
53
readme.md
53
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
|
||||
|
||||
<span id="override_on_windows">Dynamically overriding on mimalloc on Windows</span>
|
||||
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 <exe>` 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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## Static override
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue