From 1c9bafc2a9426ec4e58171008cf05efab4190cc9 Mon Sep 17 00:00:00 2001
From: Josh Berdine <jjb@fb.com>
Date: Tue, 10 Mar 2020 07:01:56 -0700
Subject: [PATCH] [sledge] Add beginnings of HACKING docs

Summary: Brief overview of compiling, testing, debugging, etc. workflow.

Reviewed By: jvillard

Differential Revision: D20351299

fbshipit-source-id: c15627362
---
 sledge/HACKING.adoc | 41 +++++++++++++++++++++++++++++++++++++++++
 sledge/Makefile     |  4 ++--
 2 files changed, 43 insertions(+), 2 deletions(-)
 create mode 100644 sledge/HACKING.adoc

diff --git a/sledge/HACKING.adoc b/sledge/HACKING.adoc
new file mode 100644
index 000000000..8000abaec
--- /dev/null
+++ b/sledge/HACKING.adoc
@@ -0,0 +1,41 @@
+= Hacking on SLEdge
+
+== Development workflow
+
+== Compiling
+
+- `make check` while coding to run the type-checker and populate the data merlin needs as fast as possible
+
+- `make dbg` to build the _debug_ binary (`_build/_install/dbg/bin/sledge`), which enables debug tracing (calls to functions in the `Trace` module) and executes `assert`ions
+
+- `make dbg-opt` to build the _optimized debug_ binary (`_build/_install/dbg-opt/bin/sledge`), which enables debug tracing but does not execute `assert`ions
+
+- `make opt` to build the _optimized_ binary (`_build/_install/opt/bin/sledge`), which disables debug tracing and does not execute `assert`ions
+
+- `make exes`, the default target, to build all 3 binaries
+
+- `make watch` to continuously watch the file system for changes and rebuild all binaries automatically
+
+- `make clean` to remove build artifacts
+
+== Testing
+
+- `make test` to run the inline tests and promote the new results, for review by source control tools (e.g. `git diff`)
+
+- `make ci-test` to run the inline tests and fail if the results change
+
+- `cd ..; GIT_SEQUENCE_EDITOR=: git rebase -ix 'make OCAMLPARAM=_,warn-error=+a -C sledge fmt exes test' $(git merge-base origin/master HEAD)` to format, build, and test a stack of diffs
+
+== Formatting
+
+- `make fmt` to autoformat source code
+
+== Running
+
+- `sledge help` to see the cli's interactive help, or see `sledge-help.txt` for the complete interactive help
+
+== Debugging
+
+- An efficient way to debug individual functions is to write an inline expect test and observe its behavior. See the various `*_test.ml` files which contain tests.
+
+- For wider debugging, take particular note of the documentation for the `-trace` option at the top of `sledge help`. It can be used to selectively enable debug tracing output for calls to `Trace` from individual functions or modules.
diff --git a/sledge/Makefile b/sledge/Makefile
index 5c70c7f91..47d9d8014 100644
--- a/sledge/Makefile
+++ b/sledge/Makefile
@@ -38,8 +38,8 @@ dbg:
 	$(dune_build_dbg)
 	$(dune_install_dbg)
 
-.PHONY: do
-do:
+.PHONY: dbg-opt
+dbg-opt:
 	$(dune_build_dbg_opt)
 	$(dune_install_dbg_opt)