mirror of
https://github.com/ElementsProject/lightning.git
synced 2026-08-13 12:32:55 +02:00
9c378dd247
- Fix `check-config-docs` script and it is using `jq` now - `check-config-docs` skips options listed in doc/undoc-flags.list - Add missing fields and deprecation information in listconfigs - Add missing field in lightningd-config - Other build generated updates
367 lines
11 KiB
Makefile
367 lines
11 KiB
Makefile
#! /usr/bin/make
|
|
|
|
# Designed to be run one level up
|
|
doc-wrongdir:
|
|
$(MAKE) -C .. doc-all
|
|
|
|
MARKDOWNPAGES := doc/addgossip.7 \
|
|
doc/addpsbtoutput.7 \
|
|
doc/askrene-age.7 \
|
|
doc/askrene-bias-channel.7 \
|
|
doc/askrene-bias-node.7 \
|
|
doc/askrene-create-channel.7 \
|
|
doc/askrene-create-layer.7 \
|
|
doc/askrene-disable-node.7 \
|
|
doc/askrene-inform-channel.7 \
|
|
doc/askrene-listlayers.7 \
|
|
doc/askrene-listreservations.7 \
|
|
doc/askrene-remove-layer.7 \
|
|
doc/askrene-reserve.7 \
|
|
doc/askrene-unreserve.7 \
|
|
doc/askrene-update-channel.7 \
|
|
doc/autoclean-once.7 \
|
|
doc/autoclean-status.7 \
|
|
doc/batching.7 \
|
|
doc/bkpr-channelsapy.7 \
|
|
doc/bkpr-dumpincomecsv.7 \
|
|
doc/bkpr-editdescriptionbyoutpoint.7 \
|
|
doc/bkpr-editdescriptionbypaymentid.7 \
|
|
doc/bkpr-inspect.7 \
|
|
doc/bkpr-listaccountevents.7 \
|
|
doc/bkpr-listbalances.7 \
|
|
doc/bkpr-listincome.7 \
|
|
doc/bkpr-report.7 \
|
|
doc/blacklistrune.7 \
|
|
doc/cancelrecurringinvoice.7 \
|
|
doc/check.7 \
|
|
doc/checkmessage.7 \
|
|
doc/checkrune.7 \
|
|
doc/clnrest-register-path.7 \
|
|
doc/close.7 \
|
|
doc/commando.7 \
|
|
doc/connect.7 \
|
|
doc/createinvoice.7 \
|
|
doc/createonion.7 \
|
|
doc/createproof.7 \
|
|
doc/createrune.7 \
|
|
doc/currencyconvert.7 \
|
|
doc/currencyrate.7 \
|
|
doc/datastore.7 \
|
|
doc/datastoreusage.7 \
|
|
doc/decode.7 \
|
|
doc/deldatastore.7 \
|
|
doc/delforward.7 \
|
|
doc/delinvoice.7 \
|
|
doc/delnetworkevent.7 \
|
|
doc/delpay.7 \
|
|
doc/deprecations.7 \
|
|
doc/dev-forget-channel.7 \
|
|
doc/dev-splice.7 \
|
|
doc/disableinvoicerequest.7 \
|
|
doc/disableoffer.7 \
|
|
doc/disconnect.7 \
|
|
doc/emergencyrecover.7 \
|
|
doc/enableoffer.7 \
|
|
doc/exposesecret.7 \
|
|
doc/feerates.7 \
|
|
doc/fetchbip353.7 \
|
|
doc/fetchinvoice.7 \
|
|
doc/fundchannel_cancel.7 \
|
|
doc/fundchannel_complete.7 \
|
|
doc/fundchannel.7 \
|
|
doc/fundchannel_start.7 \
|
|
doc/funderupdate.7 \
|
|
doc/fundpsbt.7 \
|
|
doc/getemergencyrecoverdata.7 \
|
|
doc/getinfo.7 \
|
|
doc/getlog.7 \
|
|
doc/getroute.7 \
|
|
doc/getroutes.7 \
|
|
doc/graceful.7 \
|
|
doc/help.7 \
|
|
doc/injectonionmessage.7 \
|
|
doc/injectpaymentonion.7 \
|
|
doc/invoice.7 \
|
|
doc/invoicerequest.7 \
|
|
doc/keysend.7 \
|
|
doc/listaddresses.7 \
|
|
doc/listchainmoves.7 \
|
|
doc/listchannelmoves.7 \
|
|
doc/listchannels.7 \
|
|
doc/listclosedchannels.7 \
|
|
doc/listconfigs.7 \
|
|
doc/listcurrencyrates.7 \
|
|
doc/listdatastore.7 \
|
|
doc/listforwards.7 \
|
|
doc/listfunds.7 \
|
|
doc/listhtlcs.7 \
|
|
doc/listinvoicerequests.7 \
|
|
doc/listinvoices.7 \
|
|
doc/listnetworkevents.7 \
|
|
doc/listnodes.7 \
|
|
doc/listoffers.7 \
|
|
doc/listpays.7 \
|
|
doc/listpeerchannels.7 \
|
|
doc/listpeers.7 \
|
|
doc/listsendpays.7 \
|
|
doc/listtransactions.7 \
|
|
doc/makesecret.7 \
|
|
doc/multifundchannel.7 \
|
|
doc/multiwithdraw.7 \
|
|
doc/newaddr.7 \
|
|
doc/notifications.7 \
|
|
doc/offer.7 \
|
|
doc/openchannel_abort.7 \
|
|
doc/openchannel_bump.7 \
|
|
doc/openchannel_init.7 \
|
|
doc/openchannel_signed.7 \
|
|
doc/openchannel_update.7 \
|
|
doc/parsefeerate.7 \
|
|
doc/pay.7 \
|
|
doc/ping.7 \
|
|
doc/plugin.7 \
|
|
doc/preapproveinvoice.7 \
|
|
doc/preapprovekeysend.7 \
|
|
doc/reckless.7 \
|
|
doc/recoverchannel.7 \
|
|
doc/recover.7 \
|
|
doc/renepay.7 \
|
|
doc/renepaystatus.7 \
|
|
doc/reserveinputs.7 \
|
|
doc/sendamount.7 \
|
|
doc/sendcustommsg.7 \
|
|
doc/sendinvoice.7 \
|
|
doc/sendonion.7 \
|
|
doc/sendpay.7 \
|
|
doc/sendpsbt.7 \
|
|
doc/setchannel.7 \
|
|
doc/setconfig.7 \
|
|
doc/setpsbtversion.7 \
|
|
doc/showrunes.7 \
|
|
doc/signinvoice.7 \
|
|
doc/signmessage.7 \
|
|
doc/signmessagewithkey.7 \
|
|
doc/signpsbt.7 \
|
|
doc/splicein.7 \
|
|
doc/splice_init.7 \
|
|
doc/splice_signed.7 \
|
|
doc/splice_update.7 \
|
|
doc/spliceout.7 \
|
|
doc/staticbackup.7 \
|
|
doc/stop.7 \
|
|
doc/txdiscard.7 \
|
|
doc/txprepare.7 \
|
|
doc/txsend.7 \
|
|
doc/unreserveinputs.7 \
|
|
doc/upgradewallet.7 \
|
|
doc/utxopsbt.7 \
|
|
doc/waitanyinvoice.7 \
|
|
doc/waitblockheight.7 \
|
|
doc/waitinvoice.7 \
|
|
doc/wait.7 \
|
|
doc/waitsendpay.7 \
|
|
doc/withdraw.7 \
|
|
doc/xkeysend.7 \
|
|
doc/xpay.7
|
|
|
|
NOTIFICATION_SCHEMAS := $(wildcard doc/schemas/notification/*.json)
|
|
NOTIFICATION_MARKDOWNPAGES := $(patsubst doc/schemas/notification/%.json,doc/notification-%.7,$(NOTIFICATION_SCHEMAS))
|
|
|
|
HOOK_SCHEMAS := $(wildcard doc/schemas/hook/*.json)
|
|
HOOK_MARKDOWNPAGES := $(patsubst doc/schemas/hook/%.json,doc/hook-%.7,$(HOOK_SCHEMAS))
|
|
|
|
MARKDOWNPAGES += $(NOTIFICATION_MARKDOWNPAGES) $(HOOK_MARKDOWNPAGES)
|
|
|
|
$(foreach s,$(wildcard doc/schemas/*.json), \
|
|
$(eval doc/$(basename $(notdir $(s))).7.md: $(s)))
|
|
|
|
$(foreach s,$(wildcard doc/schemas/notification/*.json), \
|
|
$(eval doc/notification-$(basename $(notdir $(s))).7.md: $(s)))
|
|
|
|
$(foreach s,$(wildcard doc/schemas/hook/*.json), \
|
|
$(eval doc/hook-$(basename $(notdir $(s))).7.md: $(s)))
|
|
|
|
ifeq ($(HAVE_SQLITE3),1)
|
|
MARKDOWNPAGES += doc/listsqlschemas.7 doc/sql.7
|
|
endif
|
|
|
|
PREFIXED_MANPAGES := $(MARKDOWNPAGES:doc/%.7=doc/lightning-%.7)
|
|
NON_PREFIXED_MANPAGES := doc/lightning-cli.1 \
|
|
doc/lightningd.8 \
|
|
doc/lightningd-config.5 \
|
|
doc/lightningd-rpc.7 \
|
|
doc/lightning-hsmtool.8 \
|
|
doc/lightning-downgrade.8 \
|
|
doc/lightning-reckless.1
|
|
|
|
MANPAGES := $(PREFIXED_MANPAGES) $(NON_PREFIXED_MANPAGES)
|
|
|
|
MARKDOWNPAGES_WITH_EXT := $(MARKDOWNPAGES:=.md)
|
|
NON_PREFIXED_MARKDOWNPAGES_WITH_EXT := $(NON_PREFIXED_MANPAGES:=.md)
|
|
OLD_MARKDOWNPAGES_WITH_EXT := $(PREFIXED_MANPAGES:=.md)
|
|
|
|
|
|
# - Read the json template from schemas/sql-template.json
|
|
# - Generate the tables schema via plugins/sql
|
|
# - Merge both and generate final schemas/sql.json
|
|
doc/schemas/sql.json: doc/schemas/sql-template.json plugins/sql
|
|
@plugins/sql --print-docs | jq --arg sqldata "$$(awk '{printf "%s\n", $$0}')" '.tables += [$$sqldata]' $< > "$@.tmp" && mv "$@.tmp" "$@";
|
|
|
|
doc-all: $(MANPAGES) doc/index.rst
|
|
|
|
SCHEMAS := $(wildcard doc/schemas/*.json) $(NOTIFICATION_SCHEMAS) $(HOOK_SCHEMAS)
|
|
|
|
# Don't try to build sql.json tables with plugins/sql if we don't have sqlite3
|
|
ifeq ($(HAVE_SQLITE3),0)
|
|
SCHEMAS := $(filter-out doc/schemas/sql.json, $(SCHEMAS))
|
|
endif
|
|
|
|
check-fmt-schemas: $(SCHEMAS:%=check-fmt-schema/%)
|
|
fmt-schemas: $(SCHEMAS:%=fmt-schema/%)
|
|
|
|
check-fmt-schema/%: %
|
|
@jq . < "$*" > "$*".fmt && diff -u "$*" "$*.fmt" && rm "$*.fmt"
|
|
|
|
fmt-schema/%: %
|
|
@jq . < "$*" > "$*".fmt && cat "$*".fmt > "$*" && rm "$*.fmt"
|
|
|
|
check-doc: check-config-docs check-manpages check-fmt-schemas
|
|
|
|
# These are hard to use in $(call) functions.
|
|
LBRACKET=(
|
|
RBRACKET=)
|
|
|
|
doc/sql.7.md: doc/schemas/sql.json
|
|
|
|
$(MARKDOWNPAGES_WITH_EXT): doc/%.7.md: tools/fromschema.py
|
|
@base="$*"; \
|
|
json="doc/schemas/$$base.json"; \
|
|
if [ ! -f "$$json" ]; then \
|
|
case "$$base" in \
|
|
notification-*) \
|
|
name=$${base#notification-}; \
|
|
json="doc/schemas/notification/$$name.json"; \
|
|
;; \
|
|
hook-*) \
|
|
name=$${base#hook-}; \
|
|
json="doc/schemas/hook/$$name.json"; \
|
|
;; \
|
|
esac; \
|
|
fi; \
|
|
if [ ! -f "$$json" ]; then \
|
|
echo "No schema found for $@ (looked for $$json)"; \
|
|
exit 1; \
|
|
fi; \
|
|
tools/fromschema.py --markdownfile=$@ $$json > $@.tmp && mv $@.tmp $@
|
|
|
|
|
|
LOWDOWN := lowdown
|
|
|
|
# For versions in documentation, we don't change with every git version, to
|
|
# save build time. We build them on new tags or keep them on pre-next-release version.
|
|
doc/.doc_version: version_gen.h
|
|
@case "$(VERSION)" in \
|
|
*-*-g*) \
|
|
DOC_VERSION="pre-$(CLN_NEXT_VERSION)";; \
|
|
*) \
|
|
DOC_VERSION="$(VERSION)";; \
|
|
esac; \
|
|
echo $$DOC_VERSION > $@.new
|
|
@if cmp $@.new $@ >/dev/null 2>&1; then rm -f $@.new; else mv $@.new $@; $(ECHO) Documentation version updated to `cat doc/.doc_version`; fi
|
|
|
|
$(PREFIXED_MANPAGES): doc/lightning-%: doc/%.md tools/md2man.sh doc/.doc_version
|
|
@VERSION=`cat doc/.doc_version` SED=$(SED) tools/md2man.sh $(LOWDOWN) $<
|
|
$(NON_PREFIXED_MANPAGES): doc/%: doc/%.md tools/md2man.sh doc/.doc_version
|
|
@VERSION=`cat doc/.doc_version` SED=$(SED) tools/md2man.sh $(LOWDOWN) $<
|
|
|
|
doc/protocol-%.svg: test/test_protocol
|
|
test/test_protocol --svg < test/commits/$*.script > $@
|
|
|
|
protocol-diagrams: $(patsubst %.script, doc/protocol-%.svg, $(notdir $(wildcard test/commits/*.script)))
|
|
|
|
doc/deployable-lightning.pdf: doc/deployable-lightning.lyx doc/bitcoin.bib
|
|
lyx -E pdf $@ $<
|
|
|
|
doc/deployable-lightning.tex: doc/deployable-lightning.lyx
|
|
lyx -E latex $@ $<
|
|
|
|
state-diagrams: doc/normal-states.svg doc/simplified-states.svg doc/error-states.svg doc/full-states.svg
|
|
|
|
%.svg: %.dot
|
|
dot -Tsvg $< > $@ || (rm -f $@; false)
|
|
|
|
doc/simplified-states.dot: test/test_state_coverage
|
|
test/test_state_coverage --dot --dot-simplify > $@
|
|
|
|
doc/normal-states.dot: test/test_state_coverage
|
|
test/test_state_coverage --dot > $@
|
|
|
|
doc/error-states.dot: test/test_state_coverage
|
|
test/test_state_coverage --dot-all --dot-include-errors > $@
|
|
|
|
doc/full-states.dot: test/test_state_coverage
|
|
test/test_state_coverage --dot-all --dot-include-errors --dot-include-nops > $@
|
|
|
|
clean: doc-clean
|
|
check: check-manpages
|
|
|
|
# This needs plugins, too.
|
|
check-manpages: all-programs check-config-docs default-targets
|
|
@SED=$(SED) tools/check-manpage.sh cli/lightning-cli doc/lightning-cli.1.md
|
|
@SED=$(SED) tools/check-manpage.sh "lightningd/lightningd --lightning-dir=/tmp/" doc/lightningd-config.5.md
|
|
@awk '/^$$/ { do { getline } while ($$0 ~ /^( {4,}|\t)/) } /^\s*```/ { do { getline } while ($$0 !~ /^\s*```/) } /^([^`_\\]|`([^`\\]|\\.)*`|\b_|_\b|\\.)*\B_\B/ { print "" ; print "Unescaped underscore at " FILENAME ":" NR ":" ; print ; ret = 1 } ENDFILE { NR = 0 } END { exit ret }' doc/*.[0-9].md
|
|
|
|
# Verify bidirectional consistency between JSON schema and man page
|
|
# First loop (schema to man page):
|
|
# Extract all non-deprecated schema properties, excluding internal fields (conf, plugins, important-plugins)
|
|
# and intentionally undocumented options (doc/undoc-flags.list).
|
|
# Check each appears in man page as '* **option**' or '* **option=**'.
|
|
#
|
|
# Second loop (man page to schema):
|
|
# Extract all man page options, excluding:
|
|
# - Plugin-specific options (lines with '[plugin ')
|
|
# - Command-line only flags (help, version)
|
|
# - Network aliases (mainnet, testnet, testnet4, signet)
|
|
# - Plugin management directives (plugin, important-plugin, plugin-dir, clear-plugins)
|
|
# Check each remaining option exists as a key in schema's configs.properties.
|
|
check-config-docs:
|
|
@for c in `jq -r '.response.properties.configs.properties | to_entries[] | select(.value.deprecated == null) | .key' doc/schemas/listconfigs.json \
|
|
| grep -v '^conf$$' \
|
|
| grep -v '^plugins$$' \
|
|
| grep -v '^important-plugins$$'`; do \
|
|
if grep -Eq "^$$c=?$$" doc/undoc-flags.list; then \
|
|
continue; \
|
|
fi; \
|
|
if ! grep -q "^\* \*\*$$c\*\*" doc/lightningd-config.5.md && ! grep -q "^\* \*\*$$c=" doc/lightningd-config.5.md; then \
|
|
echo "$$c is undocumented in markdown but is in schema!"; \
|
|
exit 1; \
|
|
fi; \
|
|
done
|
|
@for c in `grep '^\* \*\*' doc/lightningd-config.5.md | grep -v '\[plugin ' | sed -n 's/^\* \*\*\([^*=]*\)[=*].*/\1/p' \
|
|
| grep -v '^\(help\|version\|mainnet\|testnet\|testnet4\|signet\|plugin\|important-plugin\|plugin-dir\|clear-plugins\)$$'`; do \
|
|
if ! jq -r '.response.properties.configs.properties | keys[]' doc/schemas/listconfigs.json | grep -qx "$$c"; then \
|
|
echo "$$c documented in markdown but not in schema!"; \
|
|
exit 1; \
|
|
fi; \
|
|
done
|
|
@echo "Config docs check passed!"
|
|
|
|
doc-clean:
|
|
$(RM) $(MANPAGES) $(MARKDOWNPAGES_WITH_EXT) $(OLD_MARKDOWNPAGES_WITH_EXT) doc/.doc_version
|
|
$(RM) doc/deployable-lightning.{aux,bbl,blg,dvi,log,out,tex}
|
|
|
|
doc/index.rst: $(MARKDOWNPAGES_WITH_EXT) $(NON_PREFIXED_MARKDOWNPAGES_WITH_EXT) Makefile
|
|
@$(call VERBOSE, "genidx $@", \
|
|
for m in $(MARKDOWNPAGES_WITH_EXT) $(NON_PREFIXED_MARKDOWNPAGES_WITH_EXT); do \
|
|
base=$$(basename "$$m"); \
|
|
echo "$$base" | \
|
|
$(SED) -E 's/^(.*)\.([0-9]+)\.md$$/\1 <\1.\2.md>/; t; s/^(.*)\.md$$/\1 <\1.md>/'; \
|
|
done | \
|
|
LC_ALL=C sort | \
|
|
$(PYTHON) devtools/blockreplace.py doc/index.rst manpages --language=rst --indent " " \
|
|
)
|
|
|
|
# Overridden by GH CI if necessary.
|
|
BASE_REF=master
|
|
|
|
check-source:
|