$ cat Makefile
### DO NOT EDIT THIS FILE ###
include build/make/core/main.mk
### DO NOT EDIT THIS FILE ###

ifndef KATI
$(warning Calling make directly is no longer supported.)
$(warning Either use 'envsetup.sh; m' or 'build/soong/soong_ui.bash --make-mode')
$(error done)
endif

$(info [1/1] initializing build system ...)
# 以下省略 ......

$ make
build/make/core/main.mk:2: Calling make directly is no longer supported.
build/make/core/main.mk:3: Either use 'envsetup.sh; m' or 'build/soong/soong_ui.bash --make-mode'
build/make/core/main.mk:4: *** done.  Stop.

$ source build/envsetup.sh
$ lunch [<product>-<variant>]
$ m [<options>] [<targets>] [<variable>=<value>...]

function m()
(
    _trigger_build "all-modules" "$@"
)

function mm()
(
    _trigger_build "modules-in-a-dir-no-deps" "$@"
)

function mmm()
(
    _trigger_build "modules-in-dirs-no-deps" "$@"
)

function mma()
(
    _trigger_build "modules-in-a-dir" "$@"
)

function mmma()
(
    _trigger_build "modules-in-dirs" "$@"
)

function _trigger_build()
(
    local -r bc="$1"; shift
    if T="$(gettop)"; then
      _wrap_build "$T/build/soong/soong_ui.bash" --build-mode --${bc} --dir="$(pwd)" "$@"
    else
      echo "Couldn't locate the top of the tree. Try setting TOP."
    fi
)

$ cat build/soong/soong_ui.bash
......
source ${TOP}/build/soong/scripts/microfactory.bash

soong_build_go soong_ui android/soong/cmd/soong_ui

cd ${TOP}
exec "$(getoutdir)/soong_ui" "$@"

func main() {
  	// 省略 ......

	/*
	 * soong_ui 的命令格式如下：
	 * soong_ui <command> [<arg 1> <arg 2> ... <arg n>]
	 * 其中 command 指定了 soong_ui 执行的具体动作类型
	 * getCommand 的作用是检查输入的 command 选项
	 * soong_ui 目前支持四个 command：
	 * - `--make-mode`
	 * - `--dumpvar-mode`
	 * - `--dumpvars-mode`
	 * - `--build-mode`
	 */
	c, args, err := getCommand(os.Args)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Error parsing `soong` args: %s.\n", err)
		os.Exit(1)
	}

	// 省略 ......

	/*
	 * 定义一个 build.Context 的对象，
	 * build.Context 定义参考 `soong\ui\build\context.go`
	 * 我理解 Context 对象是一个容器，包含了在 build 过程中可能会涉及的 log，
	 * trace 等等辅助对象, 会传给其他函数，负责提供一些辅助功能，譬如
	 * 我们可以条用 Context 对象在执行过程中打印日志
	 */
	buildCtx := build.Context{ContextImpl: &build.ContextImpl{
		Context: ctx,
		Logger:  log,
		Metrics: met,
		Tracer:  trace,
		Writer:  output,
		Status:  stat,
	}}

	/*
	 * 定义了一个 build.Config 类型的 config 对象
	 * 这个 Config 对象的类定义参考 `soong\ui\build\config.go` 中的 configImpl,
	 * 我们在输入命令行时会带入各种选项，`build.NewConfig()` 这个函数的作用就是
	 * 解析这些参数并把它们记录在 config 对象中，这些参数会影响后面 make/m 的行为。
	 * 这个 run 函数根据 command 的不同被重载为不同的操作
	 * - "--make-mode": build.NewConfig(ctx, args...)
	 * - "--dumpvar-mode": dumpVarConfig
	 * - "--dumpvars-mode": dumpVarConfig
	 * - "--build-mode": buildActionConfig
	 * 这些操作最终都会走到 `build.NewConfig()` 这个函数，这个函数定义在 `build/soong/ui/build/config.go`
	 * 可以注意看一下这个文件中的 `parseArgs()` 文件，里面列出了会影响后面 build 的参数
	 * - - showcommands: 显示详细（verbose）的 build log
	 * - --skip-ninja: 不执行 ninja
	 * - --skip-make: 不执行和 make 有关的所有操作，包括 kati
	 * - --skip-kati: 不执行 kati
	 * - --soong-only: 只运行 soong
	 * - --skip-soong-tests：跳过 soong 的 test
	 * - -j:
	 * - -k:
	 * - dist:
	 * - checkbuild: 是否要在 build 后执行额外的 check 操作
	 */
	config := c.config(buildCtx, args...)

	if err := loadEnvConfig(); err != nil {
		fmt.Fprintf(os.Stderr, "failed to parse env config files: %v", err)
		os.Exit(1)
	}

	/*
	 * 下面的步骤主要是在准备输出目录以及各种 log 等
	 */
	build.SetupOutDir(buildCtx, config)

	if config.UseBazel() && config.Dist() {
		defer populateExternalDistDir(buildCtx, config)
	}

	// Set up files to be outputted in the log directory.
	logsDir := config.LogsDir()

	// 省略 ......

	/*
	 * build.FindSources 会创建 `out/.module_paths` 这个目录并在这个目录下产生一些
	 * 特殊的文件记录。譬如我们比较关心的 `out/.module_paths/Android.bp.list` 这个
	 * 文件，打开这个文件我们会看到里面记录了 AOSP 项目中所有 Android.bp 文件的路径
	 * 届时后面的操作会根据这里记录的项目对这些 Android.bp 文件进行分析，进而产生
	 * 最终的 build.ninja 文件。
	 */
	// Create a source finder.
	f := build.NewSourceFinder(buildCtx, config)
	defer f.Shutdown()
	build.FindSources(buildCtx, config, f)

	/*
	 * 这个 run 函数根据 command 的不同被重载为不同的操作
	 * - "--make-mode": runMake
	 * - "--dumpvar-mode": dumpVar
	 * - "--dumpvars-mode": dumpVars
	 * - "--build-mode": runMake
	 */
	c.run(buildCtx, config, args, logsDir)
}

