More tweaks to the mrbind instructions. (#5842)

Author: adalisk-emikhaylov

scripts/mrbind/README-generating.md

@@ -104,39 +104,37 @@ The resulting Python modules are created next to the MeshLib shared libraries, i
 
 * **`--trace` — enable verbose logs.** Remove to get quieter logs.
 
-* **`-B` — force a full rebuild of the bindings.** Incremental builds are not very useful, because they're not perfect and can miss changes. Use incremental builds only e.g. when you're fixing linker errors.
+* **`-B` — force a full rebuild of the bindings.** Don't remove this flag. Doing so causes Make to attempt an incremental build instead of a full rebuild, but we don't have those configured correctly, so the binding generation might be skipped even when the input headers were changed. There's one valid usecase for removing this flag: making changes to fix linker errors, such as correcting `MESHLIB_SHLIB_DIR` or `VS_MODE`; in those cases removing `-B` will redo linking instead of rebuilding the entire bindings.
 
 * **`MODE=...` — optimization** setting for the Python module:
 
-  * `release` (default) — Enable optimization, disable debug symbols. Same as what goes into the production.
+  * `release` (default) — Enable optimization, disable debug symbols. This is what goes into the production.
 
   * `debug` — disable optimizations, enable debug symbols. Use this to debug the bindings.
 
   * `none` — neither enable optimizations nor enable the debug symbols. This gives the fastest build times, useful for testing bindings locally.
 
-  You can also et entirely custom C++ compiler flags, by setting `EXTRA_CFLAGS` and `EXTRA_LDFLAGS`.
-
-  The `EXTRA_...` flags are ignored for C#, and `MODE=none` is replaced with `MODE=debug` there.
+  You can also use entirely custom C++ compiler flags, by setting `EXTRA_CFLAGS` and `EXTRA_LDFLAGS`.
 
 * **`NUM_FRAGMENTS=?? -j??` — adjust RAM usage vs build speed tradeoff.**
 
   If you're running out of RAM, reduce `-j...`.
 
-  `NUM_FRAGMENTS=??` is how many translation units the bindings are split into. `-j??` is the number of parallel build threads/processes. We have some heuristics to guess good values for this, they are printed when the script starts.
+  `NUM_FRAGMENTS=??` is how many translation units the bindings are split into. `-j??` is the number of parallel build threads/processes. We have some heuristics to guess good values for this, those values are printed when the script starts.
 
   Guessing the fastest combination isn't trivial. Usually you want to maximize threads (up to the number of cores), and then minimize the number of fragments as much as your RAM allows. The number of fragments should normally be a multiple of the number of threads.
 
 * **`PYTHON_PKGCONF_NAME=python-3.??-embed` — select Python version.** We try to guess this one. You can set this to `python3-embed` to use whatever your OS considers to be the default version.
 
-* **`ENABLE_CUDA=??` — enable or disable Cuda.** If you're building MeshLib without Cuda support, pass `ENABLE_CUDA=0` to skip the Cuda bindings too. It defaults to `1` everywhere except MacOS, where Cuda doesn't work.
+* **`ENABLE_CUDA=??` — enable or disable Cuda.** If you're building MeshLib without Cuda support, pass `ENABLE_CUDA=0` to skip the Cuda bindings. It defaults to `1` everywhere except MacOS, where Cuda doesn't work.
 
-  When this is disabled, a stub Cuda bindings are still generated, with a single function that reports that Cuda is not available.
+  When this is disabled, stub Cuda bindings are still generated, with a single function that reports that Cuda is not available.
 
 * **`BUILD_SHIMS=1` — support multiple Python versions.** This enables support for all Python versions found on the system, as opposed a single default one. See the relevant section in the [troubleshooting guide](#troubleshooting-python-bindings).
 
 * **`shims` — add support for multiple Python versions.** Same effect as `BUILD_SHIMS=1`, but instead of regenerating the bindings, this just adds the missing version support to existing bindings. This is great if you forgot the flag during the initial compilation.
 
-* **`FOR_WHEEL=1` — build for wheel packaging.** This is primarily for CI, not for local use. Indicates that you want to package the resulting module into a wheel (a Python module archive for distribution), instead of using it locally. Enabling this might prevent the module from working locally.
+* **`FOR_WHEEL=1` — build for wheel packaging.** This is primarily for CI, not for local use. Indicates that you want to package the resulting module into a wheel (a Python module archive for distribution), instead of using it locally. Enabling this might prevent the module from functioning until packaged into a wheel.
 
   This automatically enables `BUILD_SHIMS=1`, among other things.
 
@@ -148,19 +146,19 @@ The resulting Python modules are created next to the MeshLib shared libraries, i
 
   * When built locally, Python bindings only support one speific Python version by default. If you try to import them from another version, you will get errors such as the one above.
 
-  * To check which version you built for, look for shared libraried named `pybind11nonlimitedapi_meshlib_3.??` next to the Python modules. On Windows, those should be in `source/x64/Release/meshlib` (or `.../Debug/...`). The number in the filename is the Python version.
+  * To check what version you built for, look for shared libraried named `pybind11nonlimitedapi_meshlib_3.??` next to the Python modules. On Windows, those should be in `source/x64/Release/meshlib` (or `.../Debug/...`). The number in the filename is the Python version.
 
   * The easiest fix to use that Python version.
 
-    * On Windows, run e.g. `py -3.12` to use that specific version (`3.12` is our default for the bindings at the time of writing). You might need to install it first from [here](https://www.python.org/downloads/windows/).
+    * On Windows, run e.g. `py -3.12` to use that specific version (`3.12` is our default for the bindings at the time of writing). You might need to install that version first, from [here](https://www.python.org/downloads/windows/).
 
     * On Linux, just running `python3` without specifying the minor version should use the correct version by default.
 
   * Alternatively, you can add the missing shared libraries to support your preferred Python version.
 
-    * You can build them by rerunning the generation script with additional flag `shims`. This will build the libraries for all Python versions found on your system.
+    * You can build them by rerunning the generation script with the additional flag `shims`. This will build the libraries for all Python versions found on your system.
 
-      This commands only builds the libraries and does nothing else. You can use `BUILD_SHIMS=1` instead of `shims` to regenerate the bindings and build those libraries at the same time.
+      This command only builds the libraries and does nothing else. You can use `BUILD_SHIMS=1` instead of `shims` to both regenerate the bindings and build those libraries at the same time.
 
     * You can also download the prebuilt libraries from [here](https://pypi.org/project/meshlib/#files). Download the archive for your OS and extract the `pybind11nonlimitedapi_meshlib_...` shared libraries next to yours.
 
@@ -170,7 +168,7 @@ The resulting Python modules are created next to the MeshLib shared libraries, i
 
 * **`machine type x86 conflicts with x64`**
 
-  * You opened `x86 ...` VS developer command prompt, but we need `x64 Native`. Rebuild the bindings in x64 prompt.
+  * You opened `x86 ...` VS developer command prompt, but we need `x64 Native`. Rebuild the bindings in the x64 prompt.
 
 * **`undefined symbol: void __cdecl std::_Literal_zero_is_expected(void)`**
 
@@ -182,7 +180,7 @@ The resulting Python modules are created next to the MeshLib shared libraries, i
 
   * You likely used a non-default compiler when compiling MeshLib. Pass this compiler to `CXX_FOR_ABI=...` when generating Python bindings to fix the issue (e.g. `CXX_FOR_ABI=clang++-22` or `g++-15`).
 
-    MeshLib is usually compiled using a different compiler than the Python bindings (for the bindings we use a specific version of Clang, the same that is used by the parser; using the same compiler for the bindings on all platforms makes writing them easier). Therefore, we must ensure that the two compilers use the same ABI. `CXX_FOR_ABI` should be set to the compiler the ABI of which we're trying to match. (Defaults to `CXX` environment variable, or `g++` if not set.) At the moment, if `CXX_FOR_ABI` is GCC 13 or older or Clang 17 or older (note that Apple Clang uses a [different version numbering scheme](https://en.wikipedia.org/wiki/Xcode#Xcode_15.0_-_(since_visionOS_support)_2)), we pass `-fclang-abi-compat=17` to our Clang 18 or newer (which is used to compile the bindings). This flag *disables* mangling of `requires` constraints into function names. If we guess incorrectly, you'll get undefined references to functions with `requires` constraints on them.
+    MeshLib is usually compiled using a different compiler than the Python bindings (for the bindings we use a specific version of Clang, the same that is used by the parser; using the same compiler for the bindings on all platforms makes writing them easier). Therefore, we must ensure that the two compilers use the same ABI. `CXX_FOR_ABI` should be set to the compiler the ABI of which we're trying to match. (Defaults to the `CXX` environment variable, or `g++` if not set.) At the moment, if `CXX_FOR_ABI` is GCC 13 or older or Clang 17 or older (note that Apple Clang uses a [different version numbering scheme](https://en.wikipedia.org/wiki/Xcode#Xcode_15.0_-_(since_visionOS_support)_2)), we pass `-fclang-abi-compat=17` to our Clang 18 or newer (which is used to compile the bindings). This flag *disables* mangling of `requires` constraints into the function names. If we guess incorrectly, you'll get undefined references to functions with `requires` constraints on them.
 
 * **Importing the wheel segfaults on MacOS**
 
@@ -203,7 +201,7 @@ The resulting Python modules are created next to the MeshLib shared libraries, i
 
 Running our script generates the code for the bindings, at `source/MeshLibC2` and `source/MeshLibC2Cuda`.
 
-Then you must build MeshLib with a special CMake flag, which will build the generated bindings.
+Then you must build MeshLib with a special CMake flag, which will build the generated bindings in addition to the rest of the MeshLib.
 
 ### Windows
 
@@ -271,8 +269,10 @@ The steps below both generate the C# code (at `MeshLib/source/MRDotNet2`) and co
 
 ### Less common flags for the generator script
 
-* **Selecting MRBind installation:** if you installed MRBind to a non-default location (the default is `./MeshLib/mrbind`), you must pass this location to `MRBIND_SOURCE=path/to/mrbind`.
+* **Selecting MRBind installation:** if you installed MRBind to a non-default location (the default is `./thirdparty/mrbind`), you must pass this location to `MRBIND_SOURCE=path/to/mrbind`.
 
     Additionally, if the MRBind binary is not at `$MRBIND_SOURCE/build/mrbind`, you must pass `MRBIND_EXE=...` (path to the executable itself, not its directory).
 
+    For C and C# (but not Python), if you set `MRBIND_EXE`, then you can skip `MRBIND_SOURCE`.
+
 You can find more undocumented flags/variables in `generate.mk`.