# Copyright 2012 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.

# <help>
#
# # The Rust Build System
#
# Start with these these build targets:
#
# * 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
#
# Then mix in some of these environment variables to harness the
# ultimate power of 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)
# * `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].
#
# [1]: https://github.com/mozilla/rust/wiki/Note-build-system
# [2]: https://github.com/mozilla/rust/wiki/Note-testsuite
#
# </help>
#
# # 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.*
#
# There are multiple build stages (0-3) needed to verify that the
# compiler is properly self-hosting. Each stage is divided between
# 'host' artifacts and 'target' artifacts, where the stageN host
# compiler builds artifacts for 1 or more stageN target architectures.
# Once the stageN target compiler has been built for the host
# architecture it is promoted (copied) to a stageN+1 host artifact.
#
# The stage3 host compiler is a compiler that successfully builds
# itself and should (in theory) be bitwise identical to the stage2
# host compiler. The process is bootstrapped using a stage0 host
# compiler downloaded from a previous snapshot.
#
# At no time should stageN artifacts be interacting with artifacts
# from other stages. For consistency, we use the 'promotion' logic
# for all artifacts, even those that don't make sense on non-host
# architectures.
#
# The directory layout for a stage is intended to match the layout
# of the installed compiler, and looks like the following:
#
# stageN - this is the system root, corresponding to, e.g. /usr
#   bin - binaries compiled for the host
#   lib - libraries used by the host compiler
#     rustlib - rustc's own place to organize libraries
#       $(target) - target-specific artifacts
#         bin - binaries for target architectures
#         lib - libraries for target architectures
#
# A note about host libraries:
#
# The only libraries that get promoted to stageN/lib are those needed
# by rustc. In general, rust programs, even those compiled for the
# host architecture will use libraries from the target
# directories. This gives rust some freedom to experiment with how
# libraries are managed and versioned without polluting the common
# areas of the filesystem.
#
# General rust binaries may stil live in the host bin directory; they
# will just link against the libraries in the target lib directory.
#
# Admittedly this is a little convoluted.

######################################################################
# Primary rules
######################################################################

# Issue #9531: If you change the order of any of the following (or add
# new definitions), make sure definitions always precede their uses,
# especially for the dependency lists of recipes.

# First, load the variables exported by the configure script
include config.mk

# Just a few macros used everywhere
include $(CFG_SRC_DIR)mk/util.mk
# All crates and their dependencies
include $(CFG_SRC_DIR)mk/crates.mk
# Reconfiguring when the makefiles or submodules change
include $(CFG_SRC_DIR)mk/reconfig.mk
# Various bits of setup, common macros, and top-level rules
include $(CFG_SRC_DIR)mk/main.mk
# C and assembly components that are not LLVM
include $(CFG_SRC_DIR)mk/rt.mk
# Rules for crates in the target directories
include $(CFG_SRC_DIR)mk/target.mk
# Rules for crates in the host directories
include $(CFG_SRC_DIR)mk/host.mk
# Special rules for bootstrapping stage0
include $(CFG_SRC_DIR)mk/stage0.mk
# Rust-specific LLVM extensions
include $(CFG_SRC_DIR)mk/rustllvm.mk
# Documentation
include $(CFG_SRC_DIR)mk/docs.mk
# LLVM
include $(CFG_SRC_DIR)mk/llvm.mk

######################################################################
# Secondary makefiles, conditionalized for speed
######################################################################

# Source and binary distribution artifacts
ifneq ($(strip $(findstring dist,$(MAKECMDGOALS))   \
               $(findstring check,$(MAKECMDGOALS))  \
               $(findstring test,$(MAKECMDGOALS))   \
               $(findstring tidy,$(MAKECMDGOALS))   \
               $(findstring clean,$(MAKECMDGOALS))),)
  CFG_INFO := $(info cfg: including dist rules)
  include $(CFG_SRC_DIR)mk/dist.mk
endif

# Binary snapshots
ifneq ($(strip $(findstring snap,$(MAKECMDGOALS))   \
               $(findstring clean,$(MAKECMDGOALS))),)
  CFG_INFO := $(info cfg: including snap rules)
  include $(CFG_SRC_DIR)mk/snap.mk
endif

# The test suite
ifneq ($(strip $(findstring check,$(MAKECMDGOALS)) \
               $(findstring test,$(MAKECMDGOALS))  \
               $(findstring perf,$(MAKECMDGOALS))  \
               $(findstring tidy,$(MAKECMDGOALS))),)
  CFG_INFO := $(info cfg: including test rules)
  include $(CFG_SRC_DIR)mk/tests.mk
endif

# Performance and benchmarking
ifneq ($(findstring perf,$(MAKECMDGOALS)),)
  CFG_INFO := $(info cfg: including perf rules)
  include $(CFG_SRC_DIR)mk/perf.mk
endif

# Cleaning
ifneq ($(findstring clean,$(MAKECMDGOALS)),)
  CFG_INFO := $(info cfg: including clean rules)
  include $(CFG_SRC_DIR)mk/clean.mk
endif

# Installation from the build directory
ifneq ($(findstring install,$(MAKECMDGOALS)),)
  CFG_INFO := $(info cfg: including install rules)
  include $(CFG_SRC_DIR)mk/install.mk
endif

# CTAGS building
ifneq ($(strip $(findstring TAGS.emacs,$(MAKECMDGOALS)) \
               $(findstring TAGS.vi,$(MAKECMDGOALS))),)
  CFG_INFO := $(info cfg: including ctags rules)
  include $(CFG_SRC_DIR)mk/ctags.mk
endif

# Find all of the .d files and include them to add information about
# header file dependencies.
ALL_DEP_FILES := $(ALL_OBJ_FILES:%.o=%.d)
-include $(ALL_DEP_FILES)