[gjs/mozjs91: 5/13] README.MSVC.md: Update SpiderMonkey build instructions

[Philip Chimento <pchimento src gnome org>]

commit b95635a35adf92a28e0cc48fe2e2d43ffe6899ce
Author: Chun-wei Fan <fanchunwei src gnome org>
Date:   Thu Aug 12 14:37:10 2021 +0800

    README.MSVC.md: Update SpiderMonkey build instructions
    
    SpiderMonkey 91.x changed its build system significantly, so update the
    instructions accordingly so that people will know how to build
    SpiderMonkey 91.x.

 README.MSVC.md | 125 +++++++++++++++++++++++++++++++--------------------------
 1 file changed, 67 insertions(+), 58 deletions(-)
---
diff --git a/README.MSVC.md b/README.MSVC.md
index 79fa9a8fa..9cf51a876 100644
--- a/README.MSVC.md
+++ b/README.MSVC.md
@@ -50,42 +50,70 @@ FireFox (ESR) or Thunderbird 91.x sources, in $(srcroot)/js.
 Please do note that the build must be done carefully, in addition to the
 official instructions that are posted on the Mozilla website:
 
-https://developer.mozilla.org/en-US/docs/Mozilla/Projects/SpiderMonkey/Build_Documentation
+https://firefox-source-docs.mozilla.org/js/build.html
+
+You will need to create a .mozconfig file that will describe your build
+options for the build in the root directory of the Firefox/ThunderBird 91.x
+sources.  A sample content of the .mozconfig file can be added as follows:
+
+```
+ac_add_options --enable-application=js
+mk_add_options MOZ_MAKE_FLAGS=-j12
+mk_add_options JS_STANDALONE=1
+ac_add_options --target=x86_64-pc-mingw32
+ac_add_options --host=x86_64-pc-mingw32
+ac_add_options --disable-tests
+ac_add_options --enable-optimize
+ac_add_options --disable-debug
+ac_add_options --disable-jemalloc
+ac_add_options --prefix=c:/software.b/mozjs91.bin
+```
+
+An explanation of the lines above:
+*  `ac_add_options --enable-application=js`: This line is absolutely required, to build SpiderMonkey 
standalone
+*  `mk_add_options MOZ_MAKE_FLAGS=-j12`:  MOZ_MAKE_FLAGS=-jX means X number of parallel processes for the 
build
+*  `mk_add_options JS_STANDALONE=1`: Enforce building SpiderMonkey standalone (could be optional)
+*  `ac_add_options --target=x86_64-pc-mingw32`: Target architecture, replace `x86_64` with `aarch64` for 
ARM64 builds, and with `i686` for 32-bit x86 builds.
+*  `ac_add_options --host=x86_64-pc-mingw32`: Use this as-is, unless building on a 32-bit compiler (replace 
`x86_64` with `i686`; not recommended)
+*  `ac_add_options --disable-tests`: Save some build time
+*  `ac_add_options --enable-optimize`: Use for release builds of SpiderMonkey.  Use `--disable-optimize` 
instead if building with `--enable-debug`
+*  `ac_add_options --enable-debug`: Include debugging functions, for debug builds.  Use `--disable-debug` 
instead if building with `--enable-optimize`
+*  `ac_add_options --disable-jemalloc`: This is absolutely needed, otherwise GJS will not build and run 
correctly
+*  `ac_add_options --prefix=c:/software.b/mozjs91.bin`: Some installation path, change as needed
+
+If your GJS build crashes upon launch, use Dependency Walker to ensure that
+mozjs-91.dll does not depend on mozglue.dll!  If it does, or if GJS fails to
+link with missing arena_malloc() and friends symbols, you have built SpiderMoney
+incorrectly and will need to rebuild SpiderMonkey (with the build options as
+noted above) and retry the build.
+
+Please also check that `--enable-optimize` is *not* used with `--enable-debug`.
+You should explicitly enable one and disable the other, as `--enable-debug`
+will make the resulting build depend on the debug CRT, and mixing between
+the release and debug CRT in the same DLL is often a sign of trouble when using
+with GJS, meaning that you will need to rebuild SpiderMonkey with the appropriate
+options set in your `.mozconfig` file.  Please note that for SpiderMonkey builds, 
+PDB files are generated even if `--disable-debug` is used.
+
+You will need to check that `js-config.h` has the correct entries that correspond
+to your SpiderMonkey build, especially the following items:
+
+*  `JS_64BIT`, `JS_PUNBOX64`: Should be defined for 64-bit builds, not 32-bit builds
+*  `JS_NUNBOX32`: Should be defined for 32-bit builds, not 64-bit builds
+*  `JS_DEBUG`, `JS_GC_ZEAL`: Should only be defined if `--enable-debug` is used
 
-For the configuration step, you will need to run the following:
-
-(64-bit/x64 builds)
-JS_STANDALONE=1 $(mozjs_srcroot)/js/src/configure --enable-nspr-build --host=x86_64-pc-mingw32 
--target=x86_64-pc-mingw32 --prefix=<some_prefix> --disable-jemalloc 
--with-libclang-path=<full_path_to_directory_containing_libclang_dll> 
--with-clang-path=<full_path_to_directory_containing_clang_exe>
-
-(32-bit builds)
-JS_STANDALONE=1 $(mozjs_srcroot)/js/src/configure --enable-nspr-build --host=i686-pc-mingw32 
--target=i686-pc-mingw32 --prefix=<some_prefix> --disable-jemalloc 
--with-libclang-path=<full_path_to_directory_containing_libclang_dll> 
--with-clang-path=<full_path_to_directory_containing_clang_exe>
-
-Notice that "JS_STANDALONE=1" and "--disable-jemalloc" are absolutely required,
-otherwise GJS will not build/run correctly.  If your GJS build crashes upon
-launch, use Dependency Walker to ensure that mozjs-91.dll does not depend on
-mozglue.dll!  If it does, or if GJS fails to link with missing arena_malloc() and
-friends symbols, you have built SpiderMoney incorrectly and will need to rebuild
-SpiderMonkey (with the build options as noted above) and retry the build.
 Note in particular that a mozglue.dll should *not* be in $(builddir)/dist/bin,
 although there will be a mozglue.lib somewhere in the build tree (which, you can
 safely delete after building SpiderMonkey).  The --host=... and --target=...
 are absolutely required for all builds, as per the Mozilla's SpiderMonkey build
 instructions, as Rust is being involved here.
 
