Invoke soong_docs from the bootstrap Ninja file. (c6012f36) · Commits · e / os / android_build_soong

README.md

+4 −2

Original line number	Diff line number	Diff line
		@@ -33,8 +33,10 @@ cc_binary {
		Every module must have a `name` property, and the value must be unique across
		all Android.bp files.

		For a list of valid module types and their properties see
		[$OUT_DIR/soong/docs/soong_build.html](https://ci.android.com/builds/latest/branches/aosp-build-tools/targets/linux/view/soong_build.html).
		The list of valid module types and their properties can be generated by calling
		`m soong_docs`. It will be written to `$OUT_DIR/soong/docs/soong_build.html`.
		This list for the current version of Soong can be found [here](https://ci.android.com/builds/latest/branches/aosp-build-tools/targets/linux/view/soong_build.html).


		### File lists

android/Android.bp

+0 −1

Original line number	Diff line number	Diff line
		@@ -80,7 +80,6 @@ bootstrap_go_package {
		"util.go",
		"variable.go",
		"visibility.go",
		"writedocs.go",
		],
		testSrcs: [
		"android_test.go",

android/writedocs.go

deleted100644 → 0

+0 −89

Original line number	Diff line number	Diff line
		// Copyright 2015 Google Inc. All rights reserved.
		//
		// Licensed under the Apache License, Version 2.0 (the "License");
		// you may not use this file except in compliance with the License.
		// You may obtain a copy of the License at
		//
		// http://www.apache.org/licenses/LICENSE-2.0
		//
		// Unless required by applicable law or agreed to in writing, software
		// distributed under the License is distributed on an "AS IS" BASIS,
		// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
		// See the License for the specific language governing permissions and
		// limitations under the License.

		package android

		import (
		"fmt"
		"os"
		"path/filepath"
		"strings"

		"github.com/google/blueprint"
		)

		func init() {
		RegisterSingletonType("writedocs", DocsSingleton)
		}

		func DocsSingleton() Singleton {
		return &docsSingleton{}
		}

		type docsSingleton struct{}

		func primaryBuilderPath(ctx SingletonContext) Path {
		soongOutDir := absolutePath(ctx.Config().SoongOutDir())
		binary := absolutePath(os.Args[0])
		primaryBuilder, err := filepath.Rel(soongOutDir, binary)
		if err != nil {
		ctx.Errorf("path to primary builder %q is not in build dir %q (%q)",
		os.Args[0], ctx.Config().SoongOutDir(), err)
		}

		return PathForOutput(ctx, primaryBuilder)
		}

		func (c *docsSingleton) GenerateBuildActions(ctx SingletonContext) {
		var deps Paths
		deps = append(deps, pathForBuildToolDep(ctx, ctx.Config().moduleListFile))
		deps = append(deps, pathForBuildToolDep(ctx, ctx.Config().ProductVariablesFileName))

		// The dexpreopt configuration may not exist, but if it does, it's a dependency
		// of soong_build.
		dexpreoptConfigPath := ctx.Config().DexpreoptGlobalConfigPath(ctx)
		if dexpreoptConfigPath.Valid() {
		deps = append(deps, dexpreoptConfigPath.Path())
		}

		// Generate build system docs for the primary builder. Generating docs reads the source
		// files used to build the primary builder, but that dependency will be picked up through
		// the dependency on the primary builder itself. There are no dependencies on the
		// Blueprints files, as any relevant changes to the Blueprints files would have caused
		// a rebuild of the primary builder.
		docsFile := PathForOutput(ctx, "docs", "soong_build.html")
		primaryBuilder := primaryBuilderPath(ctx)
		soongDocs := ctx.Rule(pctx, "soongDocs",
		blueprint.RuleParams{
		Command: fmt.Sprintf("rm -f ${outDir}/* && %s --soong_docs %s %s",
		primaryBuilder.String(),
		docsFile.String(),
		"\""+strings.Join(os.Args[1:], "\" \"")+"\""),
		CommandDeps: []string{primaryBuilder.String()},
		Description: fmt.Sprintf("%s docs $out", primaryBuilder.Base()),
		},
		"outDir")

		ctx.Build(pctx, BuildParams{
		Rule: soongDocs,
		Output: docsFile,
		Inputs: deps,
		Args: map[string]string{
		"outDir": PathForOutput(ctx, "docs").String(),
		},
		})

		// Add a phony target for building the documentation
		ctx.Phony("soong_docs", docsFile)
		}

cmd/soong_build/main.go

+16 −24

Original line number	Diff line number	Diff line
		@@ -163,16 +163,6 @@ func runQueryView(queryviewDir, queryviewMarker string, configuration android.Co
		touch(shared.JoinPath(topDir, queryviewMarker))
		}

		func runSoongDocs(configuration android.Config) {
		ctx := newContext(configuration)
		soongDocsArgs := cmdlineArgs
		bootstrap.RunBlueprint(soongDocsArgs, bootstrap.StopBeforePrepareBuildActions, ctx.Context, configuration)
		if err := writeDocs(ctx, configuration, docFile); err != nil {
		fmt.Fprintf(os.Stderr, "%s", err)
		os.Exit(1)
		}
		}

		func writeMetrics(configuration android.Config) {
		metricsFile := filepath.Join(configuration.SoongOutDir(), "soong_build_metrics.pb")
		err := android.WriteMetrics(configuration, metricsFile)
		@@ -217,20 +207,22 @@ func writeDepFile(outputFile string, ninjaDeps []string) {
		// or the actual Soong build for the build.ninja file. Returns the top level
		// output file of the specific activity.
		func doChosenActivity(configuration android.Config, extraNinjaDeps []string) string {
		bazelConversionRequested := bp2buildMarker != ""
		mixedModeBuild := configuration.BazelContext.BazelEnabled()
		generateBazelWorkspace := bp2buildMarker != ""
		generateQueryView := bazelQueryViewDir != ""
		generateModuleGraphFile := moduleGraphFile != ""
		generateDocFile := docFile != ""

		blueprintArgs := cmdlineArgs

		var stopBefore bootstrap.StopBefore
		if !generateQueryView && moduleGraphFile == "" {
		if !generateModuleGraphFile && !generateQueryView && !generateDocFile {
		stopBefore = bootstrap.DoEverything
		} else {
		stopBefore = bootstrap.StopBeforePrepareBuildActions
		}

		if bazelConversionRequested {
		if generateBazelWorkspace {
		// Run the alternate pipeline of bp2build mutators and singleton to convert
		// Blueprint to BUILD files before everything else.
		runBp2Build(configuration, extraNinjaDeps)
		@@ -253,10 +245,20 @@ func doChosenActivity(configuration android.Config, extraNinjaDeps []string) str
		runQueryView(bazelQueryViewDir, queryviewMarkerFile, configuration, ctx)
		writeDepFile(queryviewMarkerFile, ninjaDeps)
		return queryviewMarkerFile
		} else if moduleGraphFile != "" {
		} else if generateModuleGraphFile {
		writeJsonModuleGraph(ctx, moduleGraphFile)
		writeDepFile(moduleGraphFile, ninjaDeps)
		return moduleGraphFile
		} else if generateDocFile {
		// TODO: we could make writeDocs() return the list of documentation files
		// written and add them to the .d file. Then soong_docs would be re-run
		// whenever one is deleted.
		if err := writeDocs(ctx, shared.JoinPath(topDir, docFile)); err != nil {
		fmt.Fprintf(os.Stderr, "error building Soong documentation: %s\n", err)
		os.Exit(1)
		}
		writeDepFile(docFile, ninjaDeps)
		return docFile
		} else {
		// The actual output (build.ninja) was written in the RunBlueprint() call
		// above
		@@ -320,16 +322,6 @@ func main() {
		extraNinjaDeps = append(extraNinjaDeps, filepath.Join(configuration.SoongOutDir(), "always_rerun_for_delve"))
		}

		if docFile != "" {
		// We don't write an used variables file when generating documentation
		// because that is done from within the actual builds as a Ninja action and
		// thus it would overwrite the actual used variables file so this is
		// special-cased.
		// TODO: Fix this by not passing --used_env to the soong_docs invocation
		runSoongDocs(configuration)
		return
		}

		finalOutputFile := doChosenActivity(configuration, extraNinjaDeps)
		writeUsedEnvironmentFile(configuration, finalOutputFile)
		}

cmd/soong_build/writedocs.go

+6 −5

Original line number	Diff line number	Diff line
		@@ -15,13 +15,14 @@
		package main

		import (
		"android/soong/android"
		"bytes"
		"html/template"
		"io/ioutil"
		"path/filepath"
		"sort"

		"android/soong/android"

		"github.com/google/blueprint/bootstrap"
		"github.com/google/blueprint/bootstrap/bpdoc"
		)
		@@ -95,13 +96,13 @@ func moduleTypeDocsToTemplates(moduleTypeList []*bpdoc.ModuleType) []moduleTypeT
		return result
		}

		func getPackages(ctx android.Context, config interface{}) ([]bpdoc.Package, error) {
		func getPackages(ctx android.Context) ([]bpdoc.Package, error) {
		moduleTypeFactories := android.ModuleTypeFactoriesForDocs()
		return bootstrap.ModuleTypeDocs(ctx.Context, config, moduleTypeFactories)
		return bootstrap.ModuleTypeDocs(ctx.Context, moduleTypeFactories)
		}

		func writeDocs(ctx *android.Context, config interface{}, filename string) error {
		packages, err := getPackages(ctx, config)
		func writeDocs(ctx *android.Context, filename string) error {
		packages, err := getPackages(ctx)
		if err != nil {
		return err
		}