[gjs: 5/7] docs: Update Hacking.md to use Meson workflow

[Philip Chimento <pchimento src gnome org>]

commit 5354b4285609d744c704b9bbc16b694aee297a23
Author: Philip Chimento <philip chimento gmail com>
Date:   Mon Sep 2 22:01:10 2019 -0700

    docs: Update Hacking.md to use Meson workflow
    
    With Meson's ability to download and build (most) missing depedencies,
    we can now remove the recommendation to do everything in JHBuild.

 doc/Hacking.md | 136 +++++++++++++++++++++++++++------------------------------
 1 file changed, 65 insertions(+), 71 deletions(-)
---
diff --git a/doc/Hacking.md b/doc/Hacking.md
index 6a8f6279..41fe27a8 100644
--- a/doc/Hacking.md
+++ b/doc/Hacking.md
@@ -12,47 +12,59 @@ For more information, see
 you'll need to manually format your code before it gets merged.
 You can also skip this step if you are not writing any C++ code.)
 
-For the time being, we recommend using JHBuild to develop GJS.
-Follow the [instructions from GNOME](https://wiki.gnome.org/HowDoI/Jhbuild) for 
[JHBuild](https://git.gnome.org/browse/jhbuild/).
-
 GJS requires four other libraries to be installed: GLib, libffi,
 gobject-introspection, and SpiderMonkey (also called "mozjs60" on some
 systems.)
 The readline library is not required, but strongly recommended.
-We recommend installing your system's development packages for libffi
-and readline, and building the others with JHBuild.
-(For example, on Ubuntu these packages are called `libffi-dev` and
-`libreadline-dev`.)
-
+We recommend installing your system's development packages for GLib,
+libffi, gobject-introspection, and readline.
+(For example, on Ubuntu you would run
+`sudo apt-get install libglib2.0-dev libffi-dev libreadline-dev libgirepository1.0-dev libreadline-dev`.)
+But, if your system's versions of these packages aren't new enough, then
+the build process will download and build sufficient versions.
+
+SpiderMonkey cannot be auto-installed, so you will need to install it
+either through your system's package manager, or building it yourself.
 Even if your system includes a development package for SpiderMonkey, we
-recommend building it on JHBuild so that you can enable the debugging
-features.
-Add this to your JHBuild configuration file (usually
-`~/.config/jhbuildrc`):
-```python
-module_autogenargs['mozjs60'] = '--enable-debug'
-```
-Make sure it is built first with `jhbuild build mozjs60`, otherwise
-`jhbuild build gjs` will skip it if you have the system package
-installed.
-
+still recommend building it if you are going to do any development on
+GJS so that you can enable the debugging features.
 These debugging features reduce performance by quite a lot, but they
 will help catch mistakes in the API that could otherwise go unnoticed
 and cause crashes in gnome-shell later on.
 
+To build SpiderMonkey, follow the instructions on [this page][embedder]
+to download the source code and build the library.
+If you are using `-Dprefix` to build GJS into a different path, then
+make sure to use the same build prefix for SpiderMonkey with `--prefix`.
+
+## First build ##
+
+To build GJS, change to your checkout directory, and run:
+```sh
+meson _build
+ninja -C _build
+```
+
+Add any options with `-D` arguments to the `meson _build` command.
+For a list of available options, run `meson configure`.
+
+To install GJS into the path you chose with `-Dprefix`, (or into
+`/usr/local` if you didn't choose a path), run
+`ninja -C _build install`, adding `sudo` if necessary.
+
 ## Making Sure Your Stuff Doesn't Break Anything Else ##
 
 Make your changes in your GJS checkout directory, then run
-`jhbuild make` to build a modified copy of GJS.
+`ninja -C _build` to build a modified copy of GJS.
 
 Each changeset should ensure that the test suite still passes.
 In fact, each commit should ensure that the test suite still passes,
 though there are some exceptions to this rule.
-You can run the test suite with `jhbuild make check`.
+You can run the test suite with `meson test -C _build`.
 
 For some contributions, it's a good idea to test your modified version
 of GJS with GNOME Shell.
-For this, build GNOME Shell with `jhbuild build gnome-shell`, and run
+For this, you might want to use JHBuild to build GJS instead, and run
 it with `jhbuild run gnome-shell --replace`.
 You need to be logged into an Xorg session, not Wayland, for this to
 work.
@@ -61,24 +73,19 @@ work.
 
 Mozilla has some pretty-printers that make debugging JSAPI code easier.
 Unfortunately they're not included in most packaged distributions of
-mozjs, but you can grab them from your JHBuild copy of mozjs.
+mozjs, but you can grab them from your built copy of mozjs.
 
 After reaching a breakpoint in your program, type this to activate the
 pretty-printers:
-```
-source ~/.cache/jhbuild/build/mozjs-60.Y.Z/js/src/shell/js-gdb.py
+```sh
+source /path/to/spidermonkey/js/src/_build/shell/js-gdb.py
 ```
 
-(replace `Y.Z` with mozjs's minor and micro version numbers)
+(replace `/path/to/spidermonkey` with the path to your SpiderMonkey
+sources)
 
 ## Checking Things More Thoroughly Before A Release ##
 
-### Distcheck ###
-
-Run `jhbuild make distcheck` once before every release to make sure the
-package builds and the tests run from a clean release tarball.
-If there are any errors, they must be fixed before making the release.
-
 ### GC Zeal ###
 
 Run the test suite with "GC zeal" to make non-deterministic GC errors
@@ -86,21 +93,21 @@ more likely to show up.
 
 To see which GC zeal options are available:
 ```sh
-JS_GC_ZEAL=-1 jhbuild run gjs
+JS_GC_ZEAL=-1 js60
 ```
 
-To run the test suite under it:
+We include three test setups, `extra_gc`, `pre_verify`, and
+`post_verify`, for the most useful modes: `2,1`, `4`, and `11`
+respectively.
+Run them like this (replace `extra_gc` with any of the other names):
 ```sh
-JS_GC_ZEAL=... jhbuild make check
+meson test -C _build --setup=extra_gc
 ```
 
-Good parameters for `...` are `1`, `2,100`, `2,1` (really slow and can
-cause the tests to time out), `4`, `6`, `7`, `11`.
-
-Failures in mode 4 (pre barrier verification) usually point to a GC
-thing not being traced when it should have been. Failures in mode 11
-(post barrier verification) usually point to a weak pointer's location
-not being updated after GC moved it.
+Failures in mode `pre_verify` usually point to a GC thing not being
+traced when it should have been.
+Failures in mode `post_verify` usually point to a weak pointer's
+location not being updated after GC moved it.
 
 ### Valgrind ###
 
@@ -108,12 +115,13 @@ Valgrind catches memory leak errors in the C++ code.
 It's a good idea to run the test suite under Valgrind before each
 release.
 
-To run the test suite under a succession of Valgrind tools:
+To run the test suite under Valgrind's memcheck tool:
 ```sh
-jhbuild make check-valgrind
+meson test -C _build --setup=valgrind
 ```
 
-The logs from each run will be in `~/.cache/jhbuild/build/gjs/test-suite-<toolname>.log`, where `<toolname>` 
is `drd`, `helgrind`, `memcheck`, and `sgcheck`.
+The logs from each run will be in
+`_build/meson-logs/testlog-valgrind.txt`.
 
 Note that LeakSanitizer, part of ASan (see below) can catch many, but
 not all, errors that Valgrind can catch.
@@ -131,36 +139,22 @@ the compilers normally fail to detect.
 
 ### Sanitizers ###
 
-To add instrumentation code to gjs, put this (both, or any one of them) in
-your JHBuild configuration file:
-```python
-module_autogenargs['gjs'] = '--enable-asan --enable-ubsan'
+To build GJS with support for the ASan and UBSan sanitizers, configure
+meson like this:
+```sh
+meson _build -Db_sanitize=address,undefined
 ```
-
-Sanitizers are based on compile-time instrumentation. They are available
-in gcc and clang for a range of supported operating systems and
-platforms.
-
-Please, keep in mind that instrumentation is limited by execution coverage. So,
-if your "testing" session never reaches a particular point of execution, then
-instrumentation at that point collects no data.
+and then run the tests as normal.
 
 ### Test Coverage ###
 
-To generate a test coverage report, put this in your JHBuild
-configuration file:
-```python
-module_autogenargs['gjs'] = '--enable-code-coverage'
-```
-
-Then run:
+To generate a test coverage report, run this script:
 ```sh
-jhbuild cleanone gjs
-jhbuild buildone gjs
-jhbuild make check-code-coverage
-xdg-open ~/.cache/jhbuild/build/gjs/gjs-X.Y.Z-coverage/index.html
+tools/run_coverage.sh
+gio open _coverage/html/index.html
 ```
+This will build GJS into a separate build directory with code coverage
+instrumentation enabled, run the test suite to collect the coverage
+data, and open the generated HTML report.
 
-(replace `X.Y.Z` with the version number, e.g. `1.48.0`)
-
-[JHBuild](https://wiki.gnome.org/HowDoI/Jhbuild)
\ No newline at end of file
+[embedder](https://github.com/spidermonkey-embedders/spidermonkey-embedding-examples/blob/esr60/docs/Building%20SpiderMonkey.md)
\ No newline at end of file