3c89031e1f
This is a work in progress, but this should get *extensive* review, so I'm putting it up early and often. This is the start of a draft of the new 'ownership guide,' which explains ownership, borrowing, etc. I'm feeling better about this framing than last time's, but we'll see.
300 lines
8.9 KiB
Makefile
300 lines
8.9 KiB
Makefile
# Copyright 2012-2013 The Rust Project Developers. See the COPYRIGHT
|
|
# file at the top-level directory of this distribution and at
|
|
# http://rust-lang.org/COPYRIGHT.
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
|
|
# http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
|
|
# <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
|
|
# option. This file may not be copied, modified, or distributed
|
|
# except according to those terms.
|
|
|
|
######################################################################
|
|
# The various pieces of standalone documentation: guides, manual, etc
|
|
#
|
|
# The DOCS variable is their names (with no file extension).
|
|
#
|
|
# PDF_DOCS lists the targets for which PDF documentation should be
|
|
# build.
|
|
#
|
|
# RUSTDOC_FLAGS_xyz variables are extra arguments to pass to the
|
|
# rustdoc invocation for xyz.
|
|
#
|
|
# RUSTDOC_DEPS_xyz are extra dependencies for the rustdoc invocation
|
|
# on xyz.
|
|
#
|
|
# L10N_LANGS are the languages for which the docs have been
|
|
# translated.
|
|
######################################################################
|
|
DOCS := index intro tutorial guide guide-ffi guide-macros guide-ownership \
|
|
guide-tasks guide-container guide-pointers guide-testing \
|
|
guide-plugin guide-crates complement-bugreport guide-error-handling \
|
|
complement-lang-faq complement-design-faq complement-project-faq \
|
|
rustdoc guide-unsafe guide-strings reference
|
|
|
|
PDF_DOCS := guide reference
|
|
|
|
RUSTDOC_DEPS_reference := doc/full-toc.inc
|
|
RUSTDOC_FLAGS_reference := --html-in-header=doc/full-toc.inc
|
|
|
|
L10N_LANGS := ja
|
|
|
|
# Generally no need to edit below here.
|
|
|
|
# The options are passed to the documentation generators.
|
|
RUSTDOC_HTML_OPTS_NO_CSS = --html-before-content=doc/version_info.html \
|
|
--html-in-header=doc/favicon.inc \
|
|
--html-after-content=doc/footer.inc \
|
|
--markdown-playground-url='http://play.rust-lang.org/'
|
|
|
|
RUSTDOC_HTML_OPTS = $(RUSTDOC_HTML_OPTS_NO_CSS) --markdown-css rust.css
|
|
|
|
PANDOC_BASE_OPTS := --standalone --toc --number-sections
|
|
PANDOC_TEX_OPTS = $(PANDOC_BASE_OPTS) --include-before-body=doc/version.tex \
|
|
--from=markdown --include-before-body=doc/footer.tex --to=latex
|
|
PANDOC_EPUB_OPTS = $(PANDOC_BASE_OPTS) --to=epub
|
|
|
|
# The rustdoc executable...
|
|
RUSTDOC_EXE = $(HBIN2_H_$(CFG_BUILD))/rustdoc$(X_$(CFG_BUILD))
|
|
# ...with rpath included in case --disable-rpath was provided to
|
|
# ./configure
|
|
RUSTDOC = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(RUSTDOC_EXE)
|
|
|
|
D := $(S)src/doc
|
|
|
|
DOC_TARGETS :=
|
|
COMPILER_DOC_TARGETS :=
|
|
DOC_L10N_TARGETS :=
|
|
|
|
# If NO_REBUILD is set then break the dependencies on rustdoc so we
|
|
# build the documentation without having to rebuild rustdoc.
|
|
ifeq ($(NO_REBUILD),)
|
|
HTML_DEPS := $(RUSTDOC_EXE)
|
|
else
|
|
HTML_DEPS :=
|
|
endif
|
|
|
|
# Check for the various external utilities for the EPUB/PDF docs:
|
|
|
|
ifeq ($(CFG_LUALATEX),)
|
|
$(info cfg: no lualatex found, deferring to xelatex)
|
|
ifeq ($(CFG_XELATEX),)
|
|
$(info cfg: no xelatex found, deferring to pdflatex)
|
|
ifeq ($(CFG_PDFLATEX),)
|
|
$(info cfg: no pdflatex found, disabling LaTeX docs)
|
|
NO_PDF_DOCS = 1
|
|
else
|
|
CFG_LATEX := $(CFG_PDFLATEX)
|
|
endif
|
|
else
|
|
CFG_LATEX := $(CFG_XELATEX)
|
|
XELATEX = 1
|
|
endif
|
|
else
|
|
CFG_LATEX := $(CFG_LUALATEX)
|
|
endif
|
|
|
|
|
|
ifeq ($(CFG_PANDOC),)
|
|
$(info cfg: no pandoc found, omitting PDF and EPUB docs)
|
|
ONLY_HTML_DOCS = 1
|
|
endif
|
|
|
|
|
|
######################################################################
|
|
# Rust version
|
|
######################################################################
|
|
|
|
doc/version.tex: $(MKFILE_DEPS) $(wildcard $(D)/*.*) | doc/
|
|
@$(call E, version-stamp: $@)
|
|
$(Q)echo "$(CFG_VERSION)" >$@
|
|
|
|
HTML_DEPS += doc/version_info.html
|
|
doc/version_info.html: $(D)/version_info.html.template $(MKFILE_DEPS) \
|
|
$(wildcard $(D)/*.*) | doc/
|
|
@$(call E, version-info: $@)
|
|
$(Q)sed -e "s/VERSION/$(CFG_RELEASE)/; \
|
|
s/SHORT_HASH/$(CFG_SHORT_VER_HASH)/; \
|
|
s/STAMP/$(CFG_VER_HASH)/;" $< >$@
|
|
|
|
GENERATED += doc/version.tex doc/version_info.html
|
|
|
|
######################################################################
|
|
# Docs, from rustdoc and sometimes pandoc
|
|
######################################################################
|
|
|
|
doc/:
|
|
@mkdir -p $@
|
|
|
|
HTML_DEPS += doc/rust.css
|
|
doc/rust.css: $(D)/rust.css | doc/
|
|
@$(call E, cp: $@)
|
|
$(Q)cp -a $< $@ 2> /dev/null
|
|
|
|
HTML_DEPS += doc/favicon.inc
|
|
doc/favicon.inc: $(D)/favicon.inc | doc/
|
|
@$(call E, cp: $@)
|
|
$(Q)cp -a $< $@ 2> /dev/null
|
|
|
|
doc/full-toc.inc: $(D)/full-toc.inc | doc/
|
|
@$(call E, cp: $@)
|
|
$(Q)cp -a $< $@ 2> /dev/null
|
|
|
|
HTML_DEPS += doc/footer.inc
|
|
doc/footer.inc: $(D)/footer.inc | doc/
|
|
@$(call E, cp: $@)
|
|
$(Q)cp -a $< $@ 2> /dev/null
|
|
|
|
# The (english) documentation for each doc item.
|
|
|
|
define DEF_SHOULD_BUILD_PDF_DOC
|
|
SHOULD_BUILD_PDF_DOC_$(1) = 1
|
|
endef
|
|
$(foreach docname,$(PDF_DOCS),$(eval $(call DEF_SHOULD_BUILD_PDF_DOC,$(docname))))
|
|
|
|
doc/footer.tex: $(D)/footer.inc | doc/
|
|
@$(call E, pandoc: $@)
|
|
$(CFG_PANDOC) --from=html --to=latex $< --output=$@
|
|
|
|
# HTML (rustdoc)
|
|
DOC_TARGETS += doc/not_found.html
|
|
doc/not_found.html: $(D)/not_found.md $(HTML_DEPS) | doc/
|
|
@$(call E, rustdoc: $@)
|
|
$(Q)$(RUSTDOC) $(RUSTDOC_HTML_OPTS_NO_CSS) \
|
|
--markdown-css http://doc.rust-lang.org/rust.css $<
|
|
|
|
define DEF_DOC
|
|
|
|
# HTML (rustdoc)
|
|
DOC_TARGETS += doc/$(1).html
|
|
doc/$(1).html: $$(D)/$(1).md $$(HTML_DEPS) $$(RUSTDOC_DEPS_$(1)) | doc/
|
|
@$$(call E, rustdoc: $$@)
|
|
$$(Q)$$(RUSTDOC) $$(RUSTDOC_HTML_OPTS) $$(RUSTDOC_FLAGS_$(1)) $$<
|
|
|
|
ifneq ($(ONLY_HTML_DOCS),1)
|
|
|
|
# EPUB (pandoc directly)
|
|
DOC_TARGETS += doc/$(1).epub
|
|
doc/$(1).epub: $$(D)/$(1).md | doc/
|
|
@$$(call E, pandoc: $$@)
|
|
$$(CFG_PANDOC) $$(PANDOC_EPUB_OPTS) $$< --output=$$@
|
|
|
|
# PDF (md =(pandoc)=> tex =(pdflatex)=> pdf)
|
|
DOC_TARGETS += doc/$(1).tex
|
|
doc/$(1).tex: $$(D)/$(1).md doc/footer.tex doc/version.tex | doc/
|
|
@$$(call E, pandoc: $$@)
|
|
$$(CFG_PANDOC) $$(PANDOC_TEX_OPTS) $$< --output=$$@
|
|
|
|
ifneq ($(NO_PDF_DOCS),1)
|
|
ifeq ($$(SHOULD_BUILD_PDF_DOC_$(1)),1)
|
|
DOC_TARGETS += doc/$(1).pdf
|
|
ifneq ($(XELATEX),1)
|
|
doc/$(1).pdf: doc/$(1).tex
|
|
@$$(call E, latex compiler: $$@)
|
|
$$(Q)$$(CFG_LATEX) \
|
|
-interaction=batchmode \
|
|
-output-directory=doc \
|
|
$$<
|
|
else
|
|
# The version of xelatex on the snap bots seemingly ingores -output-directory
|
|
# So we'll output to . and move to the doc directory manually.
|
|
# This will leave some intermediate files in the build directory.
|
|
doc/$(1).pdf: doc/$(1).tex
|
|
@$$(call E, latex compiler: $$@)
|
|
$$(Q)$$(CFG_LATEX) \
|
|
-interaction=batchmode \
|
|
-output-directory=. \
|
|
$$<
|
|
$$(Q)mv ./$(1).pdf $$@
|
|
endif # XELATEX
|
|
endif # SHOULD_BUILD_PDF_DOCS_$(1)
|
|
endif # NO_PDF_DOCS
|
|
|
|
endif # ONLY_HTML_DOCS
|
|
|
|
endef
|
|
|
|
$(foreach docname,$(DOCS),$(eval $(call DEF_DOC,$(docname))))
|
|
|
|
|
|
# Localized documentation
|
|
|
|
# FIXME: I (huonw) haven't actually been able to test properly, since
|
|
# e.g. (by default) I'm doing an out-of-tree build (#12763), but even
|
|
# adjusting for that, the files are too old(?) and are rejected by
|
|
# po4a.
|
|
#
|
|
# As such, I've attempted to get it working as much as possible (and
|
|
# switching from pandoc to rustdoc), but preserving the old behaviour
|
|
# (e.g. only running on the guide)
|
|
.PHONY: l10n-mds
|
|
l10n-mds: $(D)/po4a.conf \
|
|
$(foreach lang,$(L10N_LANG),$(D)/po/$(lang)/*.md.po)
|
|
$(warning WARNING: localized documentation is experimental)
|
|
po4a --copyright-holder="The Rust Project Developers" \
|
|
--package-name="Rust" \
|
|
--package-version="$(CFG_RELEASE)" \
|
|
-M UTF-8 -L UTF-8 \
|
|
$(D)/po4a.conf
|
|
|
|
define DEF_L10N_DOC
|
|
DOC_L10N_TARGETS += doc/l10n/$(1)/$(2).html
|
|
doc/l10n/$(1)/$(2).html: l10n-mds $$(HTML_DEPS) $$(RUSTDOC_DEPS_$(2))
|
|
@$$(call E, rustdoc: $$@)
|
|
$$(RUSTDOC) $$(RUSTDOC_HTML_OPTS) $$(RUSTDOC_FLAGS_$(1)) doc/l10n/$(1)/$(2).md
|
|
endef
|
|
|
|
$(foreach lang,$(L10N_LANGS),$(eval $(call DEF_L10N_DOC,$(lang),guide)))
|
|
|
|
|
|
######################################################################
|
|
# Rustdoc (libstd/extra)
|
|
######################################################################
|
|
|
|
|
|
# The library documenting macro
|
|
#
|
|
# $(1) - The crate name (std/extra)
|
|
#
|
|
# Passes --cfg stage2 to rustdoc because it uses the stage2 librustc.
|
|
define DEF_LIB_DOC
|
|
|
|
# If NO_REBUILD is set then break the dependencies on rustdoc so we
|
|
# build crate documentation without having to rebuild rustdoc.
|
|
ifeq ($(NO_REBUILD),)
|
|
LIB_DOC_DEP_$(1) = \
|
|
$$(CRATEFILE_$(1)) \
|
|
$$(RSINPUTS_$(1)) \
|
|
$$(RUSTDOC_EXE) \
|
|
$$(foreach dep,$$(RUST_DEPS_$(1)), \
|
|
$$(TLIB2_T_$(CFG_BUILD)_H_$(CFG_BUILD))/stamp.$$(dep) \
|
|
doc/$$(dep)/)
|
|
else
|
|
LIB_DOC_DEP_$(1) = $$(CRATEFILE_$(1)) $$(RSINPUTS_$(1))
|
|
endif
|
|
|
|
doc/$(1)/:
|
|
$$(Q)mkdir -p $$@
|
|
|
|
$(2) += doc/$(1)/index.html
|
|
doc/$(1)/index.html: CFG_COMPILER_HOST_TRIPLE = $(CFG_TARGET)
|
|
doc/$(1)/index.html: $$(LIB_DOC_DEP_$(1)) doc/$(1)/
|
|
@$$(call E, rustdoc: $$@)
|
|
$$(Q)CFG_LLVM_LINKAGE_FILE=$$(LLVM_LINKAGE_PATH_$(CFG_BUILD)) \
|
|
$$(RUSTDOC) --cfg dox --cfg stage2 $$<
|
|
endef
|
|
|
|
$(foreach crate,$(DOC_CRATES),$(eval $(call DEF_LIB_DOC,$(crate),DOC_TARGETS)))
|
|
$(foreach crate,$(COMPILER_DOC_CRATES),$(eval $(call DEF_LIB_DOC,$(crate),COMPILER_DOC_TARGETS)))
|
|
|
|
ifdef CFG_DISABLE_DOCS
|
|
$(info cfg: disabling doc build (CFG_DISABLE_DOCS))
|
|
DOC_TARGETS :=
|
|
COMPILER_DOC_TARGETS :=
|
|
endif
|
|
|
|
docs: $(DOC_TARGETS)
|
|
compiler-docs: $(COMPILER_DOC_TARGETS)
|
|
|
|
docs-l10n: $(DOC_L10N_TARGETS)
|
|
|
|
.PHONY: docs-l10n
|