Skip to content

Commit cd84858

Browse files
wilzbachwilzbach
committed
Dynamic writeln magic
1 parent a21c649 commit cd84858

File tree

1 file changed

+34
-59
lines changed

1 file changed

+34
-59
lines changed

‎posix.mak

Lines changed: 34 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,15 @@
126126
# in the build folder `.generated`, s.t. Ddoc can be run on the modified sources.
127127
#
128128
# See also: https://dlang.org/blog/2017/03/08/editable-and-runnable-doc-examples-on-dlang-org
129+
#
130+
# Custom DDoc wrapper
131+
# -------------------
132+
#
133+
# `ddoc.d` is a wrapper around Ddoc and allows expanding Ddoc macros dynamically
134+
# before actually running Ddoc.
135+
# Currently this is used for:
136+
# - TOC
137+
# - assert -> writeln magic
129138
PWD=$(shell pwd)
130139
MAKEFILE=$(firstword $(MAKEFILE_LIST))
131140

@@ -169,21 +178,13 @@ $(shell [ ! -d $(DMD_DIR) ] && git clone --depth=1 ${GIT_HOME}/dmd $(DMD_DIR))
169178
$(shell [ ! -d $(DRUNTIME_DIR) ] && git clone --depth=1 ${GIT_HOME}/druntime $(DRUNTIME_DIR))
170179

171180
################################################################################
172-
# Automatically generated directories
173-
PHOBOS_DIR_GENERATED=$(GENERATED)/phobos-prerelease
174-
PHOBOS_LATEST_DIR_GENERATED=$(GENERATED)/phobos-latest
175-
# The assert_writeln_magic tool transforms all source files from Phobos. Hence
176-
# - a temporary folder with a copy of Phobos needs to be generated
177-
# - a list of all files in Phobos and the temporary copy is needed to setup proper
178-
# Makefile dependencies and rules
181+
# Automatically clone Phobos
179182
PHOBOS_FILES := $(shell find $(PHOBOS_DIR) -name '*.d' -o -name '*.mak' -o -name '*.ddoc')
180-
PHOBOS_FILES_GENERATED := $(subst $(PHOBOS_DIR), $(PHOBOS_DIR_GENERATED), $(PHOBOS_FILES))
181183
ifndef RELEASE
182184
# TODO: should be replaced by make targets
183185
$(shell [ ! -d $(PHOBOS_DIR) ] && git clone --depth=1 ${GIT_HOME}/phobos $(PHOBOS_DIR))
184186
$(shell [ ! -d $(PHOBOS_LATEST_DIR) ] && git clone -b v${LATEST} --depth=1 ${GIT_HOME}/phobos $(PHOBOS_LATEST_DIR))
185187
PHOBOS_LATEST_FILES := $(shell find $(PHOBOS_LATEST_DIR) -name '*.d' -o -name '*.mak' -o -name '*.ddoc')
186-
PHOBOS_LATEST_FILES_GENERATED := $(subst $(PHOBOS_LATEST_DIR), $(PHOBOS_LATEST_DIR_GENERATED), $(PHOBOS_LATEST_FILES))
187188
endif
188189
################################################################################
189190

@@ -668,21 +669,21 @@ $W/phobos-prerelease/object.verbatim : $(DMD) $G/changelog/next-version
668669
################################################################################
669670

670671
.PHONY: phobos-prerelease
671-
phobos-prerelease : ${PHOBOS_FILES_GENERATED} druntime-target $(STD_DDOC_PRERELEASE)
672-
$(MAKE) --directory=$(PHOBOS_DIR_GENERATED) -f posix.mak html $(DDOC_VARS_PRERELEASE_HTML)
672+
phobos-prerelease : ${PHOBOS_FILES} druntime-target $(STD_DDOC_PRERELEASE)
673+
$(MAKE) --directory=$(PHOBOS_DIR) -f posix.mak html $(DDOC_VARS_PRERELEASE_HTML)
673674

674-
phobos-release : ${PHOBOS_FILES_GENERATED} druntime-target $(STD_DDOC_RELEASE)
675-
$(MAKE) --directory=$(PHOBOS_DIR_GENERATED) -f posix.mak html $(DDOC_VARS_RELEASE_HTML)
675+
phobos-release : ${PHOBOS_FILES} druntime-target $(STD_DDOC_RELEASE)
676+
$(MAKE) --directory=$(PHOBOS_DIR) -f posix.mak html $(DDOC_VARS_RELEASE_HTML)
676677

