From 6e38848b92e078f9d0f263b54adb7b84cb9f5eb3 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Thu, 25 Jan 2024 12:35:03 +1300
Subject: [PATCH] Docs: updating makefiles

---
 Makefile                                      | 11 +++++----
 docs/Makefile                                 | 23 ++++++++++++++-----
 docs/source/code_examples/extensions/Makefile | 11 +++++----
 docs/source/code_examples/fifo/Makefile       |  5 ++--
 docs/source/code_examples/intro/Makefile      |  1 +
 docs/source/code_examples/macc/Makefile       |  1 +
 docs/source/code_examples/opt/Makefile        |  1 +
 docs/source/code_examples/scrambler/Makefile  |  2 ++
 docs/source/code_examples/selections/Makefile |  2 ++
 docs/source/code_examples/show/Makefile       |  4 +++-
 docs/source/code_examples/stubnets/Makefile   |  4 ++++
 docs/source/code_examples/synth_flow/Makefile |  2 ++
 docs/source/code_examples/techmap/Makefile    |  2 ++
 .../extending_yosys/extensions.rst            |  2 ++
 14 files changed, 53 insertions(+), 18 deletions(-)

diff --git a/Makefile b/Makefile
index 753ff9b92fa..cdcf96b0c06 100644
--- a/Makefile
+++ b/Makefile
@@ -971,9 +971,12 @@ docs/source/cmd/abc.rst: $(TARGETS) $(EXTRA_TARGETS)
 	mkdir -p docs/source/cmd
 	./$(PROGRAM_PREFIX)yosys -p 'help -write-rst-command-reference-manual'
 
-PHONY: docs/gen_images docs/guidelines docs/usage
+PHONY: docs/gen_examples docs/gen_images docs/guidelines docs/usage
+docs/gen_examples:
+	$(Q) $(MAKE) -C docs examples
+
 docs/gen_images:
-	$(Q) $(MAKE) -C docs/source/_images all
+	$(Q) $(MAKE) -C docs images
 
 DOCS_GUIDELINE_FILES := GettingStarted CodingStyle
 docs/guidelines:
@@ -988,7 +991,7 @@ docs/source/temp/%: docs/guidelines
 	-$(Q) ./$(PROGRAM_PREFIX)$* --help > $@ 2>&1
 
 DOC_TARGET ?= html
-docs: docs/source/cmd/abc.rst docs/gen_images docs/guidelines docs/usage
+docs: docs/source/cmd/abc.rst docs/gen_examples docs/gen_images docs/guidelines docs/usage
 	$(Q) $(MAKE) -C docs $(DOC_TARGET)
 
 clean:
@@ -1007,8 +1010,6 @@ clean:
 	rm -f tests/svinterfaces/*.log_stdout tests/svinterfaces/*.log_stderr tests/svinterfaces/dut_result.txt tests/svinterfaces/reference_result.txt tests/svinterfaces/a.out tests/svinterfaces/*_syn.v tests/svinterfaces/*.diff
 	rm -f  tests/tools/cmp_tbdata
 	$(MAKE) -C docs clean
-	$(MAKE) -C docs/source/_images clean
-	rm -rf docs/source/cmd docs/util/__pycache__
 
 clean-abc:
 	$(MAKE) -C abc DEP= clean
diff --git a/docs/Makefile b/docs/Makefile
index 71a6b3152fe..c2e730fa82a 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -45,8 +45,10 @@ help:
 	@echo "  dummy      to check syntax errors of document sources"
 
 .PHONY: clean
-clean:
+clean: clean-examples
 	rm -rf $(BUILDDIR)/*
+	rm -rf source/cmd util/__pycache__
+	$(MAKE) -C source/_images clean
 
 .PHONY: html
 html:
@@ -227,15 +229,24 @@ dummy:
 
 PYTHON ?= python3
 
-.PHONY: test test-examples test-macros
+.PHONY: test test-examples test-macros examples
 test: test-examples test-macros
 
 FORCE:
-../%/Makefile: FORCE
-	+$(MAKE) -C $(@D)
+Makefile-%: FORCE
+	$(MAKE) -C $(@D) $(*F)
 
-CODE_EXAMPLES := source/code_examples/*/Makefile
-test-examples: $(CODE_EXAMPLES)
+CODE_EXAMPLES := $(wildcard source/code_examples/*/Makefile)
+TEST_EXAMPLES := $(addsuffix -all,$(CODE_EXAMPLES))
+CLEAN_EXAMPLES := $(addsuffix -clean,$(CODE_EXAMPLES))
+test-examples: $(TEST_EXAMPLES)
+clean-examples: $(CLEAN_EXAMPLES)
+examples: $(TEST_EXAMPLES)
 
 test-macros:
 	$(PYTHON) tests/macro_commands.py
+
+.PHONY: images
+images:
+	$(MAKE) -C source/_images
+
diff --git a/docs/source/code_examples/extensions/Makefile b/docs/source/code_examples/extensions/Makefile
index bec29369cff..288983ed356 100644
--- a/docs/source/code_examples/extensions/Makefile
+++ b/docs/source/code_examples/extensions/Makefile
@@ -2,15 +2,15 @@ PROGRAM_PREFIX :=
 
 YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
-all: test0.log test1.log test2.log
-
+.PHONY: all dots
+all: dots test0.log test1.log test2.log
 dots: test1.dot
 
 CXXFLAGS=$(shell $(YOSYS)-config --cxxflags)
 DATDIR=$(shell $(YOSYS)-config --datdir)
 
 my_cmd.so: my_cmd.cc
-	$(YOSYS)-config --exec --cxx $(subst $(DATDIR),../../share,$(CXXFLAGS)) --ldflags -o my_cmd.so -shared my_cmd.cc --ldlibs
+	$(YOSYS)-config --exec --cxx $(subst $(DATDIR),../../../../share,$(CXXFLAGS)) --ldflags -o my_cmd.so -shared my_cmd.cc --ldlibs
 
 test0.log: my_cmd.so
 	$(YOSYS) -Ql test0.log_new -m ./my_cmd.so -p 'my_cmd foo bar' absval_ref.v
@@ -20,10 +20,13 @@ test1.log: my_cmd.so
 	$(YOSYS) -Ql test1.log_new -m ./my_cmd.so -p 'clean; test1; dump' absval_ref.v
 	mv test1.log_new test1.log
 
-test1.dot:
+test1.dot: my_cmd.so
 	$(YOSYS) -m ./my_cmd.so -p 'test1; show -format dot -prefix test1'
 
 test2.log: my_cmd.so
 	$(YOSYS) -Ql test2.log_new -m ./my_cmd.so -p 'hierarchy -top test; test2' sigmap_test.v
 	mv test2.log_new test2.log
 
+.PHONY: clean
+clean:
+	rm -f *.d *.so *.dot
diff --git a/docs/source/code_examples/fifo/Makefile b/docs/source/code_examples/fifo/Makefile
index 37ce0a12cf4..0a1186a62d4 100644
--- a/docs/source/code_examples/fifo/Makefile
+++ b/docs/source/code_examples/fifo/Makefile
@@ -10,12 +10,13 @@ MAPDOT_NAMES += rdata_map_ffs rdata_map_luts rdata_map_cells
 DOTS := $(addsuffix .dot,$(DOT_NAMES))
 MAPDOTS := $(addsuffix .dot,$(MAPDOT_NAMES))
 
-dots: $(DOTS) $(MAPDOTS) fifo.out
+all: dots fifo.out fifo.stat
+dots: $(DOTS) $(MAPDOTS)
 
 $(DOTS) fifo.out: fifo.v fifo.ys
 	$(YOSYS) fifo.ys -l fifo.out -Q -T
 
-$(MAPDOTS): fifo.v fifo_map.ys
+$(MAPDOTS) fifo.stat: fifo.v fifo_map.ys
 	$(YOSYS) fifo_map.ys
 
 .PHONY: clean
diff --git a/docs/source/code_examples/intro/Makefile b/docs/source/code_examples/intro/Makefile
index e6509681f68..009c82c6219 100644
--- a/docs/source/code_examples/intro/Makefile
+++ b/docs/source/code_examples/intro/Makefile
@@ -4,6 +4,7 @@ YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
 DOTS = counter_00.dot counter_01.dot counter_02.dot counter_03.dot
 
+all: dots
 dots: $(DOTS)
 
 $(DOTS): counter.v counter.ys mycells.lib
diff --git a/docs/source/code_examples/macc/Makefile b/docs/source/code_examples/macc/Makefile
index 57ba455bb51..e93fe065734 100644
--- a/docs/source/code_examples/macc/Makefile
+++ b/docs/source/code_examples/macc/Makefile
@@ -4,6 +4,7 @@ YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
 DOTS = macc_simple_xmap.dot macc_xilinx_xmap.dot
 
+all: dots
 dots: $(DOTS)
 
 macc_simple_xmap.dot: macc_simple_*.v macc_simple_test.ys
diff --git a/docs/source/code_examples/opt/Makefile b/docs/source/code_examples/opt/Makefile
index e59130ecdaa..4cb51e90bec 100644
--- a/docs/source/code_examples/opt/Makefile
+++ b/docs/source/code_examples/opt/Makefile
@@ -6,6 +6,7 @@ DOT_NAMES = opt_share opt_muxtree opt_merge opt_expr
 
 DOTS := $(addsuffix .dot,$(DOT_NAMES))
 
+all: dots
 dots: $(DOTS)
 
 %_full.dot: %.ys
diff --git a/docs/source/code_examples/scrambler/Makefile b/docs/source/code_examples/scrambler/Makefile
index 4fdb0610a2e..de475b8b1a1 100644
--- a/docs/source/code_examples/scrambler/Makefile
+++ b/docs/source/code_examples/scrambler/Makefile
@@ -2,6 +2,8 @@ PROGRAM_PREFIX :=
 
 YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
+.PHONY: all dots
+all: dots
 dots: scrambler_p01.dot scrambler_p02.dot
 
 scrambler_p01.dot scrambler_p02.dot: scrambler.ys scrambler.v
diff --git a/docs/source/code_examples/selections/Makefile b/docs/source/code_examples/selections/Makefile
index 06abd2a3ea9..bb506ff38eb 100644
--- a/docs/source/code_examples/selections/Makefile
+++ b/docs/source/code_examples/selections/Makefile
@@ -11,6 +11,8 @@ MEMDEMO_DOTS := $(addsuffix .dot,$(MEMDEMO))
 SUBMOD = submod_00 submod_01 submod_02 submod_03
 SUBMOD_DOTS := $(addsuffix .dot,$(SUBMOD))
 
+.PHONY: all dots
+all: dots
 dots: select.dot $(SUMPROD_DOTS) $(MEMDEMO_DOTS) $(SUBMOD_DOTS)
 
 select.dot: select.v select.ys
diff --git a/docs/source/code_examples/show/Makefile b/docs/source/code_examples/show/Makefile
index c254ed25503..4b269a4aba1 100644
--- a/docs/source/code_examples/show/Makefile
+++ b/docs/source/code_examples/show/Makefile
@@ -8,7 +8,9 @@ EXAMPLE_DOTS := $(addsuffix .dot,$(EXAMPLE))
 CMOS = cmos_00 cmos_01
 CMOS_DOTS := $(addsuffix .dot,$(CMOS))
 
-dots: splice.dot $(EXAMPLE_DOTS) $(CMOS_DOTS) example.out
+.PHONY: all dots
+all: dots example.out
+dots: splice.dot $(EXAMPLE_DOTS) $(CMOS_DOTS)
 
 splice.dot: splice.v
 	$(YOSYS) -p 'prep -top splice_demo; show -format dot -prefix splice' splice.v
diff --git a/docs/source/code_examples/stubnets/Makefile b/docs/source/code_examples/stubnets/Makefile
index cbcd71113e9..ec501f006ca 100644
--- a/docs/source/code_examples/stubnets/Makefile
+++ b/docs/source/code_examples/stubnets/Makefile
@@ -1,5 +1,8 @@
+.PHONY: all dots
+all: dots
 dots:
 
+.PHONY: test
 test: stubnets.so
 	yosys -ql test1.log -m ./stubnets.so test.v -p "stubnets"
 	yosys -ql test2.log -m ./stubnets.so test.v -p "opt; stubnets"
@@ -9,6 +12,7 @@ test: stubnets.so
 stubnets.so: stubnets.cc
 	yosys-config --exec --cxx --cxxflags --ldflags -o $@ -shared $^ --ldlibs
 
+.PHONY: clean
 clean:
 	rm -f test1.log test2.log test3.log
 	rm -f stubnets.so stubnets.d
diff --git a/docs/source/code_examples/synth_flow/Makefile b/docs/source/code_examples/synth_flow/Makefile
index af5d4149381..cc5a34b26b5 100644
--- a/docs/source/code_examples/synth_flow/Makefile
+++ b/docs/source/code_examples/synth_flow/Makefile
@@ -9,6 +9,8 @@ YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
 DOTS = $(addsuffix .dot,$(TARGETS))
 
+.PHONY: all dots
+all: dots
 dots: $(DOTS)
 
 %.dot: %.v %.ys
diff --git a/docs/source/code_examples/techmap/Makefile b/docs/source/code_examples/techmap/Makefile
index e4e0ac745c2..e900fea4c5f 100644
--- a/docs/source/code_examples/techmap/Makefile
+++ b/docs/source/code_examples/techmap/Makefile
@@ -2,6 +2,8 @@ PROGRAM_PREFIX :=
 
 YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
+.PHONY: all dots
+all: dots
 dots: red_or3x1.dot sym_mul.dot mymul.dot mulshift.dot addshift.dot
 
 red_or3x1.dot: red_or3x1_*
diff --git a/docs/source/yosys_internals/extending_yosys/extensions.rst b/docs/source/yosys_internals/extending_yosys/extensions.rst
index ab8cf0cb64e..2d6847f256d 100644
--- a/docs/source/yosys_internals/extending_yosys/extensions.rst
+++ b/docs/source/yosys_internals/extending_yosys/extensions.rst
@@ -6,6 +6,8 @@ Writing extensions
 
 .. todo:: check text is coherent
 
+.. todo:: update to use ``/code_examples/extensions/test*.log``
+
 This chapter contains some bits and pieces of information about programming
 yosys extensions. Don't be afraid to ask questions on the YosysHQ Slack.