-You may want to pass in --disable-js-shell to not build the JS
-shell that comes with SpiderMonkey to save time, and perhaps
-use --with-system-nspr (instead of the --enable-nspr-build as
-above), --with-system-zlib and --with-system-icu if you know
-what you are doing and that their pkg-config files
-(or headers/LIB's) can be found directly or using configuration 
-options, to further save time.
-
-After the configuration finishes successfully, you may run 'mozmake' and
-'mozmake install' as you would for a standard SpiderMonkey build.  If
-'mozmake install' does not work for you for some reason, the DLLs you 
-need and js.exe (if you did not pass in --disable-js-shell) can be 
-found in $(buildroot)/dist/bin (you need *all* the DLLs, make sure 
-that there is no mozglue.dll, otherwise you will need to redo your 
+Run `./mach build` to carry out the build, and then `./mach build install` to copy
+the completed build to the directory specified by `ac_add_options --prefix=xxx`.
+
+If `./mach build install` does not work for you for some reason, the DLLs you 
+need and js.exe can be found in $(buildroot)/dist/bin (you need *all* the DLLs,
+make sure that there is no mozglue.dll, otherwise you will need to redo your 
 build as noted above), and the required headers are found in
 $(buildroot)/dist/include.  Note that for PDB files and .lib files, 
 you will need to search for them in $(buildroot),
@@ -93,9 +121,6 @@ where the PDB file names match the filenames for the DLLs/EXEs in
 $(buildroot)/dist/bin, and you will need to look for the following .lib files:
 -mozjs-91.lib
 -js_static.lib (optional)
--nspr4.lib (optional, recommended for future use, if --enable-nspr-build is used)
--plc4.lib (optional, recommended for future use, if --enable-nspr-build is used)
--plds4.lib (optional, recommended for future use, if --enable-nspr-build is used)
 
 You may want to put the .lib's and DLLs/EXEs into $(PREFIX)\lib and 
 $(PREFIX)\bin respectively, and put the headers into
@@ -104,31 +129,13 @@ $(PREFIX)\include\mozjs-91 for convenience.
 You will need to place the generated mozjs-91.pc pkg-config file into
 $(PREFIX)\lib\pkgconfig and ensure that pkg-config can find it by
 setting PKG_CONFIG_PATH.  Ensure that the 'includedir' and 'libdir'
-in there is correct, and remove the 'nspr' entry from the
-'Requires.private:' line so that the
-mozjs-91.pc can be used correctly in Visual Studio/clang-cl builds.  You
-will also need to ensure that the existing GObject-Introspection
-installation (if used) is on the same drive where the GJS sources
-are (and therefore where the GJS build is being carried out).
-
-Since Mozilla insisted that clang-cl is to be used to build SpiderMonkey,
-note that some SpideMonkey headers might need be updated as follows, if intending
-to build without clang-cl, since there are some GCC-ish assumptions here:
+in there is correct so that the mozjs-91.pc can be used correctly in
+Visual Studio/clang-cl builds, and replace the `-isystem` with `-I` if
+building GJS with Visual Studio.  You will also need to ensure that the
+existing GObject-Introspection installation (if used) is on the same
+drive where the GJS sources are (and therefore where the GJS build
+is being carried out).
 
--Update $(includedir)/mozjs-91/js/AllocPolicy.h (after the build):
-
-Get rid of the 'JS_FRIEND_API' macro from the class
-'TempAllocPolicy : public AllocPolicyBase' (ca. lines 112 and 178),
-for the member method definitions of onOutOfMemory() and reportAllocOverflow()
-
--Update $(includedir)/mozjs-91/js/BigInt.h (after the build):
-
-Remove the 'JS_PUBLIC_API' macro from the definition of
-'template <typename NumericT>
-extern BigInt* NumberToBigInt(JSContext* cx, NumericT val)' (ca lines 72-73), as
-it should not be there.
-
-======================
 To carry out the build
 ======================
 If using clang-cl, you will need to set *both* the environment variables CC
@@ -138,12 +145,14 @@ can be defined, which is used if using the cross-compilation capabilities of CLa
 In this case, you need to ensure that 'clang-cl.exe' and 'lld-link.exe' (i.e. your
 LLVM bindir) are present in your PATH.
 
-You need to install Python 3.5.x or later, as well as the
+You need to install Python 3.6.x or later, as well as the
 pkg-config tool, Meson (via pip) and Ninja.  Perform a build by doing the
 following, in an appropriate Visual Studio command prompt
 in an empty build directory:
 
-meson <path_to_gjs_sources> --buildtype=... --prefix=<some_prefix> -Dskip_dbus_tests=true
+```
+meson <path_to_gjs_sources> --buildtype=... --prefix=<some_prefix> -Dskip_dbus_tests=true -Dprofiler=disabled
+```
 
 (Note that -Dskip_dbus_tests=true is required for MSVC/clang-cl builds; please
 see the Meson documentation for the values accepted by buildtype)