677-
phobos-latest : ${PHOBOS_LATEST_FILES_GENERATED} druntime-latest-target $(STD_DDOC_LATEST)
678-
$(MAKE) --directory=$(PHOBOS_LATEST_DIR_GENERATED) -f posix.mak html $(DDOC_VARS_LATEST_HTML)
678+
phobos-latest : ${PHOBOS_LATEST_FILES} druntime-latest-target $(STD_DDOC_LATEST)
679+
$(MAKE) --directory=$(PHOBOS_LATEST_DIR) -f posix.mak html $(DDOC_VARS_LATEST_HTML)
679680

680-
phobos-prerelease-verbatim : ${PHOBOS_FILES_GENERATED} druntime-target \
681+
phobos-prerelease-verbatim : ${PHOBOS_FILES} druntime-target \
681682
$W/phobos-prerelease/index.verbatim
682683
$W/phobos-prerelease/index.verbatim : verbatim.ddoc \
683684
$W/phobos-prerelease/object.verbatim \
684685
$W/phobos-prerelease/mars.verbatim $G/changelog/next-version
685-
${MAKE} --directory=${PHOBOS_DIR_GENERATED} -f posix.mak html $(DDOC_VARS_PRERELEASE_VERBATIM) \
686+
${MAKE} --directory=${PHOBOS_DIR} -f posix.mak html $(DDOC_VARS_PRERELEASE_VERBATIM) \
686687
DOC_OUTPUT_DIR=$W/phobos-prerelease-verbatim
687688
$(call CHANGE_SUFFIX,html,verbatim,$W/phobos-prerelease-verbatim)
688689
mv $W/phobos-prerelease-verbatim/* $(dir $@)
@@ -733,7 +734,7 @@ else
733734
endif
734735

735736
$G/docs-latest.json : ${DMD_LATEST} ${DMD_LATEST_DIR} \
736-
${DRUNTIME_LATEST_DIR} ${PHOBOS_LATEST_FILES_GENERATED} | dpl-docs
737+
${DRUNTIME_LATEST_DIR} ${PHOBOS_LATEST_FILES} | dpl-docs
737738
# remove this after https://github.com/dlang/dmd/pull/7513 has been merged
738739
if [ -f $(DMD_LATEST_DIR)/src/*/objc_glue_stubs.d ] ; then \
739740
DMD_EXCLUDE_LATEST_BASH="-e /objc_glue.d/d"; \
@@ -742,17 +743,17 @@ $G/docs-latest.json : ${DMD_LATEST} ${DMD_LATEST_DIR} \
742743
sed -e /mscoff/d $${DMD_EXCLUDE_LATEST_BASH} ${DMD_EXCLUDE_LATEST}
743744
find ${DRUNTIME_LATEST_DIR}/src -name '*.d' | \
744745
sed -e /unittest.d/d -e /gcstub/d >> $G/.latest-files.txt
745-
find ${PHOBOS_LATEST_DIR_GENERATED} -name '*.d' | \
746+
find ${PHOBOS_LATEST_DIR} -name '*.d' | \
746747
sed -e /unittest.d/d | sort >> $G/.latest-files.txt
747748
${DMD_LATEST} -J$(DMD_LATEST_DIR)/res -J$(dir $(DMD_LATEST)) -c -o- -version=CoreDdoc \
748749
-version=MARS -version=CoreDdoc -version=StdDdoc -Df$G/.latest-dummy.html \
749-
-Xf$@ -I${PHOBOS_LATEST_DIR_GENERATED} @$G/.latest-files.txt
750+
-Xf$@ -I${PHOBOS_LATEST_DIR} @$G/.latest-files.txt
750751
${DPL_DOCS} filter $@ --min-protection=Protected \
751752
--only-documented $(MOD_EXCLUDES_LATEST)
752753
rm -f $G/.latest-files.txt $G/.latest-dummy.html
753754

