31 // A Module handles generating all of the Ninja build actions needed to build a
32 // single module based on properties defined in a Blueprints file.  Module
34 // of the registered module types (and the associated ModuleFactory function).
35 // The Module's properties struct is automatically filled in with the property
39 // A Module can be split into multiple Modules by a Mutator.  All existing
40 // properties set on the module will be duplicated to the new Module, and then
43 // The Module implementation can access the build configuration as well as any
51 // In addition to implementing the GenerateBuildActions method, a Module should
56 // all the Modules).  The set of methods a Module supports will determine how
59 // For example, consider a Module that is responsible for generating a library
60 // that other modules can link against.  The library Module might implement the
67 //	func IsLibraryProducer(module blueprint.Module) {
68 //	    _, ok := module.(LibraryProducer)
72 // A binary-producing Module that depends on the library Module could then do:
78 //	        func(module blueprint.Module) {
79 //	            libProducer := module.(LibraryProducer)
91 // Any accesses to global variables or to Module objects that are not dependencies
92 // or variants of the current Module must be synchronized by the implementation of
94 type Module interface {  interface
95 	// Name returns a string used to uniquely identify each module.  The return
105 	// GenerateBuildActions is called by the Context that created the Module
107 	// actions (rules, pools, and build statements) needed to build the module.
112 	module Module  member
115 func CreateModuleProxy(module Module) ModuleProxy {  argument
117 		module: module,
122 	return m.module.Name()
126 	m.module.GenerateBuildActions(context)
129 // A DynamicDependerModule is a Module that may add dependencies that do not
130 // appear in its "deps" property.  Any Module that implements this interface
136 	Module
140 	// the list of module names that the DynamicDependerModule depends on
141 	// dynamically.  Module names that already appear in the "deps" property may
147 …// Module returns the current module as a Module.  It should rarely be necessary, as the module al…
149 	Module() Module  methodSpec
151 …// ModuleName returns the name of the module.  This is generally the value that was returned by Mo…
152 	// the module was created, but may have been modified by calls to BottomUpMutatorContext.Rename.
155 	// ModuleDir returns the path to the directory that contains the definition of the module.
158 …// ModuleType returns the name of the module type that was used to create the module, as specified…
162 	// ModuleTags returns the tags for this module that should be passed to
171 	// module.
177 	// ContainsProperty returns true if the specified property name was set in the module definition.
180 	// Errorf reports an error at the specified position of the module definition file.
183 	// ModuleErrorf reports an error at the line number of the module type in the module definition.
186 	// PropertyErrorf reports an error at the line number of a property in the module definition.
189 …// OtherModulePropertyErrorf reports an error at the line number of a property in the given module…
190 	OtherModulePropertyErrorf(logicModule Module, property string, format string, args ...interface{})  argument
192 …// Failed returns true if any errors have been reported.  In most cases the module can continue wi…
194 …// has prevented the module from creating necessary data it can return early when Failed returns t…
206 	// the module to be used in build system tests that run against a mock filesystem.
232 	// GetDirectDepWithTag returns the Module the direct dependency with the specified name, or nil if
234 	GetDirectDepWithTag(name string, tag DependencyTag) Module
236 	// GetDirectDep returns the Module and DependencyTag for the  direct dependency with the specified
237 	// name, or nil if none exists.  If there are multiple dependencies on the same module it returns
239 	GetDirectDep(name string) (Module, DependencyTag)
242 …// module visit will be called multiple times on that module and OtherModuleDependencyTag will ret…
245 …// The Module passed to the visit function should not be retained outside of the visit function, i…
247 	VisitDirectDeps(visit func(Module))  argument
252 …/ multiple direct dependencies on the same module pred and visit will be called multiple times on …
255 …// The Module passed to the visit function should not be retained outside of the visit function, i…
257 	VisitDirectDepsIf(pred func(Module) bool, visit func(Module))  argument
260 …// order. visit will only be called once for any given module, even if there are multiple paths th…
261 …// dependency tree to the module or multiple direct dependencies with different tags.  OtherModule…
262 	// return the tag for the first path found to the module.
264 …// The Module passed to the visit function should not be retained outside of the visit function, i…
266 	VisitDepsDepthFirst(visit func(Module))  argument
269 …// the dependency tree in depth first order.  visit will only be called once for any given module,…
270 …// multiple paths through the dependency tree to the module or multiple direct dependencies with d…
271 …// OtherModuleDependencyTag will return the tag for the first path found to the module.  The retur…
274 …// The Module passed to the visit function should not be retained outside of the visit function, i…
276 	VisitDepsDepthFirstIf(pred func(Module) bool, visit func(Module))  argument
285 	WalkDeps(visit func(Module, Module) bool)  argument
289 …// PrimaryModule returns the first variant of the current module.  Variants of a module are always…
291 …// Module returned by PrimaryModule without data races.  This can be used to perform singleton act…
292 	// only done once for all variants of a module.
293 	PrimaryModule() Module
295 …// FinalModule returns the last variant of the current module.  Variants of a module are always vi…
297 …// variants using VisitAllModuleVariants if the current module == FinalModule().  This can be used…
298 	// singleton actions that are only done once for all variants of a module.
299 	FinalModule() Module
301 …// IsFinalModule returns if the current module is the last variant.  Variants of a module are alwa…
303 …// variants using VisitAllModuleVariants if the current module is the last one.  This can be used …
304 	// singleton actions that are only done once for all variants of a module.
305 	IsFinalModule(module Module) bool  argument
307 …AllModuleVariants calls visit for each variant of the current module.  Variants of a module are al…
309 …// from all variants if the current module is the last one.  Otherwise, care must be taken to not …
311 	VisitAllModuleVariants(visit func(Module))  argument
313 …uleVariantProxies calls visit for each variant of the current module.  Variants of a module are al…
315 …// from all variants if the current module is the last one.  Otherwise, care must be taken to not …
319 …// OtherModuleName returns the name of another Module.  See BaseModuleContext.ModuleName for more …
321 	OtherModuleName(m Module) string  argument
323 …// OtherModuleDir returns the directory of another Module.  See BaseModuleContext.ModuleDir for mo…
325 	OtherModuleDir(m Module) string  argument
327 …// OtherModuleType returns the type of another Module.  See BaseModuleContext.ModuleType for more …
329 	OtherModuleType(m Module) string  argument
331 …// OtherModuleErrorf reports an error on another Module.  See BaseModuleContext.ModuleErrorf for m…
333 	OtherModuleErrorf(m Module, fmt string, args ...interface{})  argument
335 …// OtherModuleDependencyTag returns the dependency tag used to depend on a module, or nil if there…
336 …// on the module.  When called inside a Visit* method with current module being visited, and there…
337 …// dependencies on the module being visited, it returns the dependency tag used for the current de…
338 	OtherModuleDependencyTag(m Module) DependencyTag  argument
340 …// OtherModuleExists returns true if a module with the specified name exists, as determined by the…
344 …// ModuleFromName returns (module, true) if a module exists by the given name and same context nam…
346 	// module of the given name, or if the given name refers to an alias instead of a module.
347 	// There are no guarantees about which variant of the module will be returned.
348 	// Prefer retrieving the module using GetDirectDep or a visit function, when possible, as
349 	// this will guarantee the appropriate module-variant dependency is returned.
353 	ModuleFromName(name string) (Module, bool)
355 	// OtherModuleDependencyVariantExists returns true if a module with the
358 	// module. In other words, it checks for the module that AddVariationDependencies
362 	// OtherModuleFarDependencyVariantExists returns true if a module with the
364 	// variations, but not the non-local variations of the current module. In
365 	// other words, it checks for the module that AddFarVariationDependencies
369 	// OtherModuleReverseDependencyVariantExists returns true if a module with the
370 	// specified name exists with the same variations as the current module. In
371 	// other words, it checks for the module that AddReverseDependency would add a
375 	// OtherModuleProvider returns the value for a provider for the given module.  If the value is
380 	OtherModuleProvider(m Module, provider AnyProviderKey) (any, bool)  argument
382 	// OtherModuleIsAutoGenerated returns true if a module has been generated from another module,
384 	OtherModuleIsAutoGenerated(m Module) bool  argument
386 	// Provider returns the value for a provider for the current module.  If the value is
394 	// SetProvider sets the value for a provider for the current module.  It panics if not called
404 	EqualModules(m1, m2 Module) bool  argument
414 …// ModuleSubDir returns a unique name for the current variant of a module that can be used as part…
415 	// to ensure that each variant of a module gets its own intermediates directory to write to.
420 …// Variable creates a new ninja variable scoped to the module.  It can be referenced by calls to R…
421 	// in the same module.
424 …ule creates a new ninja rule scoped to the module.  It can be referenced by calls to Build in the …
441 	module         *moduleInfo  member
449 	return d.module
452 func (d *baseModuleContext) Module() Module {  func
453 	return d.module.logicModule
457 	return d.module.Name()
461 	return d.module.typeName
472 	_, ok := d.module.propertyPos[name]
477 	return filepath.Dir(d.module.relBlueprintsFile)
481 	return d.module.relBlueprintsFile
506 	d.error(d.context.moduleErrorf(d.module, format, args...))
512 	d.error(d.context.PropertyErrorf(d.module.logicModule, property, format, args...))
515 func (d *baseModuleContext) OtherModulePropertyErrorf(logicModule Module, property string, format s…
535 	return d.context.nameInterface.GetNamespace(newNamespaceContext(d.module))
551 func (m *baseModuleContext) EqualModules(m1, m2 Module) bool {
555 func (m *baseModuleContext) OtherModuleName(logicModule Module) string {
556 	module := m.context.moduleInfo[getWrappedModule(logicModule)]
557 	return module.Name()
560 func (m *baseModuleContext) OtherModuleDir(logicModule Module) string {
561 	module := m.context.moduleInfo[getWrappedModule(logicModule)]
562 	return filepath.Dir(module.relBlueprintsFile)
565 func (m *baseModuleContext) OtherModuleType(logicModule Module) string {
566 	module := m.context.moduleInfo[getWrappedModule(logicModule)]
567 	return module.typeName
570 func (m *baseModuleContext) OtherModuleErrorf(logicModule Module, format string,
573 	module := m.context.moduleInfo[getWrappedModule(logicModule)]
577 			Pos: module.pos,
579 		module: module,
583 func getWrappedModule(module Module) Module {  argument
584 	if mp, isProxy := module.(ModuleProxy); isProxy {
585 		return mp.module
587 	return module
590 func (m *baseModuleContext) OtherModuleDependencyTag(logicModule Module) DependencyTag {
592 …if m.visitingDep.module != nil && getWrappedModule(logicModule) == m.visitingDep.module.logicModul…
601 		if dep.module.logicModule == getWrappedModule(logicModule) {
609 func (m *baseModuleContext) ModuleFromName(name string) (Module, bool) {
610 	moduleGroup, exists := m.context.nameInterface.ModuleFromName(name, m.module.namespace())
613 …panic(fmt.Errorf("Expected exactly one module named %q, but got %d", name, len(moduleGroup.modules…
619 			panic(fmt.Errorf(`Expected actual module named %q, but group did not contain a module.
627 	_, exists := m.context.nameInterface.ModuleFromName(name, m.module.namespace())
632 	possibleDeps := m.context.moduleGroupFromName(name, m.module.namespace())
636 	found, _, errs := m.context.findVariant(m.module, m.config, possibleDeps, variations, false, false)
644 	possibleDeps := m.context.moduleGroupFromName(name, m.module.namespace())
648 	found, _, errs := m.context.findVariant(m.module, m.config, possibleDeps, variations, true, false)
656 	possibleDeps := m.context.moduleGroupFromName(name, m.module.namespace())
660 	found, _, errs := m.context.findVariant(m.module, m.config, possibleDeps, nil, false, true)
667 func (m *baseModuleContext) OtherModuleProvider(logicModule Module, provider AnyProviderKey) (any, …
668 	module := m.context.moduleInfo[getWrappedModule(logicModule)]
669 	return m.context.provider(module, provider.provider())
673 	return m.context.provider(m.module, provider.provider())
677 	m.context.setProvider(m.module, provider.provider(), value)
682 	for i, p := range m.module.providers {
694 	relPos := m.module.pos
695 	relPos.Filename = m.module.relBlueprintsFile
705 	// Whether the incremental flag is set and the module type supports
706 	// incremental, this will decide weather to cache the data for the module.
709 	// the cache for this module, i.e., no env, product variables and Soong
714 		if im, ok := m.module.logicModule.(Incremental); ok {
720 		hash, err := proptools.CalculateHash(m.module.properties)
726 		m.VisitDirectDeps(func(module Module) {
728 				append(cacheInput.ProvidersHash, m.context.moduleInfo[module].providerInitialValueHashes)
738 		m.module.buildActionCacheKey = cacheKey
745 		relPos := m.module.pos
746 		relPos.Filename = m.module.relBlueprintsFile
749 				m.context.setProvider(m.module, provider.Id, *provider.Value)
751 			m.module.incrementalRestored = true
752 			m.module.orderOnlyStrings = data.OrderOnlyStrings
760 func (m *baseModuleContext) GetDirectDep(name string) (Module, DependencyTag) {
761 	for _, dep := range m.module.directDeps {
762 		if dep.module.Name() == name {
763 			return dep.module.logicModule, dep.tag
770 func (m *baseModuleContext) GetDirectDepWithTag(name string, tag DependencyTag) Module {
772 	for _, dep := range m.module.directDeps {
773 		if dep.module.Name() == name {
775 				return dep.module.logicModule
782 …rorf("Unable to find dependency %q with requested tag %#v. Found: %#v", deps[0].module, tag, deps))
788 func (m *baseModuleContext) VisitDirectDeps(visit func(Module)) {
792 				m.module, funcName(visit), m.visitingDep.module))
796 	m.visitingParent = m.module
798 	for _, dep := range m.module.directDeps {
800 		visit(dep.module.logicModule)
811 				m.module, funcName(visit), m.visitingDep.module))
815 	m.visitingParent = m.module
817 	for _, dep := range m.module.directDeps {
819 		visit(ModuleProxy{dep.module.logicModule})
826 func (m *baseModuleContext) VisitDirectDepsIf(pred func(Module) bool, visit func(Module)) {
830 				m.module, funcName(pred), funcName(visit), m.visitingDep.module))
834 	m.visitingParent = m.module
836 	for _, dep := range m.module.directDeps {
838 		if pred(dep.module.logicModule) {
839 			visit(dep.module.logicModule)
847 func (m *baseModuleContext) VisitDepsDepthFirst(visit func(Module)) {
851 				m.module, funcName(visit), m.visitingDep.module))
855 	m.context.walkDeps(m.module, false, nil, func(dep depInfo, parent *moduleInfo) {
858 		visit(dep.module.logicModule)
865 func (m *baseModuleContext) VisitDepsDepthFirstIf(pred func(Module) bool,
866 	visit func(Module)) {
871 				m.module, funcName(pred), funcName(visit), m.visitingDep.module))
875 	m.context.walkDeps(m.module, false, nil, func(dep depInfo, parent *moduleInfo) {
876 		if pred(dep.module.logicModule) {
879 			visit(dep.module.logicModule)
887 func (m *baseModuleContext) WalkDeps(visit func(child, parent Module) bool) {
888 	m.context.walkDeps(m.module, true, func(dep depInfo, parent *moduleInfo) bool {
891 		return visit(dep.module.logicModule, parent.logicModule)
899 	m.context.walkDeps(m.module, true, func(dep depInfo, parent *moduleInfo) bool {
902 		return visit(ModuleProxy{dep.module.logicModule}, ModuleProxy{parent.logicModule})
909 func (m *baseModuleContext) PrimaryModule() Module {
910 	return m.module.group.modules.firstModule().logicModule
913 func (m *baseModuleContext) FinalModule() Module {
914 	return m.module.group.modules.lastModule().logicModule
917 func (m *baseModuleContext) IsFinalModule(module Module) bool {
918 	return m.module.group.modules.lastModule().logicModule == module
921 func (m *baseModuleContext) VisitAllModuleVariants(visit func(Module)) {
922 	m.context.visitAllModuleVariants(m.module, visit)
926 	m.context.visitAllModuleVariants(m.module, visitProxyAdaptor(visit))
941 func (m *baseModuleContext) OtherModuleIsAutoGenerated(logicModule Module) bool {
942 	module := m.context.moduleInfo[getWrappedModule(logicModule)]
943 	if module == nil {
944 		panic(fmt.Errorf("Module %s not found in baseModuleContext", logicModule.Name()))
946 	return module.createdBy != nil
950 	return m.module.variant.name
954 	return m.module.ModuleCacheKey()
996 	return m.module.missingDeps
1000 	return m.module.missingDeps
1026 	// AddDependency adds a dependency to the given module.  It returns a slice of modules for each
1031 	AddDependency(module Module, tag DependencyTag, name ...string) []Module  argument
1033 	// AddReverseDependency adds a dependency from the destination to the given module.
1035 	// correctly for all future mutator passes.  All reverse dependencies for a destination module are
1037 	// module's dependency list.  May only  be called by mutators that were marked with
1039 	AddReverseDependency(module Module, tag DependencyTag, name string)  argument
1041 …// AddVariationDependencies adds deps as dependencies of the current module, but uses the variatio…
1044 	// the all of the non-local variations of the current module, plus the variations argument.
1048 	AddVariationDependencies([]Variation, DependencyTag, ...string) []Module
1050 	// AddReverseVariationDependency adds a dependency from the named module to the current
1051 	// module. The given variations will be added to the current module's varations, and then the
1052 	// result will be used to find the correct variation of the depending module, which must exist.
1055 	// correctly for all future mutator passes.  All reverse dependencies for a destination module are
1057 	// module's dependency list.  May only  be called by mutators that were marked with
1061 	// AddFarVariationDependencies adds deps as dependencies of the current module, but uses the
1067 	// Unlike AddVariationDependencies, the variations of the current module are ignored - the
1072 	AddFarVariationDependencies([]Variation, DependencyTag, ...string) []Module
1074 	// ReplaceDependencies finds all the variants of the module with the specified name, then
1075 	// replaces all dependencies onto those variants with the current variant of this module.
1080 	// ReplaceDependenciesIf finds all the variants of the module with the specified name, then
1081 	// replaces all dependencies onto those variants with the current variant of this module
1087 	// Rename all variants of a module.  The new name is not visible to calls to ModuleName,
1092 …// CreateModule creates a new module by calling the factory method for the specified moduleType, a…
1095 	CreateModule(ModuleFactory, string, ...interface{}) Module
1098 // A Mutator function is called for each Module, and can modify properties on the modules.
1100 // and is always called on dependencies before being called on the depending module.
1103 // members of the module struct itself, to ensure the modified values are copied
1104 // if a second Mutator chooses to split the module a second time.
1123 … createVariationsWithTransition(variationNames []string, outgoingTransitions [][]string) []Module {
1127 … (mctx *mutatorContext) createVariations(variationNames []string, depChooser depChooser) []Module {
1128 	var ret []Module
1129 …modules, errs := mctx.context.createVariations(mctx.module, mctx.mutator, depChooser, variationNam…
1134 	for _, module := range modules {
1135 		ret = append(ret, module.logicModule)
1139 		panic("module already has variations from this mutator")
1150 func (mctx *mutatorContext) Module() Module {  func
1151 	return mctx.module.logicModule
1154 func (mctx *mutatorContext) AddDependency(module Module, tag DependencyTag, deps ...string) []Modul…
1155 	depInfos := make([]Module, 0, len(deps))
1157 		modInfo := mctx.context.moduleInfo[module]
1171 func (mctx *mutatorContext) AddReverseDependency(module Module, tag DependencyTag, destName string)…
1180 …destModule, errs := mctx.context.findReverseDependency(mctx.context.moduleInfo[module], mctx.confi…
1187 		// allowMissingDependencies is true and the module wasn't found
1193 		depInfo{mctx.context.moduleInfo[module], tag},
1206 …destModule, errs := mctx.context.findReverseDependency(mctx.module, mctx.config, variations, destN…
1213 		// allowMissingDependencies is true and the module wasn't found
1219 		depInfo{mctx.module, tag},
1224 	deps ...string) []Module {
1226 	depInfos := make([]Module, 0, len(deps))
1228 …depInfo, errs := mctx.context.addVariationDependency(mctx.module, mctx.mutator, mctx.config, varia…
1242 	deps ...string) []Module {
1244 	depInfos := make([]Module, 0, len(deps))
1246 …depInfo, errs := mctx.context.addVariationDependency(mctx.module, mctx.mutator, mctx.config, varia…
1263 type ReplaceDependencyPredicate func(from Module, tag DependencyTag, to Module) bool
1270 	targets := mctx.context.moduleVariantsThatDependOn(name, mctx.module)
1273 		panic(fmt.Errorf("ReplaceDependencies could not find identical variant {%s} for module %s\n"+
1275 			mctx.context.prettyPrintVariant(mctx.module.variant.variations),
1277 …mctx.context.prettyPrintGroupVariants(mctx.context.moduleGroupFromName(name, mctx.module.namespace…
1281 		mctx.replace = append(mctx.replace, replace{target, mctx.module, predicate})
1289 	mctx.rename = append(mctx.rename, rename{mctx.module.group, name})
1292 …mutatorContext) CreateModule(factory ModuleFactory, typeName string, props ...interface{}) Module {
1297 	module := newModule(factory)
1299 	module.relBlueprintsFile = mctx.module.relBlueprintsFile
1300 	module.pos = mctx.module.pos
1301 	module.propertyPos = mctx.module.propertyPos
1302 	module.createdBy = mctx.module
1303 	module.typeName = typeName
1306 		err := proptools.AppendMatchingProperties(module.properties, p, nil)
1312 	mctx.newModules = append(mctx.newModules, module)
1314 	return module.logicModule
1326 				paused:  mctx.module,
1355 …// CreateModule creates a new module by calling the factory method for the specified moduleType, a…
1357 	CreateModule(ModuleFactory, string, ...interface{}) Module
1359 	// CreateModuleInDirectory creates a new module in the specified directory by calling the
1362 	CreateModuleInDirectory(ModuleFactory, string, string, ...interface{}) Module
1364 	// RegisterScopedModuleType creates a new module type that is scoped to the current Blueprints
1369 …ext) createModule(factory ModuleFactory, typeName, moduleDir string, props ...interface{}) Module {
1370 	module := newModule(factory)
1372 	module.relBlueprintsFile = moduleDir
1373 	module.pos = l.module.pos
1374 	module.propertyPos = l.module.propertyPos
1375 	module.createdBy = l.module
1376 	module.typeName = typeName
1379 		err := proptools.AppendMatchingProperties(module.properties, p, nil)
1385 	l.newModules = append(l.newModules, module)
1387 	return module.logicModule
1390 …oadHookContext) CreateModule(factory ModuleFactory, typeName string, props ...interface{}) Module {
1391 	return l.createModule(factory, typeName, l.module.relBlueprintsFile, props...)
1394 …ModuleInDirectory(factory ModuleFactory, typeName, moduleDir string, props ...interface{}) Module {
1396 		panic(fmt.Errorf("Cannot create a module in %s", moduleDir))
1405 		panic(fmt.Errorf("A global module type named %q already exists", name))
1409 		panic(fmt.Errorf("A module type named %q already exists in this scope", name))
1435 // Load hooks need to be added by module factories, which don't have any parameter to get to the
1436 // Context, and only produce a Module interface with no base implementation, so the load hooks
1437 // must be stored in a global map.  The key is a pointer allocated by the module factory, so there
1439 // contents should be short-lived, they are added during a module factory and removed immediately
1440 // after the module factory returns.
1443 func AddLoadHook(module Module, hook LoadHook) {  argument
1445 	AddLoadHookWithPriority(module, hook, 0)
1451 func AddLoadHookWithPriority(module Module, hook LoadHook, priority int) {  argument
1452 	// Only one goroutine can be processing a given module, so no additional locking is required
1454 	v, exists := pendingHooks.Load(module)
1456 		v, _ = pendingHooks.LoadOrStore(module, new([]LoadHookWithPriority))
1462 func runAndRemoveLoadHooks(ctx *Context, config interface{}, module *moduleInfo,
1465 	if v, exists := pendingHooks.Load(module.logicModule); exists {
1476 					module:  module,
1485 		pendingHooks.Delete(module.logicModule)
1498 // * Valid module types.
1507 // * Invokes relevant factory to create Module instances.
1508 // * Unpacks the properties into the Module.
1520 		case *parser.Module:
1532 func maybeLogicModule(module *moduleInfo) Module {
1533 	if module != nil {
1534 		return module.logicModule