Improve comments in cc/library.go and cc/linkable.go.
Test: N/A
Change-Id: I10cca7942bf86be8c933fd924f4bb7bdaff0cef7
diff --git a/cc/cc.go b/cc/cc.go
index 6deb1b4..ce69668 100644
--- a/cc/cc.go
+++ b/cc/cc.go
@@ -2203,8 +2203,8 @@
// For example, with maxSdkVersion is 10 and versionList is [9,11]
// it returns 9 as string. The list of stubs must be in order from
// oldest to newest.
-func (c *Module) chooseSdkVersion(ctx android.PathContext, stubsInfo []SharedLibraryStubsInfo,
- maxSdkVersion android.ApiLevel) (SharedLibraryStubsInfo, error) {
+func (c *Module) chooseSdkVersion(ctx android.PathContext, stubsInfo []SharedStubLibrary,
+ maxSdkVersion android.ApiLevel) (SharedStubLibrary, error) {
for i := range stubsInfo {
stubInfo := stubsInfo[len(stubsInfo)-i-1]
@@ -2215,7 +2215,7 @@
var err error
ver, err = android.ApiLevelFromUser(ctx, stubInfo.Version)
if err != nil {
- return SharedLibraryStubsInfo{}, err
+ return SharedStubLibrary{}, err
}
}
if ver.LessThanOrEqualTo(maxSdkVersion) {
@@ -2226,7 +2226,7 @@
for _, stubInfo := range stubsInfo {
versionList = append(versionList, stubInfo.Version)
}
- return SharedLibraryStubsInfo{}, fmt.Errorf("not found a version(<=%s) in versionList: %v", maxSdkVersion.String(), versionList)
+ return SharedStubLibrary{}, fmt.Errorf("not found a version(<=%s) in versionList: %v", maxSdkVersion.String(), versionList)
}
// Convert dependencies to paths. Returns a PathDeps containing paths
@@ -2369,9 +2369,9 @@
return
}
sharedLibraryInfo := ctx.OtherModuleProvider(dep, SharedLibraryInfoProvider).(SharedLibraryInfo)
- sharedLibraryStubsInfo := ctx.OtherModuleProvider(dep, SharedLibraryImplementationStubsInfoProvider).(SharedLibraryImplementationStubsInfo)
+ sharedLibraryStubsInfo := ctx.OtherModuleProvider(dep, SharedLibraryStubsProvider).(SharedLibraryStubsInfo)
- if !libDepTag.explicitlyVersioned && len(sharedLibraryStubsInfo.SharedLibraryStubsInfos) > 0 {
+ if !libDepTag.explicitlyVersioned && len(sharedLibraryStubsInfo.SharedStubLibraries) > 0 {
useStubs := false
if lib := moduleLibraryInterface(dep); lib.buildStubs() && c.UseVndk() { // LLNDK
@@ -2406,7 +2406,7 @@
// when to use (unspecified) stubs, check min_sdk_version and choose the right one
if useStubs {
sharedLibraryStubsInfo, err :=
- c.chooseSdkVersion(ctx, sharedLibraryStubsInfo.SharedLibraryStubsInfos, c.apexSdkVersion)
+ c.chooseSdkVersion(ctx, sharedLibraryStubsInfo.SharedStubLibraries, c.apexSdkVersion)
if err != nil {
ctx.OtherModuleErrorf(dep, err.Error())
return
diff --git a/cc/library.go b/cc/library.go
index 7ae75f2..5eea419 100644
--- a/cc/library.go
+++ b/cc/library.go
@@ -28,6 +28,7 @@
"android/soong/cc/config"
)
+// LibraryProperties is a collection of properties shared by cc library rules.
type LibraryProperties struct {
// local file name to pass to the linker as -unexported_symbols_list
Unexported_symbols_list *string `android:"path,arch_variant"`
@@ -115,14 +116,23 @@
Llndk_stubs *string
}
+// StaticProperties is a properties stanza to affect only attributes of the "static" variants of a
+// library module.
type StaticProperties struct {
Static StaticOrSharedProperties `android:"arch_variant"`
}
+// SharedProperties is a properties stanza to affect only attributes of the "shared" variants of a
+// library module.
type SharedProperties struct {
Shared StaticOrSharedProperties `android:"arch_variant"`
}
+// StaticOrSharedProperties is an embedded struct representing properties to affect attributes of
+// either only the "static" variants or only the "shared" variants of a library module. These override
+// the base properties of the same name.
+// Use `StaticProperties` or `SharedProperties`, depending on which variant is needed.
+// `StaticOrSharedProperties` exists only to avoid duplication.
type StaticOrSharedProperties struct {
Srcs []string `android:"path,arch_variant"`
@@ -242,16 +252,23 @@
return module.Init()
}
+// flagExporter is a separated portion of libraryDecorator pertaining to exported
+// include paths and flags. Keeping this dependency-related information separate
+// from the rest of library information is helpful in keeping data more structured
+// and explicit.
type flagExporter struct {
Properties FlagExporterProperties
- dirs android.Paths
- systemDirs android.Paths
- flags []string
+ dirs android.Paths // Include directories to be included with -I
+ systemDirs android.Paths // System include directories to be included with -isystem
+ flags []string // Exported raw flags.
deps android.Paths
headers android.Paths
}
+// exportedIncludes returns the effective include paths for this module and
+// any module that links against this module. This is obtained from
+// the export_include_dirs property in the appropriate target stanza.
func (f *flagExporter) exportedIncludes(ctx ModuleContext) android.Paths {
// TODO(b/150902910): product variant must use Target.Product
if ctx.useVndk() && f.Properties.Target.Vendor.Override_export_include_dirs != nil {
@@ -261,25 +278,35 @@
}
}
+// exportIncludes registers the include directories and system include directories to be exported
+// transitively to modules depending on this module.
func (f *flagExporter) exportIncludes(ctx ModuleContext) {
f.dirs = append(f.dirs, f.exportedIncludes(ctx)...)
f.systemDirs = append(f.systemDirs, android.PathsForModuleSrc(ctx, f.Properties.Export_system_include_dirs)...)
}
+// exportIncludesAsSystem registers the include directories and system include directories to be
+// exported transitively both as system include directories to modules depending on this module.
func (f *flagExporter) exportIncludesAsSystem(ctx ModuleContext) {
// all dirs are force exported as system
f.systemDirs = append(f.systemDirs, f.exportedIncludes(ctx)...)
f.systemDirs = append(f.systemDirs, android.PathsForModuleSrc(ctx, f.Properties.Export_system_include_dirs)...)
}
+// reexportDirs registers the given directories as include directories to be exported transitively
+// to modules depending on this module.
func (f *flagExporter) reexportDirs(dirs ...android.Path) {
f.dirs = append(f.dirs, dirs...)
}
+// reexportSystemDirs registers the given directories as system include directories
+// to be exported transitively to modules depending on this module.
func (f *flagExporter) reexportSystemDirs(dirs ...android.Path) {
f.systemDirs = append(f.systemDirs, dirs...)
}
+// reexportFlags registers the flags to be exported transitively to modules depending on this
+// module.
func (f *flagExporter) reexportFlags(flags ...string) {
if android.PrefixInList(flags, "-I") || android.PrefixInList(flags, "-isystem") {
panic(fmt.Errorf("Exporting invalid flag %q: "+
@@ -457,6 +484,8 @@
return l.collectedSnapshotHeaders
}
+// linkerProps returns the list of properties structs relevant for this library. (For example, if
+// the library is cc_shared_library, then static-library properties are omitted.)
func (library *libraryDecorator) linkerProps() []interface{} {
var props []interface{}
props = append(props, library.baseLinker.linkerProps()...)
@@ -476,6 +505,9 @@
return props
}
+// linkerFlags takes a Flags struct and augments it to contain linker flags that are defined by this
+// library, or that are implied by attributes of this library (such as whether this library is a
+// shared library).
func (library *libraryDecorator) linkerFlags(ctx ModuleContext, flags Flags) Flags {
flags = library.baseLinker.linkerFlags(ctx, flags)
@@ -526,6 +558,9 @@
return flags
}
+// compilerFlags takes a Flags and augments it to contain compile flags from global values,
+// per-target values, module type values, per-module Blueprints properties, extra flags from
+// `flags`, and generated sources from `deps`.
func (library *libraryDecorator) compilerFlags(ctx ModuleContext, flags Flags, deps PathDeps) Flags {
exportIncludeDirs := library.flagExporter.exportedIncludes(ctx)
if len(exportIncludeDirs) > 0 {
@@ -727,6 +762,8 @@
return name + suffix
}
+// getLibName returns the actual canonical name of the library (the name which
+// should be passed to the linker via linker flags).
func (library *libraryDecorator) getLibName(ctx BaseModuleContext) string {
name := library.getLibNameHelper(ctx.baseModuleName(), ctx.useVndk())
@@ -1058,18 +1095,18 @@
stubs := ctx.GetDirectDepsWithTag(stubImplDepTag)
if len(stubs) > 0 {
- var stubsInfo []SharedLibraryStubsInfo
+ var stubsInfo []SharedStubLibrary
for _, stub := range stubs {
stubInfo := ctx.OtherModuleProvider(stub, SharedLibraryInfoProvider).(SharedLibraryInfo)
flagInfo := ctx.OtherModuleProvider(stub, FlagExporterInfoProvider).(FlagExporterInfo)
- stubsInfo = append(stubsInfo, SharedLibraryStubsInfo{
+ stubsInfo = append(stubsInfo, SharedStubLibrary{
Version: moduleLibraryInterface(stub).stubsVersion(),
SharedLibraryInfo: stubInfo,
FlagExporterInfo: flagInfo,
})
}
- ctx.SetProvider(SharedLibraryImplementationStubsInfoProvider, SharedLibraryImplementationStubsInfo{
- SharedLibraryStubsInfos: stubsInfo,
+ ctx.SetProvider(SharedLibraryStubsProvider, SharedLibraryStubsInfo{
+ SharedStubLibraries: stubsInfo,
IsLLNDK: ctx.isLlndk(ctx.Config()),
})
@@ -1158,9 +1195,15 @@
}
}
+// link registers actions to link this library, and sets various fields
+// on this library to reflect information that should be exported up the build
+// tree (for example, exported flags and include paths).
func (library *libraryDecorator) link(ctx ModuleContext,
flags Flags, deps PathDeps, objs Objects) android.Path {
+ // Linking this library consists of linking `deps.Objs` (.o files in dependencies
+ // of this library), together with `objs` (.o files created by compiling this
+ // library).
objs = deps.Objs.Copy().Append(objs)
var out android.Path
if library.static() || library.header() {
@@ -1169,6 +1212,7 @@
out = library.linkShared(ctx, flags, deps, objs)
}
+ // Export include paths and flags to be propagated up the tree.
library.exportIncludes(ctx)
library.reexportDirs(deps.ReexportedDirs...)
library.reexportSystemDirs(deps.ReexportedSystemDirs...)
@@ -1176,6 +1220,7 @@
library.reexportDeps(deps.ReexportedDeps...)
library.addExportedGeneratedHeaders(deps.ReexportedGeneratedHeaders...)
+ // Optionally export aidl headers.
if Bool(library.Properties.Aidl.Export_aidl_headers) {
if library.baseCompiler.hasSrcExt(".aidl") {
dir := android.PathForModuleGen(ctx, "aidl")
@@ -1187,6 +1232,7 @@
}
}
+ // Optionally export proto headers.
if Bool(library.Properties.Proto.Export_proto_headers) {
if library.baseCompiler.hasSrcExt(".proto") {
var includes android.Paths
@@ -1221,25 +1267,30 @@
}
}
+ // Add sysprop-related directories to the exported directories of this library.
library.reexportDirs(dir)
library.reexportDeps(library.baseCompiler.pathDeps...)
library.addExportedGeneratedHeaders(library.baseCompiler.pathDeps...)
}
+ // Add stub-related flags if this library is a stub library.
if library.buildStubs() && !library.skipAPIDefine {
library.reexportFlags("-D" + versioningMacroName(ctx.Module().(*Module).ImplementationModuleName(ctx)) + "=" + library.stubsVersion())
}
+ // Propagate a Provider containing information about exported flags, deps, and include paths.
library.flagExporter.setProvider(ctx)
return out
}
+// buildStatic returns true if this library should be built as a static library.
func (library *libraryDecorator) buildStatic() bool {
return library.MutatedProperties.BuildStatic &&
BoolDefault(library.StaticProperties.Static.Enabled, true)
}
+// buildShared returns true if this library should be built as a shared library.
func (library *libraryDecorator) buildShared() bool {
return library.MutatedProperties.BuildShared &&
BoolDefault(library.SharedProperties.Shared.Enabled, true)
@@ -1346,36 +1397,46 @@
return library.shared() || library.static()
}
+// static returns true if this library is for a "static' variant.
func (library *libraryDecorator) static() bool {
return library.MutatedProperties.VariantIsStatic
}
+// shared returns true if this library is for a "shared' variant.
func (library *libraryDecorator) shared() bool {
return library.MutatedProperties.VariantIsShared
}
+// header returns true if this library is for a header-only variant.
func (library *libraryDecorator) header() bool {
+ // Neither "static" nor "shared" implies this library is header-only.
return !library.static() && !library.shared()
}
+// setStatic marks the library variant as "static".
func (library *libraryDecorator) setStatic() {
library.MutatedProperties.VariantIsStatic = true
library.MutatedProperties.VariantIsShared = false
}
+// setShared marks the library variant as "shared".
func (library *libraryDecorator) setShared() {
library.MutatedProperties.VariantIsStatic = false
library.MutatedProperties.VariantIsShared = true
}
+// BuildOnlyStatic disables building this library as a shared library.
func (library *libraryDecorator) BuildOnlyStatic() {
library.MutatedProperties.BuildShared = false
}
+// BuildOnlyShared disables building this library as a static library.
func (library *libraryDecorator) BuildOnlyShared() {
library.MutatedProperties.BuildStatic = false
}
+// HeaderOnly disables building this library as a shared or static library;
+// the library only exists to propagate header file dependencies up the build graph.
func (library *libraryDecorator) HeaderOnly() {
library.MutatedProperties.BuildShared = false
library.MutatedProperties.BuildStatic = false
@@ -1458,6 +1519,17 @@
var versioningMacroNamesListKey = android.NewOnceKey("versioningMacroNamesList")
+// versioningMacroNamesList returns a singleton map, where keys are "version macro names",
+// and values are the module name responsible for registering the version macro name.
+//
+// Version macros are used when building against stubs, to provide version information about
+// the stub. Only stub libraries should have an entry in this list.
+//
+// For example, when building against libFoo#ver, __LIBFOO_API__ macro is set to ver so
+// that headers from libFoo can be conditionally compiled (this may hide APIs
+// that are not available for the version).
+//
+// This map is used to ensure that there aren't conflicts between these version macro names.
func versioningMacroNamesList(config android.Config) *map[string]string {
return config.Once(versioningMacroNamesListKey, func() interface{} {
m := make(map[string]string)
@@ -1469,12 +1541,17 @@
// other characters are all converted to _
var charsNotForMacro = regexp.MustCompile("[^a-zA-Z0-9_]+")
+// versioningMacroName returns the canonical version macro name for the given module.
func versioningMacroName(moduleName string) string {
macroName := charsNotForMacro.ReplaceAllString(moduleName, "_")
macroName = strings.ToUpper(macroName)
return "__" + macroName + "_API__"
}
+// NewLibrary builds and returns a new Module corresponding to a C++ library.
+// Individual module implementations which comprise a C++ library (or something like
+// a C++ library) should call this function, set some fields on the result, and
+// then call the Init function.
func NewLibrary(hod android.HostOrDeviceSupported) (*Module, *libraryDecorator) {
module := newModule(hod, android.MultilibBoth)
@@ -1530,6 +1607,8 @@
}
}
+// LinkageMutator adds "static" or "shared" variants for modules depending
+// on whether the module can be built as a static library or a shared library.
func LinkageMutator(mctx android.BottomUpMutatorContext) {
cc_prebuilt := false
if m, ok := mctx.Module().(*Module); ok && m.linker != nil {
@@ -1607,6 +1686,9 @@
}
}
+// normalizeVersions modifies `versions` in place, so that each raw version
+// string becomes its normalized canonical form.
+// Validates that the versions in `versions` are specified in least to greatest order.
func normalizeVersions(ctx android.BaseModuleContext, versions []string) {
var previous android.ApiLevel
for i, v := range versions {
diff --git a/cc/linkable.go b/cc/linkable.go
index 0609b28..ddf3950 100644
--- a/cc/linkable.go
+++ b/cc/linkable.go
@@ -6,6 +6,7 @@
"github.com/google/blueprint"
)
+// LinkableInterface is an interface for a type of module that is linkable in a C++ library.
type LinkableInterface interface {
Module() android.Module
CcLibrary() bool
@@ -51,23 +52,30 @@
}
var (
+ // Dependency tag for crtbegin, an object file responsible for initialization.
CrtBeginDepTag = dependencyTag{name: "crtbegin"}
- CrtEndDepTag = dependencyTag{name: "crtend"}
+ // Dependency tag for crtend, an object file responsible for program termination.
+ CrtEndDepTag = dependencyTag{name: "crtend"}
+ // Dependency tag for coverage library.
CoverageDepTag = dependencyTag{name: "coverage"}
)
+// SharedDepTag returns the dependency tag for any C++ shared libraries.
func SharedDepTag() blueprint.DependencyTag {
return libraryDependencyTag{Kind: sharedLibraryDependency}
}
+// StaticDepTag returns the dependency tag for any C++ static libraries.
func StaticDepTag() blueprint.DependencyTag {
return libraryDependencyTag{Kind: staticLibraryDependency}
}
+// HeaderDepTag returns the dependency tag for any C++ "header-only" libraries.
func HeaderDepTag() blueprint.DependencyTag {
return libraryDependencyTag{Kind: headerLibraryDependency}
}
+// SharedLibraryInfo is a provider to propagate information about a shared C++ library.
type SharedLibraryInfo struct {
SharedLibrary android.Path
UnstrippedSharedLibrary android.Path
@@ -80,22 +88,30 @@
var SharedLibraryInfoProvider = blueprint.NewProvider(SharedLibraryInfo{})
-type SharedLibraryImplementationStubsInfo struct {
- SharedLibraryStubsInfos []SharedLibraryStubsInfo
-
- IsLLNDK bool
-}
-
-var SharedLibraryImplementationStubsInfoProvider = blueprint.NewProvider(SharedLibraryImplementationStubsInfo{})
-
-type SharedLibraryStubsInfo struct {
+// SharedStubLibrary is a struct containing information about a stub shared library.
+// Stub libraries are used for cross-APEX dependencies; when a library is to depend on a shared
+// library in another APEX, it must depend on the stub version of that library.
+type SharedStubLibrary struct {
+ // The version of the stub (corresponding to the stable version of the shared library being
+ // stubbed).
Version string
SharedLibraryInfo SharedLibraryInfo
FlagExporterInfo FlagExporterInfo
}
-var SharedLibraryStubsInfoProvider = blueprint.NewProvider(SharedLibraryStubsInfo{})
+// SharedLibraryStubsInfo is a provider to propagate information about all shared library stubs
+// which are dependencies of a library.
+// Stub libraries are used for cross-APEX dependencies; when a library is to depend on a shared
+// library in another APEX, it must depend on the stub version of that library.
+type SharedLibraryStubsInfo struct {
+ SharedStubLibraries []SharedStubLibrary
+ IsLLNDK bool
+}
+
+var SharedLibraryStubsProvider = blueprint.NewProvider(SharedLibraryStubsInfo{})
+
+// StaticLibraryInfo is a provider to propagate information about a static C++ library.
type StaticLibraryInfo struct {
StaticLibrary android.Path
Objects Objects
@@ -109,10 +125,12 @@
var StaticLibraryInfoProvider = blueprint.NewProvider(StaticLibraryInfo{})
+// FlagExporterInfo is a provider to propagate transitive library information
+// pertaining to exported include paths and flags.
type FlagExporterInfo struct {
- IncludeDirs android.Paths
- SystemIncludeDirs android.Paths
- Flags []string
+ IncludeDirs android.Paths // Include directories to be included with -I
+ SystemIncludeDirs android.Paths // System include directories to be included with -isystem
+ Flags []string // Exported raw flags.
Deps android.Paths
GeneratedHeaders android.Paths
}