754755
$G/docs-prerelease.json : ${DMD} ${DMD_DIR} ${DRUNTIME_DIR} \
755-
${PHOBOS_FILES_GENERATED} | dpl-docs
756+
${PHOBOS_FILES} | dpl-docs
756757
# remove this after https://github.com/dlang/dmd/pull/7513 has been merged
757758
if [ -f $(DMD_DIR)/src/*/objc_glue_stubs.d ] ; then \
758759
DMD_EXCLUDE_PRERELEASE="-e /objc_glue.d/d"; \
@@ -761,11 +762,11 @@ $G/docs-prerelease.json : ${DMD} ${DMD_DIR} ${DRUNTIME_DIR} \
761762
sed -e /mscoff/d $${DMD_EXCLUDE_PRERELEASE} > $G/.prerelease-files.txt
762763
find ${DRUNTIME_DIR}/src -name '*.d' | \
763764
sed -e /unittest/d >> $G/.prerelease-files.txt
764-
find ${PHOBOS_DIR_GENERATED} -name '*.d' | \
765+
find ${PHOBOS_DIR} -name '*.d' | \
765766
sed -e /unittest.d/d | sort >> $G/.prerelease-files.txt
766767
${DMD} -J$(DMD_DIR)/res -J$(dir $(DMD)) -c -o- -version=MARS -version=CoreDdoc \
767768
-version=StdDdoc -Df$G/.prerelease-dummy.html \
768-
-Xf$@ -I${PHOBOS_DIR_GENERATED} @$G/.prerelease-files.txt
769+
-Xf$@ -I${PHOBOS_DIR} @$G/.prerelease-files.txt
769770
${DPL_DOCS} filter $@ --min-protection=Protected \
770771
--only-documented $(MOD_EXCLUDES_PRERELEASE)
771772
rm -f $G/.prerelease-files.txt $G/.prerelease-dummy.html
@@ -826,42 +827,6 @@ d-release.tag d-tags-release.json : chmgen.d $(STABLE_DMD) $(ALL_FILES) phobos-r
826827
d-prerelease.tag d-tags-prerelease.json : chmgen.d $(STABLE_DMD) $(ALL_FILES) phobos-prerelease druntime-prerelease chm-nav-prerelease.json
827828
$(STABLE_RDMD) chmgen.d --root=$W --only-tags --target prerelease
828829

829-
################################################################################
830-
# Assert -> writeln magic
831-
# -----------------------
832-
#
833-
# - This transforms assert(a == b) to writeln(a); // b
834-
# - It creates a copy of Phobos to apply the transformations
835-
# - All "d" files are piped through the transformator,
836-
# other needed files (e.g. posix.mak) get copied over
837-
#
838-
# See also: https://dlang.org/blog/2017/03/08/editable-and-runnable-doc-examples-on-dlang-org
839-
################################################################################
840-
841-
ASSERT_WRITELN_BIN = $(GENERATED)/assert_writeln_magic
842-
843-
$(ASSERT_WRITELN_BIN): assert_writeln_magic.d $(DUB) $(STABLE_DMD)
844-
@mkdir -p $(dir $@)
845-
$(DUB) -v build --single --compiler=$(STABLE_DMD) $<
846-
@mv ./assert_writeln_magic $@
847-
848-
$(ASSERT_WRITELN_BIN)_test: assert_writeln_magic.d $(DUB) $(STABLE_DMD)
849-
@mkdir -p $(dir $@)
850-
$(DUB) -v build --single --compiler=$(STABLE_DMD) --build=unittest $<
851-
@mv ./assert_writeln_magic $@
852-
853-
$(PHOBOS_FILES_GENERATED): $(PHOBOS_DIR_GENERATED)/%: $(PHOBOS_DIR)/% $(DUB) $(ASSERT_WRITELN_BIN)
854-
@mkdir -p $(dir $@)
855-
@if [ $(subst .,, $(suffix $@)) = "d" ] && [ "$@" != "$(PHOBOS_DIR_GENERATED)/index.d" ] ; then \
856-
$(ASSERT_WRITELN_BIN) -i $< -o $@ ; \
857-
else cp $< $@ ; fi
858-
859-
$(PHOBOS_LATEST_FILES_GENERATED): $(PHOBOS_LATEST_DIR_GENERATED)/%: $(PHOBOS_LATEST_DIR)/% $(DUB) $(ASSERT_WRITELN_BIN)
860-
@mkdir -p $(dir $@)
861-
@if [ $(subst .,, $(suffix $@)) = "d" ] && [ "$@" != "$(PHOBOS_LATEST_DIR_GENERATED)/index.d" ] ; then \
862-
$(ASSERT_WRITELN_BIN) -i $< -o $@ ; \
863-
else cp $< $@ ; fi
864-
865830
################################################################################
866831
# Style tests
867832
################################################################################
@@ -967,6 +932,16 @@ $G/contributors_list.ddoc: | $(STABLE_RDMD) $(TOOLS_DIR) $(INSTALLER_DIR)
967932
#
968933
# This allows extending Ddoc files dynamically on-the-fly.
969934
# It is currently only used for the specification pages
935+
#
936+
# It does:
937+
# - dynamic TOC generation
938+
# - GRAMMAR overview generation
939+
# - CHANGELOG menu generation
940+
# - Assert -> writeln magic (https://dlang.org/blog/2017/03/08/editable-and-runnable-doc-examples-on-dlang-org)
941+
# - This transforms assert(a == b) to writeln(a); // b
942+
# - It creates a copy of Phobos to apply the transformations
943+
# - All "d" files are piped through the transformator,
944+
# other needed files (e.g. posix.mak) get copied over
970945
################################################################################
971946

972947
$(DDOC_BIN): ddoc_preprocessor.d | $(STABLE_DMD)

0 commit comments

Comments
 (0)