Document makefiles/virtualenv/
makefiles/virtualenv/include.mk
-------------------------------
o This makefile will install/maintain/invoke a python virtualenv via
makefile target dependencies.
o Add more comments to describe macro definitions, targets and usage.
Change-Id: I59e428d3d5e85c8299e9d1e19257e47ed33417e0
diff --git a/makefiles/virtualenv/include.mk b/makefiles/virtualenv/include.mk
index c20333f..2ce04d2 100644
--- a/makefiles/virtualenv/include.mk
+++ b/makefiles/virtualenv/include.mk
@@ -14,15 +14,30 @@
# See the License for the specific language governing permissions and
# limitations under the License.
# -----------------------------------------------------------------------
-# https://gerrit.opencord.org/plugins/gitiles/onf-make
-# ONF.makefile.virtualenv.version = 1.2
+# -----------------------------------------------------------------------
+# Intent:
+# This makefile defines dependencies that will install a python virtualenv
+# beneath $(sandbox)/.venv/. The $(activate) macro is used to source
+# .venv/bin/activate allowing command python and pip to be used.
# -----------------------------------------------------------------------
# Usage:
-# include makefiles/virtualenv/include.m
+# include makefiles/virtualenv/include.mk
#
-# Target Dependencies:
-# tgt : $(venv-activate-patched) python 3.10+ local use
-# tgt : $(venv-activate-script) python < v3.8
+# Makefile Target Dependencies:
+# tgt : $(venv-activate-patched) # python 3.10+ local use
+# tgt : $(venv-activate-script) # python < v3.8
+#
+# Make definitions (convenience macros used for command access)
+# PIP := $(activate) && pip # invoke pip from virtualenv
+# PYTHON := $(activate) && python # invoke python from virtualenv
+#
+# Target declaration and command invocation:
+# my-target : $(venv-activate-script) # dependency installs virtualenv
+# <tab>$(PYTHON) --version # invoke python with arguments
+# <tab>$(PYTHON) my-command.py
+# <tab>$(activate) && pip install foobar
+#
+# % make my-target # Invoke make target from shell
# -----------------------------------------------------------------------
$(if $(DEBUG),$(warning ENTER))
@@ -40,8 +55,12 @@
venv-activate-bin := $(venv-name)/bin# # no whitespace
venv-activate-script := $(venv-activate-bin)/activate# # dependency
-# Intent: activate= is a macro for accessing the virtualenv activation script#
-# Usage: $(activate) && python
+# ------------------------------------------------------------------------
+# Intent: Define macro activate= to access virtualenv activation script.
+# Usage:
+# - $(activate) && python # Syntax inlined within a target
+# - PYTHON := $(activate) && python # Define a named command macro
+# ------------------------------------------------------------------------
activate ?= set +u && source $(venv-activate-script) && set -u
## -----------------------------------------------------------------------