[examples] Split Makefile to be standalone and improve readme.

Fixes facebookresearch#536.

Author: ChrisCummins

Makefile

@@ -51,10 +51,6 @@ Post-installation Tests
         the fuzz tests for a minimum of one minute. This requires that the
         CompilerGym package has been installed (`make install`).
 
-    make examples-test
-        Run pytest in the examples directory. This requires that the CompilerGym
-        package has been installed (`make install`).
-
 
 Documentation
 -------------
@@ -169,9 +165,6 @@ DISTTOOLS_OUTS := \
 	build \
 	compiler_gym.egg-info \
 	dist \
-	examples/build \
-	examples/compiler_gym_examples.egg-info \
-	examples/dist \
 	$(NULL)
 
 BUILD_TARGET ?= //:package
@@ -333,12 +326,6 @@ endef
 install-test: | install-test-setup
 	$(call pytest,--no-success-flaky-report --benchmark-disable -n auto -k "not fuzz" --durations=5)
 
-examples-pip-install:
-	cd examples && python setup.py install
-
-examples-test: examples-pip-install
-	cd examples && pytest --no-success-flaky-report --benchmark-disable -n auto --durations=5 . --cov=compiler_gym --cov-report=xml:$(COV_REPORT) $(PYTEST_ARGS)
-
 # Note we export $CI=1 so that the tests always run as if within the CI
 # environement. This is to ensure that the reported coverage matches that of
 # the value on: https://codecov.io/gh/facebookresearch/CompilerGym
@@ -352,11 +339,7 @@ FUZZ_SECONDS ?= 300
 install-fuzz: install-test-setup
 	$(call pytest,--no-success-flaky-report -p no:sugar -x -vv -k fuzz --seconds=$(FUZZ_SECONDS))
 
-post-install-test:
-	$(MAKE) -C examples/makefile_integration clean
-	SEARCH_TIME=3 $(MAKE) -C examples/makefile_integration test
-
-.PHONY: test post-install-test examples-pip-install examples-test
+.PHONY: test post-install-test
 
 
 ################
@@ -370,6 +353,7 @@ pip-install: uninstall
 	$(PYTHON) setup.py install
 
 install: |  init-runtime-requirements bazel-build pip-install
+	$(MAKE) -C examples install
 
 .PHONY: pip-install install
 
@@ -402,6 +386,7 @@ distclean: clean
 
 uninstall:
 	$(PYTHON) -m pip uninstall -y compiler_gym
+	$(MAKE) -C examples uninstall
 
 purge: distclean uninstall
 	rm -rf $(COMPILER_GYM_DATA_FILE_LOCATIONS)

examples/Makefile

@@ -9,14 +9,55 @@ CompilerGym usage examples. See README.md for details. Available targets:
         Install the example python packages.
 
     make test
-        Run the example unit tests.
+        Run pytest in this directory.
+
+    make clean
+        Remove build artifacts.
+
+    make uninstall
+        Uninstall the example python packages.
 endef
 export HELP
 
+# The path of the repository reoot.
+ROOT := $(realpath $(dir $(realpath $(firstword $(MAKEFILE_LIST))))/..)
+
 PYTHON ?= python3
 
+# Extra command line arguments for pytest.
+PYTEST_ARGS ?=
+
+# The path of the XML pytest coverage report to generate when running the
+# install-test-cov target.
+COV_REPORT ?= $(ROOT)/coverage.xml
+
+DISTTOOLS_OUTS := \
+	build \
+	compiler_gym_examples.egg-info \
+	dist \
+	$(NULL)
+
+.DEFAULT_GOAL := help
+
+help:
+	@echo "$$HELP"
+
 install:
 	$(PYTHON) setup.py install
 
+uninstall:
+	$(PYTHON) -m pip uninstall -y compiler_gym_examples
+
 test:
-	$(PYTHON) -m pytest .
+	pytest --no-success-flaky-report --benchmark-disable -n auto --durations=5 . --cov=compiler_gym --cov-report=xml:$(COV_REPORT) $(PYTEST_ARGS)
+	$(MAKE) -C makefile_integration clean
+	SEARCH_TIME=3 $(MAKE) -C makefile_integration test
+
+clean:
+	rm -rf $(DISTTOOLS_OUTS)
+
+disclean: clean
+
+purge: distclean uninstall
+
+.PHONY: help install uninstall test clean distclean purge

examples/README.md

@@ -1,11 +1,22 @@
 # CompilerGym Examples <!-- omit in toc -->
 
-This directory contains code samples for everything from implementing simple
-RL agents to adding support for entirely new compilers. Is there an example that
-you think is missing? If so, please [contribute](/CONTRIBUTING.md)!
+This directory contains standalone code samples for everything from implementing
+simple RL agents to adding support for entirely new compilers. You can run these
+examples using a `pip` installed CompilerGym, though there are some additional
+dependencies that can be installed using:
 
+    make install
 
-**Table of contents:**
+Then run the python scripts from this directory. E.g.:
+
+    python actor_critic.py
+
+Is there an example that you think is missing? If so, please file a [feature
+request](https://github.com/facebookresearch/CompilerGym/issues/new/choose) or
+[contribute](/CONTRIBUTING.md)!
+
+
+## Table of contents  <!-- omit in toc -->
 
 - [Autotuning](#autotuning)
   - [Performing a random walk of an environment](#performing-a-random-walk-of-an-environment)

examples/setup.py

@@ -13,6 +13,8 @@
     version = f.read().strip()
 with open("requirements.txt") as f:
     requirements = [ln.split("#")[0].rstrip() for ln in f.readlines()]
+with open("../tests/requirements.txt") as f:
+    requirements += [ln.split("#")[0].rstrip() for ln in f.readlines()]
 
 setuptools.setup(
     name="compiler_gym_examples",