build regenerating SkJumper stages into GN

I _think_ this makes it so changes to _stages.cpp or _lowp.cpp get
noticed, regenerated, and baked into Skia all in the same Ninja
invocation.

Now you just need to set up the tools we use in GN:

  skia_jumper_clang = ...
  skia_jumper_objdump = ...
  skia_jumper_ccache = ...

Change-Id: I09fb54d965644ff6e5825056fb0be2c7cab2ea92
Reviewed-on: https://skia-review.googlesource.com/21140
Reviewed-by: Florin Malita <fmalita@chromium.org>
Commit-Queue: Mike Klein <mtklein@chromium.org>

1 files changed, 21 insertions, 31 deletions

diff --git a/site/dev/contrib/jumper.md b/site/dev/contrib/jumper.md
index 520876cd19..757697f653 100644
--- a/site/dev/contrib/jumper.md
+++ b/site/dev/contrib/jumper.md
@@ -8,19 +8,16 @@ and color-correct drawing.
 (This is where I'd put my link to design document if I had one...)
 
 SkJumper is more annoying to contribute to than most Skia code because of its
-offline compilation step.  `src/jumper/build_stages.py` compiles
-`src/jumper/SkJumper_stages.cpp` several different ways and parses the object
-files it generates into `src/jumper/SkJumper_generated.S` and
-`src/jumper/SkJumper_generated_win.S`.  This document is designed to guide you
+offline compilation step.  You'll need particular tools installed on your
+machine and to tell GN about them.  This document is designed to guide you
 through this process and ease some of that annoyance.
 
 One-time Setup
 --------------
 
-To run `build_stages.py` you need Clang 4.0 and objdump, and probably want
-ccache.  It's best that Clang is exactly the same version we typically use (as
-of writing 4.0.0) and you'll need objdump to be compiled with support for
-x86-64, ARMv7, and ARMv8.
+To generate stage code you need Clang 4.0, objdump, and ccache.  It's best that
+Clang is exactly the same version we typically use (as of writing 4.0.0) and
+you'll need objdump to be compiled with support for x86-64, ARMv7, and ARMv8.
 
 The easiest way to satisfy these contraints is to get your hands on a Mac and
 install [Homebrew](https://brew.sh).  Once you have `brew` installed, run this
@@ -30,28 +27,22 @@ to get the tools you need:
 
     brew install llvm binutils ccache
 
-Running `build_stages.py`
+Setting up GN
 -------------------------
 
-With your tools installed, try a no-op run of `build_stages.py`:
+With your tools installed, tell GN about them
 
-<!--?prettify lang=sh?-->
+    skia_jumper_clang = path/to/clang-4.0
+    skia_jumper_objdump = path/to/gobjdump
+    skia_jumper_ccache = path/to/ccache
 
-    python src/jumper/build_stages.py path/to/clang-4.0 path/to/gobjdump path/to/ccache
-    git status
+then regenerate and build as normal.
 
-When you run `git status` you should see a bunch of untracked `.o` files
-sitting in skia/, and no changes to `src/jumper/SkJumper_generated*.S`.
+If you look in your GN out directory, you should now see a bunch of `.o` files,
+and `git status` should show no changes to `src/jumper/SkJumper_generated*.S`.
 That's good.  Those object files are the intermediates we parse to produce
 the assembly files.  We just leave them around in case you want to look at
-them yourself.  If you don't like them, it's safe to just
-
-<!--?prettify lang=sh?-->
-
-    rm *.o
-
-If `clang-4.0`, `gobjdump`, and `ccache` are on your path, `build_stages.py`
-should find them without you needing to pass them on the command line.
+them yourself.
 
 Make A Change
 -------------
@@ -65,7 +56,9 @@ Open up `SkJumper_stages.cpp` and find the `from_srgb` stage.  It'll look like
 <!--?prettify lang=cc?-->
 
     STAGE(from_srgb) {
-        ...
+        r = from_srgb(r);
+        g = from_srgb(g);
+        b = from_srgb(b);
     }
 
 Let's replace whatever's there with our fast approximation:
@@ -78,7 +71,7 @@ Let's replace whatever's there with our fast approximation:
         b *= b;
     }
 
-When you save and re-run `build_stages.py`, you should now see changes to
+When you save and re-Ninja, you should now see changes to
 `src/jumper/SkJumper_generated.S` and `src/jumper/SkJumper_generated_win.S`.
 If you can't read assembly, no big deal.  If you can, run `git diff`.  You
 should see the various `sk_from_srgb_*` functions get dramatically simpler,
@@ -94,17 +87,14 @@ see some code that looks like garbage change; those are the constants.  If
 any of this worries you, please do go running to someone who knows more for
 help, but odds are everything is fine.
 
-At this point you can re-build Skia, run DM, compare images, etc. as normal.
-Any time you change `SkJumper_stages.cpp`, you need to re-run `build_stages.py`
-for those changes to take effect.  Believe me, I'd bake this into our GN build
-if I could figure out a way.
+At this point things should just be business as usual.  Any time you change
+`SkJumper_stages.cpp`, Ninja ought to notice and regenerate the assembly files.
 
 Adding a new Stage
 ------------------
 
 Adding a new stage is a lot like changing an existing stage.  Edit
-`SkJumper_stages.cpp`, run `build_stages.py`, build Skia, test, repeat until
-correct.
+`SkJumper_stages.cpp`, build Skia, test, repeat until correct.
 
 You'll just need to also edit `SkRasterPipeline.h` to add your new stage to the
 macro listing all the stages.  The stage name is the handle normal Skia code