From 334af011f01ceda1086d335231ada3363190b8a9 Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Fri, 14 Feb 2014 03:34:18 -0800 Subject: [PATCH] mk: Improve build system help commands --- Makefile.in | 112 +++++++++++++++++++++++++++++++++++++--------------- configure | 2 + mk/main.mk | 18 +++++++-- mk/tests.mk | 4 ++ 4 files changed, 101 insertions(+), 35 deletions(-) diff --git a/Makefile.in b/Makefile.in index 1d828f6ee4c..f83ddf76eef 100644 --- a/Makefile.in +++ b/Makefile.in @@ -8,55 +8,100 @@ # option. This file may not be copied, modified, or distributed # except according to those terms. -# +# \(^o^)/ # -# # The Rust Build System +# Greetings, adventurer! The Rust Build System is at your service. # -# Start with these these build targets: +# Whether you want a genuine copy of `rustc`, access to the latest and +# most authoritative Rust documentation, or even to investigate the +# most intimate workings of the compiler itself, you've come to the +# right place. Let's see what's on the menu. # -# * all - The default rule. Builds a complete stage2 compiler, std, -# and extra for all hosts and targets -# * docs - Generate HTML documentation for the std and extra libraries -# from source code comments -# * rustc - The stage 2 compiler for the build platform with standard -# and extra libraries -# * install -# * uninstall -# * check - Run tests -# * check-stage1-$(crate) - Run tests for a crate, e.g. `check-stage1-std` -# * check-stage1-rpass - Run the language tests -# * check-docs - Run the doc tests +# First, start with one of these build targets: +# +# * all - The default. Builds a complete, bootstrapped compiler. +# `rustc` will be in `${target-triple}/stage2/bin/`. Run it +# directly from the build directory if you like. This also +# comes with docs in `doc/`. +# +# * check - Run the complete test suite +# +# * install - Install Rust. Note that installation is not necessary +# to use the compiler. +# +# * uninstall - Uninstall the binaries +# +# For hot tips on working with The Rust Build System, just: +# +# type `make hot-tips` +# +# Otherwise +# +# type `make` +# +# +# +# +# +# # The Rust Build System Tip Line +# +# There are a bazillion different targets you might want to build. Here +# are a few ideas. +# +# * docs - Build gobs of HTML documentation and put it into `doc/` +# * check-$(crate) - Test a crate, e.g. `check-std` +# * check-ref - Run the language reference tests +# * check-docs - Test the documentation examples +# +# TODO: Lots more # # Then mix in some of these environment variables to harness the -# ultimate power of Rust Build System. +# ultimate power of The Rust Build System. # -# * `VERBOSE=1` - Print all commands. Use this to see what's going on. -# * `RUSTFLAGS=...` - Add compiler flags to all `rustc` invocations -# * `CFG_ENABLE_VALGRIND=1` - Run tests under valgrind -# * `VALGRIND_COMPILE=1` - Run the compiler itself under valgrind -# (may require `CFG_ENABLE_VALGRIND`) -# * `NO_REBUILD=1` - Don't rebootstrap when testing std -# (and possibly other crates) -# * `NO_MKFILE_DEPS=1` - Don rebuild for modified .mk files -# * `SAVE_TEMPS=1` - Use `--save-temps` flag on all `rustc` invocations -# * `ASM_COMMENTS=1` - Use `-Z asm-comments` -# * `TIME_PASSES=1` - Use `-Z time-passes` -# * `TIME_LLVM_PASSES=1` - Use `-Z time-llvm-passes` -# * `TRACE=1` - Use `-Z trace` +# * `VERBOSE=1` - Print all commands. Use this to see what's going on. +# * `RUSTFLAGS=...` - Add compiler flags to all `rustc` invocations +# +# * `TESTNAME=...` - Specify the name of tests to run +# * `CHECK_IGNORED=1` - Run normally-ignored tests +# * `NO_BENCH=1` - Don't run crate benchmarks (disable `--bench` flag) +# +# * `CFG_ENABLE_VALGRIND=1` - Run tests under valgrind +# * `VALGRIND_COMPILE=1` - Run the compiler itself under valgrind +# (may require `CFG_ENABLE_VALGRIND`) +# +# * `NO_REBUILD=1` - Don't rebootstrap when testing std +# (and possibly other crates) +# * `NO_MKFILE_DEPS=1` - Don rebuild for modified .mk files +# +# * `SAVE_TEMPS=1` - Use `--save-temps` flag on all `rustc` invocations +# * `ASM_COMMENTS=1` - Use `-Z asm-comments` +# * `TIME_PASSES=1` - Use `-Z time-passes` +# * `TIME_LLVM_PASSES=1` - Use `-Z time-llvm-passes` +# * `TRACE=1` - Use `-Z trace` # # This is hardly all there is to know of The Rust Build System's -# mysteries. Your journey continues on the wiki[1][2]. +# mysteries. The tale continues on the wiki[1][2]. # # [1]: https://github.com/mozilla/rust/wiki/Note-build-system # [2]: https://github.com/mozilla/rust/wiki/Note-testsuite # -# +# Unless you feel like getting your hands dirty, then: +# +# don't type `make nitty-gritty` +# +# +# +# +# +# # The Rust Build System +# +# Gosh I wish there was something useful here (TODO). # # # An (old) explanation of how the build is structured: # # *Note: Hey, like, this is probably inaccurate, and is definitely # an outdated and insufficient explanation of the remarkable -# and discomfiting Rust Build System.* +# Rust Build System.* # # There are multiple build stages (0-3) needed to verify that the # compiler is properly self-hosting. Each stage is divided between @@ -99,6 +144,9 @@ # will just link against the libraries in the target lib directory. # # Admittedly this is a little convoluted. +# +# +# ###################################################################### # Primary rules diff --git a/configure b/configure index de0b7680dcf..60d7efc7ac8 100755 --- a/configure +++ b/configure @@ -1103,3 +1103,5 @@ rm -f config.tmp touch config.stamp step_msg "complete" +msg "type \`make help\`" +msg diff --git a/mk/main.mk b/mk/main.mk index 723f659b7fd..c42b7b4757a 100644 --- a/mk/main.mk +++ b/mk/main.mk @@ -428,8 +428,20 @@ ALL_TARGET_RULES = $(foreach target,$(CFG_TARGET), \ all: $(ALL_TARGET_RULES) $(GENERATED) docs -help: -# Show the comments from Makefile.in as "help" +###################################################################### +# Build system documentation +###################################################################### + +# $(1) is the name of the doc
in Makefile.in # pick everything between tags | remove first line | remove last line # | remove extra (?) line | strip leading `#` from lines - $(Q)awk '//,/<\/help>/' $(S)/Makefile.in | sed '1d' | sed '$$d' | sed 's/^# \?//' +SHOW_DOCS = $(Q)awk '/$(1)/,/<\/$(1)>/' $(S)/Makefile.in | sed '1d' | sed '$$d' | sed 's/^\# \?//' + +help: + $(call SHOW_DOCS,help) + +hot-tips: + $(call SHOW_DOCS,hottips) + +nitty-gritty: + $(call SHOW_DOCS,nittygritty) diff --git a/mk/tests.mk b/mk/tests.mk index 7dec48b8372..049b41ab204 100644 --- a/mk/tests.mk +++ b/mk/tests.mk @@ -190,6 +190,10 @@ check-lite: cleantestlibs cleantmptestlogs \ check-stage2-rfail check-stage2-cfail check-stage2-rmake $(Q)$(CFG_PYTHON) $(S)src/etc/check-summary.py tmp/*.log +check-ref: cleantestlibs cleantmptestlogs check-stage2-rpass \ + check-stage2-rfail check-stage2-cfail check-stage2-rmake + $(Q)$(CFG_PYTHON) $(S)src/etc/check-summary.py tmp/*.log + .PHONY: cleantmptestlogs cleantestlibs cleantmptestlogs: