Skip to content

Commit 1cb8540

Browse files
wilzbachwilzbach
committed
Dynamic writeln magic
1 parent 9f64f81 commit 1cb8540

File tree

1 file changed

+33
-59
lines changed

1 file changed

+33
-59
lines changed

‎posix.mak‎

Lines changed: 33 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

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

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

@@ -664,21 +665,21 @@ $W/phobos-prerelease/object.verbatim : $(DMD) $G/changelog/next-version
664665
################################################################################
665666

666667
.PHONY: phobos-prerelease
667-
phobos-prerelease : ${PHOBOS_FILES_GENERATED} druntime-target $(STD_DDOC_PRERELEASE)
668-
$(MAKE) --directory=$(PHOBOS_DIR_GENERATED) -f posix.mak html $(DDOC_VARS_PRERELEASE_HTML)
668+
phobos-prerelease : ${PHOBOS_FILES} druntime-target $(STD_DDOC_PRERELEASE)
669+
$(MAKE) --directory=$(PHOBOS_DIR) -f posix.mak html $(DDOC_VARS_PRERELEASE_HTML)
669670

670-
phobos-release : ${PHOBOS_FILES_GENERATED} druntime-target $(STD_DDOC_RELEASE)
671-
$(MAKE) --directory=$(PHOBOS_DIR_GENERATED) -f posix.mak html $(DDOC_VARS_RELEASE_HTML)
671+
phobos-release : ${PHOBOS_FILES} druntime-target $(STD_DDOC_RELEASE)
672+
$(MAKE) --directory=$(PHOBOS_DIR) -f posix.mak html $(DDOC_VARS_RELEASE_HTML)
672673

673-
phobos-latest : ${PHOBOS_LATEST_FILES_GENERATED} druntime-latest-target $(STD_DDOC_LATEST)
674-
$(MAKE) --directory=$(PHOBOS_LATEST_DIR_GENERATED) -f posix.mak html $(DDOC_VARS_LATEST_HTML)
674+
phobos-latest : ${PHOBOS_LATEST_FILES} druntime-latest-target $(STD_DDOC_LATEST)
675+
$(MAKE) --directory=$(PHOBOS_LATEST_DIR) -f posix.mak html $(DDOC_VARS_LATEST_HTML)
675676

676-
phobos-prerelease-verbatim : ${PHOBOS_FILES_GENERATED} druntime-target \
677+
phobos-prerelease-verbatim : ${PHOBOS_FILES} druntime-target \
677678
$W/phobos-prerelease/index.verbatim
678679
$W/phobos-prerelease/index.verbatim : verbatim.ddoc \
679680
$W/phobos-prerelease/object.verbatim \
680681
$W/phobos-prerelease/mars.verbatim $G/changelog/next-version
681-
${MAKE} --directory=${PHOBOS_DIR_GENERATED} -f posix.mak html $(DDOC_VARS_PRERELEASE_VERBATIM) \
682+
${MAKE} --directory=${PHOBOS_DIR} -f posix.mak html $(DDOC_VARS_PRERELEASE_VERBATIM) \
682683
DOC_OUTPUT_DIR=$W/phobos-prerelease-verbatim
683684
$(call CHANGE_SUFFIX,html,verbatim,$W/phobos-prerelease-verbatim)
684685
mv $W/phobos-prerelease-verbatim/* $(dir $@)
@@ -726,7 +727,7 @@ else
726727
endif
727728

728729
$G/docs-latest.json : ${DMD_LATEST} ${DMD_LATEST_DIR} \
729-
${DRUNTIME_LATEST_DIR} ${PHOBOS_LATEST_FILES_GENERATED} | dpl-docs
730+
${DRUNTIME_LATEST_DIR} ${PHOBOS_LATEST_FILES} | dpl-docs
730731
# remove this after https://github.com/dlang/dmd/pull/7513 has been merged
731732
if [ -f $(DMD_LATEST_DIR)/src/*/objc_glue_stubs.d ] ; then \
732733
DMD_EXCLUDE_LATEST_BASH="-e /objc_glue.d/d"; \
@@ -735,17 +736,17 @@ $G/docs-latest.json : ${DMD_LATEST} ${DMD_LATEST_DIR} \
735736
sed -e /mscoff/d $${DMD_EXCLUDE_LATEST_BASH} ${DMD_EXCLUDE_LATEST}
736737
find ${DRUNTIME_LATEST_DIR}/src -name '*.d' | \
737738
sed -e /unittest.d/d -e /gcstub/d >> $G/.latest-files.txt
738-
find ${PHOBOS_LATEST_DIR_GENERATED} -name '*.d' | \
739+
find ${PHOBOS_LATEST_DIR} -name '*.d' | \
739740
sed -e /unittest.d/d | sort >> $G/.latest-files.txt
740741
${DMD_LATEST} -J$(DMD_LATEST_DIR)/res -J$(dir $(DMD_LATEST)) -c -o- -version=CoreDdoc \
741742
-version=MARS -version=CoreDdoc -version=StdDdoc -Df$G/.latest-dummy.html \
742-
-Xf$@ -I${PHOBOS_LATEST_DIR_GENERATED} @$G/.latest-files.txt
743+
-Xf$@ -I${PHOBOS_LATEST_DIR} @$G/.latest-files.txt
743744
${DPL_DOCS} filter $@ --min-protection=Protected \
744745
--only-documented $(MOD_EXCLUDES_LATEST)
745746
rm -f $G/.latest-files.txt $G/.latest-dummy.html
746747