func runMake(ctx build.Context, config build.Config, _ []string, logsDir string) {
	......

	build.Build(ctx, config)
}

// Build the tree. The 'what' argument can be used to chose which components of
// the build to run, via checking various bitmasks.
func Build(ctx Context, config Config) {
	// 省略 ......
	/*
	 * 输入 `m help` 会打印帮助，帮助的内容实际上是通过执行 `build/make/help.sh` 这
	 * 个脚本产生的
	 */
	if inList("help", config.Arguments()) {
		help(ctx, config)
		return
	}

	// 省略 ......

	/*
	 * 输入 `m clean` 或者 `m clobber` 会清除构建结果，等同于 `rm -rf out/`
	 */
	if inList("clean", config.Arguments()) || inList("clobber", config.Arguments()) {
		clean(ctx, config)
		return
	}

	/* 一些 build 前的准备工作和检查 */
	// 省略 ......

	/* 判断是否要启动一些操作 */
	what := RunAll
	if config.UseBazel() {
		what = RunAllWithBazel /* Bazel 取决于环境变量 `USE_BAZEL` 是否定义 */
	}
	if config.Checkbuild() { /* 譬如执行 m checkbuild */
		what |= RunBuildTests
	}
	if config.SkipConfig() { /* 譬如执行 m --skip-make */
		ctx.Verboseln("Skipping Config as requested")
		what = what &^ RunProductConfig
	}
	if config.SkipKati() { /* 譬如执行 m --skip-make 或者 --skip-kati --soong-only */
		ctx.Verboseln("Skipping Kati as requested")
		what = what &^ RunKati
	}
	if config.SkipKatiNinja() { /* 譬如执行 m --soong-only */
		ctx.Verboseln("Skipping use of Kati ninja as requested")
		what = what &^ RunKatiNinja
	}
	if config.SkipNinja() { /* 譬如执行 m --skip-ninja */
		ctx.Verboseln("Skipping Ninja as requested")
		what = what &^ RunNinja
	}

	if config.StartGoma() {
		startGoma(ctx, config)
	}

	if config.StartRBE() {
		startRBE(ctx, config)
	}

	/*
	 * `runMakeProductConfig()` 函数的的内部调用 `dumpMakeVars()`, 这个函数会通过 ckati
	 * 调用 `build/make/core/config.mk`， 其作用也是在执行执行重要的 runSoong 之前将
	 * makefile 中定义的变量转化为环境变量，进而传递给 soong
	 * 此外 `runMakeProductConfig()` 还会在 `out/soong/` 目录下生成一些重要的记录环
	 * 境变量的文件，譬如 `out/soong/soong.variables`，这个文件是在 soong_ui 的
	 * build 过程中在 bootstrap 之前生成，生成后我们在屏幕上才会看到 banner 显示各个
	 * 重要环境变量的值。内部含有当前项目的所有特定配置信息。
	 */
	if what&RunProductConfig != 0 {
		runMakeProductConfig(ctx, config)
	}

	// Everything below here depends on product config.

	if inList("installclean", config.Arguments()) ||
		inList("install-clean", config.Arguments()) {
		installClean(ctx, config)
		ctx.Println("Deleted images and staging directories.")
		return
	}

	if inList("dataclean", config.Arguments()) ||
		inList("data-clean", config.Arguments()) {
		dataClean(ctx, config)
		ctx.Println("Deleted data files.")
		return
	}

	if what&RunSoong != 0 {
		runSoong(ctx, config)

		if config.bazelBuildMode() == generateBuildFiles {
			// Return early, if we're using Soong as solely the generator of BUILD files.
			return
		}
	}

	if what&RunKati != 0 {
		genKatiSuffix(ctx, config)
		runKatiCleanSpec(ctx, config)
		runKatiBuild(ctx, config)
		runKatiPackage(ctx, config)

		ioutil.WriteFile(config.LastKatiSuffixFile(), []byte(config.KatiSuffix()), 0666) // a+rw
	} else if what&RunKatiNinja != 0 {
		// Load last Kati Suffix if it exists
		if katiSuffix, err := ioutil.ReadFile(config.LastKatiSuffixFile()); err == nil {
			ctx.Verboseln("Loaded previous kati config:", string(katiSuffix))
			config.SetKatiSuffix(string(katiSuffix))
		}
	}

	// Write combined ninja file
	createCombinedBuildNinjaFile(ctx, config)

	distGzipFile(ctx, config, config.CombinedNinjaFile())

	if what&RunBuildTests != 0 {
		testForDanglingRules(ctx, config)
	}

	if what&RunNinja != 0 {
		if what&RunKati != 0 {
			installCleanIfNecessary(ctx, config)
		}

		runNinjaForBuild(ctx, config)
	}

	// Currently, using Bazel requires Kati and Soong to run first, so check whether to run Bazel last.
	if what&RunBazel != 0 {
		runBazel(ctx, config)
	}
}

func runSoong(ctx Context, config Config) {
	// 省略 ......
   	ctx.BeginTrace(metrics.RunSoong, "blueprint bootstrap")
	// 省略 ......
   	ctx.BeginTrace(metrics.RunSoong, "minibp")
	// 省略 ......
	ctx.BeginTrace(metrics.RunSoong, "bpglob")
	// 省略 ......
	ninja("minibootstrap", ".minibootstrap/build.ninja")
	// 省略 ......
	ninja("bootstrap", ".bootstrap/build.ninja")
}

$ ls ./out/soong/.bootstrap/bin
gotestmain  gotestrunner  loadplugins  soong_build  soong_env

[117/117] out/soong/.bootstrap/bin/soong_build -t -l out/.module_paths/Android.bp.list -b out/soong -n out -d out/soong/build.ninja.d -globFile out/soong/.bootstrap/build-globs.ninja -o out/soong/build.ninja Android.bp