1 # Copyright 2012 The Rust Project Developers. See the COPYRIGHT
2 # file at the top-level directory of this distribution and at
3 # http://rust-lang.org/COPYRIGHT.
5 # Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 # http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 # <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 # option. This file may not be copied, modified, or distributed
9 # except according to those terms.
13 # Greetings, adventurer! The Rust Build System is at your service.
15 # Whether you want a genuine copy of `rustc`, access to the latest and
16 # most authoritative Rust documentation, or even to investigate the
17 # most intimate workings of the compiler itself, you've come to the
18 # right place. Let's see what's on the menu.
20 # First, start with one of these build targets:
22 # * all - The default. Build a complete, bootstrapped compiler.
23 # `rustc` will be in `${target-triple}/stage2/bin/`. Run it
24 # directly from the build directory if you like. This also
25 # comes with docs in `doc/`.
27 # * check - Run the complete test suite
29 # * clean - Clean the build repository. It is advised to run this
30 # command if you want to build Rust again, after an update
31 # of the git repository.
33 # * install - Install Rust. Note that installation is not necessary
34 # to use the compiler.
36 # * uninstall - Uninstall the binaries
38 # For tips on working with The Rust Build System, just:
50 # # The Rust Build System Tip Line
52 # There are a bazillion different targets you might want to build. Here
55 # * docs - Build gobs of HTML documentation and put it into `doc/`
56 # * check-$(crate) - Test a crate, e.g. `check-std`
57 # * check-ref - Run the language reference tests
58 # * check-docs - Test the documentation examples
59 # * check-stage$(stage)-$(crate) - Test a crate in a specific stage
60 # * check-stage$(stage)-{rpass,rfail,cfail,rmake,...} - Run tests in src/test/
61 # * check-stage1-T-$(target)-H-$(host) - Run cross-compiled-tests
62 # * tidy - Basic style check, show highest rustc error code and
63 # the status of language and lib features
64 # * rustc-stage$(stage) - Only build up to a specific stage
65 # * $host/stage1/bin/rustc - Only build stage1 rustc, not libstd. For further
66 # information see "Rust recipes for build system success" below.
68 # Then mix in some of these environment variables to harness the
69 # ultimate power of The Rust Build System.
71 # * `VERBOSE=1` - Print all commands. Use this to see what's going on.
72 # * `RUSTFLAGS=...` - Add compiler flags to all `rustc` invocations
73 # * `JEMALLOC_FLAGS=...` - Pass flags to jemalloc's configure script
75 # * `TESTNAME=...` - Specify the name of tests to run
76 # * `CHECK_IGNORED=1` - Run normally-ignored tests
77 # * `PLEASE_BENCH=1` - Run crate benchmarks (enable `--bench` flag)
79 # * `CFG_ENABLE_VALGRIND=1` - Run tests under valgrind
80 # * `VALGRIND_COMPILE=1` - Run the compiler itself under valgrind
81 # (requires `CFG_ENABLE_VALGRIND`)
83 # * `NO_REBUILD=1` - Don't rebootstrap when testing std
84 # (and possibly other crates)
85 # * `NO_MKFILE_DEPS=1` - Don't rebuild for modified .mk files
87 # * `SAVE_TEMPS=1` - Use `--save-temps` flag on all `rustc` invocations
88 # * `ASM_COMMENTS=1` - Use `-Z asm-comments`
89 # * `TIME_PASSES=1` - Use `-Z time-passes`
90 # * `TIME_LLVM_PASSES=1` - Use `-Z time-llvm-passes`
91 # * `TRACE=1` - Use `-Z trace`
93 # # Rust recipes for build system success
95 # // Modifying libstd? Use this command to run unit tests just on your change
96 # make check-stage1-std NO_REBUILD=1 NO_BENCH=1
98 # // Modifying just rustc?
99 # // Compile rustc+libstd once
101 # // From now on use this command to rebuild just rustc and reuse the previously built libstd
102 # // $host is a target triple, eg. x86_64-unknown-linux-gnu
103 # // The resulting binary is located at $host/stage1/bin/rustc.
104 # // If there are any issues with libstd recompile it with the command above.
105 # make $host/stage1/bin/rustc
107 # // Added a run-pass test? Use this to test running your test
108 # make check-stage1-rpass TESTNAME=my-shiny-new-test
110 # // Having trouble figuring out which test is failing? Turn off parallel tests
111 # make check-stage1-std RUST_TEST_THREADS=1
113 # // To make debug!() and other logging calls visible, reconfigure:
114 # ./configure --enable-debug-assertions
117 # If you really feel like getting your hands dirty, then:
119 # run `make nitty-gritty`
121 # # Make command examples
123 # ## Docs linked commands
125 # * make check-stage1-rustdocck: Builds rustdoc. It has the advantage to compile
126 # quite quickly since we're only using stage1
128 # * make doc/error-index.md: Gets all doc blocks from doc comments and error
129 # explanations to put them in a markdown file. You
130 # can then test them by running
131 # "rustdoc --test error-index.md".
133 # And of course, the wonderfully useful 'make tidy'! Always run it before opening a pull request to rust!
139 # # The Rust Build System
141 # Gosh I wish there was something useful here (TODO).
143 # # An (old) explanation of how the build is structured:
145 # *Note: Hey, like, this is probably inaccurate, and is definitely
146 # an outdated and insufficient explanation of the remarkable
147 # Rust Build System.*
149 # There are multiple build stages (0-3) needed to verify that the
150 # compiler is properly self-hosting. Each stage is divided between
151 # 'host' artifacts and 'target' artifacts, where the stageN host
152 # compiler builds artifacts for 1 or more stageN target architectures.
153 # Once the stageN target compiler has been built for the host
154 # architecture it is promoted (copied) to a stageN+1 host artifact.
156 # The stage3 host compiler is a compiler that successfully builds
157 # itself and should (in theory) be bitwise identical to the stage2
158 # host compiler. The process is bootstrapped using a stage0 host
159 # compiler downloaded from a previous snapshot.
161 # At no time should stageN artifacts be interacting with artifacts
162 # from other stages. For consistency, we use the 'promotion' logic
163 # for all artifacts, even those that don't make sense on non-host
166 # The directory layout for a stage is intended to match the layout
167 # of the installed compiler, and looks like the following:
169 # stageN - this is the system root, corresponding to, e.g. /usr
170 # bin - binaries compiled for the host
171 # lib - libraries used by the host compiler
172 # rustlib - rustc's own place to organize libraries
173 # $(target) - target-specific artifacts
174 # bin - binaries for target architectures
175 # lib - libraries for target architectures
177 # A note about host libraries:
179 # The only libraries that get promoted to stageN/lib are those needed
180 # by rustc. In general, rust programs, even those compiled for the
181 # host architecture will use libraries from the target
182 # directories. This gives rust some freedom to experiment with how
183 # libraries are managed and versioned without polluting the common
184 # areas of the filesystem.
186 # General rust binaries may still live in the host bin directory; they
187 # will just link against the libraries in the target lib directory.
189 # Admittedly this is a little convoluted.
191 # If you find yourself working on the make infrastructure itself, and trying to
192 # find the value of a given variable after expansion, you can use:
194 # make print-VARIABLE_NAME
201 ######################################################################
203 ######################################################################
205 # Issue #9531: If you change the order of any of the following (or add
206 # new definitions), make sure definitions always precede their uses,
207 # especially for the dependency lists of recipes.
209 # First, load the variables exported by the configure script
212 # Just a few macros used everywhere
213 include $(CFG_SRC_DIR)mk/util.mk
214 # Reconfiguring when the makefiles or submodules change
215 include $(CFG_SRC_DIR)mk/reconfig.mk
216 # All crates and their dependencies
217 include $(CFG_SRC_DIR)mk/crates.mk
218 # Various bits of setup, common macros, and top-level rules
219 include $(CFG_SRC_DIR)mk/main.mk
220 # C and assembly components that are not LLVM
221 include $(CFG_SRC_DIR)mk/rt.mk
222 # Rules for crates in the target directories
223 include $(CFG_SRC_DIR)mk/target.mk
224 # Rules for crates in the host directories
225 include $(CFG_SRC_DIR)mk/host.mk
226 # Special rules for bootstrapping stage0
227 include $(CFG_SRC_DIR)mk/stage0.mk
228 # Rust-specific LLVM extensions
229 include $(CFG_SRC_DIR)mk/rustllvm.mk
231 include $(CFG_SRC_DIR)mk/docs.mk
233 include $(CFG_SRC_DIR)mk/llvm.mk
234 # Rules for installing debugger scripts
235 include $(CFG_SRC_DIR)mk/debuggers.mk
237 ######################################################################
238 # Secondary makefiles, conditionalized for speed
239 ######################################################################
242 ifneq ($(strip $(findstring check,$(MAKECMDGOALS)) \
243 $(findstring test,$(MAKECMDGOALS)) \
244 $(findstring tidy,$(MAKECMDGOALS))),)
245 CFG_INFO := $(info cfg: including test rules)
246 include $(CFG_SRC_DIR)mk/tests.mk
247 include $(CFG_SRC_DIR)mk/grammar.mk
250 # Copy all the distributables to another directory for binary install
251 ifneq ($(strip $(findstring prepare,$(MAKECMDGOALS)) \
252 $(findstring dist,$(MAKECMDGOALS)) \
253 $(findstring install,$(MAKECMDGOALS))),)
254 CFG_INFO := $(info cfg: including prepare rules)
255 include $(CFG_SRC_DIR)mk/prepare.mk
258 # Source and binary distribution artifacts
259 ifneq ($(strip $(findstring dist,$(MAKECMDGOALS)) \
260 $(findstring install,$(MAKECMDGOALS)) \
261 $(findstring clean,$(MAKECMDGOALS))),)
262 CFG_INFO := $(info cfg: including dist rules)
263 include $(CFG_SRC_DIR)mk/dist.mk
266 # (Unix) Installation from the build directory
267 ifneq ($(findstring install,$(MAKECMDGOALS)),)
268 CFG_INFO := $(info cfg: including install rules)
269 include $(CFG_SRC_DIR)mk/install.mk
273 ifneq ($(findstring clean,$(MAKECMDGOALS)),)
274 CFG_INFO := $(info cfg: including clean rules)
275 include $(CFG_SRC_DIR)mk/clean.mk
279 ifneq ($(strip $(findstring TAGS.emacs,$(MAKECMDGOALS)) \
280 $(findstring TAGS.vi,$(MAKECMDGOALS)) \
281 $(findstring TAGS.rustc.emacs,$(MAKECMDGOALS)) \
282 $(findstring TAGS.rustc.vi,$(MAKECMDGOALS))),)
283 CFG_INFO := $(info cfg: including ctags rules)
284 include $(CFG_SRC_DIR)mk/ctags.mk
289 @echo "======================================================"
290 @echo "== If you need help, run 'make help' or 'make tips' =="
291 @echo "======================================================"