747748
$G/docs-prerelease.json : ${DMD} ${DMD_DIR} ${DRUNTIME_DIR} \
748-
${PHOBOS_FILES_GENERATED} | dpl-docs
749+
${PHOBOS_FILES} | dpl-docs
749750
# remove this after https://github.com/dlang/dmd/pull/7513 has been merged
750751
if [ -f $(DMD_DIR)/src/*/objc_glue_stubs.d ] ; then \
751752
DMD_EXCLUDE_PRERELEASE="-e /objc_glue.d/d"; \
@@ -754,11 +755,11 @@ $G/docs-prerelease.json : ${DMD} ${DMD_DIR} ${DRUNTIME_DIR} \
754755
sed -e /mscoff/d $${DMD_EXCLUDE_PRERELEASE} > $G/.prerelease-files.txt
755756
find ${DRUNTIME_DIR}/src -name '*.d' | \
756757
sed -e /unittest/d >> $G/.prerelease-files.txt
757-
find ${PHOBOS_DIR_GENERATED} -name '*.d' | \
758+
find ${PHOBOS_DIR} -name '*.d' | \
758759
sed -e /unittest.d/d | sort >> $G/.prerelease-files.txt
759760
${DMD} -J$(DMD_DIR)/res -J$(dir $(DMD)) -c -o- -version=MARS -version=CoreDdoc \
760761
-version=StdDdoc -Df$G/.prerelease-dummy.html \
761-
-Xf$@ -I${PHOBOS_DIR_GENERATED} @$G/.prerelease-files.txt
762+
-Xf$@ -I${PHOBOS_DIR} @$G/.prerelease-files.txt
762763
${DPL_DOCS} filter $@ --min-protection=Protected \
763764
--only-documented $(MOD_EXCLUDES_PRERELEASE)
764765
rm -f $G/.prerelease-files.txt $G/.prerelease-dummy.html
@@ -819,42 +820,6 @@ d-release.tag d-tags-release.json : chmgen.d $(STABLE_DMD) $(ALL_FILES) phobos-r
819820
d-prerelease.tag d-tags-prerelease.json : chmgen.d $(STABLE_DMD) $(ALL_FILES) phobos-prerelease druntime-prerelease chm-nav-prerelease.json
820821
$(STABLE_RDMD) chmgen.d --root=$W --only-tags --target prerelease
821822

822-
################################################################################
823-
# Assert -> writeln magic
824-
# -----------------------
825-
#
826-
# - This transforms assert(a == b) to writeln(a); // b
827-
# - It creates a copy of Phobos to apply the transformations
828-
# - All "d" files are piped through the transformator,
829-
# other needed files (e.g. posix.mak) get copied over
830-
#
831-
# See also: https://dlang.org/blog/2017/03/08/editable-and-runnable-doc-examples-on-dlang-org
832-
################################################################################
833-
834-
ASSERT_WRITELN_BIN = $(GENERATED)/assert_writeln_magic
835-
836-
$(ASSERT_WRITELN_BIN): assert_writeln_magic.d $(DUB) $(STABLE_DMD)
837-
@mkdir -p $(dir $@)
838-
$(DUB) build --single --compiler=$(STABLE_DMD) $<
839-
@mv ./assert_writeln_magic $@
840-
841-
$(ASSERT_WRITELN_BIN)_test: assert_writeln_magic.d $(DUB) $(STABLE_DMD)
842-
@mkdir -p $(dir $@)
843-
$(DUB) build --single --compiler=$(STABLE_DMD) --build=unittest $<
844-
@mv ./assert_writeln_magic $@
845-
846-
$(PHOBOS_FILES_GENERATED): $(PHOBOS_DIR_GENERATED)/%: $(PHOBOS_DIR)/% $(DUB) $(ASSERT_WRITELN_BIN)
847-
@mkdir -p $(dir $@)
848-
@if [ $(subst .,, $(suffix $@)) = "d" ] && [ "$@" != "$(PHOBOS_DIR_GENERATED)/index.d" ] ; then \
849-
$(ASSERT_WRITELN_BIN) -i $< -o $@ ; \
850-
else cp $< $@ ; fi
851-
852-
$(PHOBOS_LATEST_FILES_GENERATED): $(PHOBOS_LATEST_DIR_GENERATED)/%: $(PHOBOS_LATEST_DIR)/% $(DUB) $(ASSERT_WRITELN_BIN)
853-
@mkdir -p $(dir $@)
854-
@if [ $(subst .,, $(suffix $@)) = "d" ] && [ "$@" != "$(PHOBOS_LATEST_DIR_GENERATED)/index.d" ] ; then \
855-
$(ASSERT_WRITELN_BIN) -i $< -o $@ ; \
856-
else cp $< $@ ; fi
857-
858823
################################################################################
859824
# Style tests
860825
################################################################################
@@ -961,9 +926,18 @@ $G/contributors_list.ddoc: | $(STABLE_RDMD) $(TOOLS_DIR) $(INSTALLER_DIR)
961926
#
962927
# This allows extending Ddoc files dynamically on-the-fly.
963928
# It is currently only used for the specification pages
929+
#
930+
# It does:
931+
# - dynamic TOC generation
932+
# - Assert -> writeln magic (https://dlang.org/blog/2017/03/08/editable-and-runnable-doc-examples-on-dlang-org)
933+
# - This transforms assert(a == b) to writeln(a); // b
934+
# - It creates a copy of Phobos to apply the transformations
935+
# - All "d" files are piped through the transformator,
936+
# other needed files (e.g. posix.mak) get copied over
964937
################################################################################
965938

966939
$(DDOC_BIN): ddoc.d | $(STABLE_DMD)
967940
$(STABLE_DMD) -of$@ $<
941+
# TODO: use assert pipeline here
968942

969943
.DELETE_ON_ERROR: # GNU Make directive (delete output files on error)

0 commit comments

Comments
 (0)