Add comments to cc/cc.go
Test: N/A
Change-Id: I2e221a40fdf9d6975891dedf0bf8a7db3e3943f1
diff --git a/cc/cc.go b/cc/cc.go
index 1a7ccf2..f922ea5 100644
--- a/cc/cc.go
+++ b/cc/cc.go
@@ -91,6 +91,14 @@
ctx.RegisterSingletonType("kythe_extract_all", kytheExtractAllFactory)
}
+// Deps is a struct containing module names of dependencies, separated by the kind of dependency.
+// Mutators should use `AddVariationDependencies` or its sibling methods to add actual dependency
+// edges to these modules.
+// This object is constructed in DepsMutator, by calling to various module delegates to set
+// relevant fields. For example, `module.compiler.compilerDeps()` may append type-specific
+// dependencies.
+// This is then consumed by the same DepsMutator, which will call `ctx.AddVariationDependencies()`
+// (or its sibling methods) to set real dependencies on the given modules.
type Deps struct {
SharedLibs, LateSharedLibs []string
StaticLibs, LateStaticLibs, WholeStaticLibs []string
@@ -103,6 +111,7 @@
// Used by DepsMutator to pass system_shared_libs information to check_elf_file.py.
SystemSharedLibs []string
+ // If true, statically link the unwinder into native libraries/binaries.
StaticUnwinderIfLegacy bool
ReexportSharedLibHeaders, ReexportStaticLibHeaders, ReexportHeaderLibHeaders []string
@@ -122,6 +131,11 @@
DynamicLinker string
}
+// PathDeps is a struct containing file paths to dependencies of a module.
+// It's constructed in depsToPath() by traversing the direct dependencies of the current module.
+// It's used to construct flags for various build statements (such as for compiling and linking).
+// It is then passed to module decorator functions responsible for registering build statements
+// (such as `module.compiler.compile()`).`
type PathDeps struct {
// Paths to .so files
SharedLibs, EarlySharedLibs, LateSharedLibs android.Paths
@@ -182,8 +196,12 @@
LdFlags []string // Flags that apply to linker command lines
}
+// Flags contains various types of command line flags (and settings) for use in building build
+// statements related to C++.
type Flags struct {
- Local LocalOrGlobalFlags
+ // Local flags (which individual modules are responsible for). These may override global flags.
+ Local LocalOrGlobalFlags
+ // Global flags (which build system or toolchain is responsible for).
Global LocalOrGlobalFlags
aidlFlags []string // Flags that apply to aidl source files
@@ -198,19 +216,23 @@
SystemIncludeFlags []string
Toolchain config.Toolchain
- Tidy bool
- GcovCoverage bool
- SAbiDump bool
+ Tidy bool // True if clang-tidy is enabled.
+ GcovCoverage bool // True if coverage files should be generated.
+ SAbiDump bool // True if header abi dumps should be generated.
EmitXrefs bool // If true, generate Ninja rules to generate emitXrefs input files for Kythe
+ // The instruction set required for clang ("arm" or "thumb").
RequiredInstructionSet string
- DynamicLinker string
+ // The target-device system path to the dynamic linker.
+ DynamicLinker string
CFlagsDeps android.Paths // Files depended on by compiler flags
LdFlagsDeps android.Paths // Files depended on by linker flags
+ // True if .s files should be processed with the c preprocessor.
AssemblerWithCpp bool
- GroupStaticLibs bool
+ // True if static libraries should be grouped (using `-Wl,--start-group` and `-Wl,--end-group`).
+ GroupStaticLibs bool
proto android.ProtoFlags
protoC bool // Whether to use C instead of C++
@@ -358,6 +380,10 @@
Double_loadable *bool
}
+// ModuleContextIntf is an interface (on a module context helper) consisting of functions related
+// to understanding details about the type of the current module.
+// For example, one might call these functions to determine whether the current module is a static
+// library and/or is installed in vendor directories.
type ModuleContextIntf interface {
static() bool
staticBinary() bool
@@ -412,6 +438,8 @@
ModuleContextIntf
}
+// feature represents additional (optional) steps to building cc-related modules, such as invocation
+// of clang-tidy.
type feature interface {
begin(ctx BaseModuleContext)
deps(ctx DepsContext, deps Deps) Deps
@@ -419,6 +447,9 @@
props() []interface{}
}
+// compiler is the interface for a compiler helper object. Different module decorators may implement
+// this helper differently. For example, compiling a `cc_library` may use a different build
+// statement than building a `toolchain_library`.
type compiler interface {
compilerInit(ctx BaseModuleContext)
compilerDeps(ctx DepsContext, deps Deps) Deps
@@ -430,6 +461,9 @@
compile(ctx ModuleContext, flags Flags, deps PathDeps) Objects
}
+// linker is the interface for a linker decorator object. Individual module types can provide
+// their own implementation for this decorator, and thus specify custom logic regarding build
+// statements pertaining to linking.
type linker interface {
linkerInit(ctx BaseModuleContext)
linkerDeps(ctx DepsContext, deps Deps) Deps
@@ -445,15 +479,19 @@
coverageOutputFilePath() android.OptionalPath
// Get the deps that have been explicitly specified in the properties.
- // Only updates the
linkerSpecifiedDeps(specifiedDeps specifiedDeps) specifiedDeps
}
+// specifiedDeps is a tuple struct representing dependencies of a linked binary owned by the linker.
type specifiedDeps struct {
- sharedLibs []string
- systemSharedLibs []string // Note nil and [] are semantically distinct.
+ sharedLibs []string
+ // Note nil and [] are semantically distinct. [] prevents linking against the defaults (usually
+ // libc, libm, etc.)
+ systemSharedLibs []string
}
+// installer is the interface for an installer helper object. This helper is responsible for
+// copying build outputs to the appropriate locations so that they may be installed on device.
type installer interface {
installerProps() []interface{}
install(ctx ModuleContext, path android.Path)
@@ -626,7 +664,18 @@
// Module contains the properties and members used by all C/C++ module types, and implements
// the blueprint.Module interface. It delegates to compiler, linker, and installer interfaces
-// to construct the output file. Behavior can be customized with a Customizer interface
+// to construct the output file. Behavior can be customized with a Customizer, or "decorator",
+// interface.
+//
+// To define a C/C++ related module, construct a new Module object and point its delegates to
+// type-specific structs. These delegates will be invoked to register module-specific build
+// statements which may be unique to the module type. For example, module.compiler.compile() should
+// be defined so as to register build statements which are responsible for compiling the module.
+//
+// Another example: to construct a cc_binary module, one can create a `cc.binaryDecorator` struct
+// which implements the `linker` and `installer` interfaces, and points the `linker` and `installer`
+// members of the cc.Module to this decorator. Thus, a cc_binary module has custom linker and
+// installer logic.
type Module struct {
android.ModuleBase
android.DefaultableModuleBase
@@ -643,18 +692,23 @@
// Allowable SdkMemberTypes of this module type.
sdkMemberTypes []android.SdkMemberType
- // delegates, initialize before calling Init
- features []feature
+ // decorator delegates, initialize before calling Init
+ // these may contain module-specific implementations, and effectively allow for custom
+ // type-specific logic. These members may reference different objects or the same object.
+ // Functions of these decorators will be invoked to initialize and register type-specific
+ // build statements.
compiler compiler
linker linker
installer installer
- stl *stl
- sanitize *sanitize
- coverage *coverage
- sabi *sabi
- vndkdep *vndkdep
- lto *lto
- pgo *pgo
+
+ features []feature
+ stl *stl
+ sanitize *sanitize
+ coverage *coverage
+ sabi *sabi
+ vndkdep *vndkdep
+ lto *lto
+ pgo *pgo
library libraryInterface
