{"id":20498489,"url":"https://github.com/grapheneos/platform_build_soong","last_synced_at":"2025-07-06T03:02:45.610Z","repository":{"id":40243709,"uuid":"101214915","full_name":"GrapheneOS/platform_build_soong","owner":"GrapheneOS","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-11T23:40:10.000Z","size":72730,"stargazers_count":7,"open_issues_count":0,"forks_count":21,"subscribers_count":3,"default_branch":"15-qpr2","last_synced_at":"2025-04-13T18:55:39.558Z","etag":null,"topics":["android","security"],"latest_commit_sha":null,"homepage":"https://grapheneos.org/","language":"Go","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GrapheneOS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"licenses/Android.bp","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"thestinger","custom":"https://grapheneos.org/donate"}},"created_at":"2017-08-23T18:56:51.000Z","updated_at":"2025-04-04T03:08:13.000Z","dependencies_parsed_at":"2023-10-23T19:25:21.913Z","dependency_job_id":"07fbbef2-d8a7-4f86-b4f5-193b1153c5ce","html_url":"https://github.com/GrapheneOS/platform_build_soong","commit_stats":null,"previous_names":[],"tags_count":791,"template":false,"template_full_name":null,"purl":"pkg:github/GrapheneOS/platform_build_soong","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrapheneOS%2Fplatform_build_soong","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrapheneOS%2Fplatform_build_soong/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrapheneOS%2Fplatform_build_soong/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrapheneOS%2Fplatform_build_soong/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GrapheneOS","download_url":"https://codeload.github.com/GrapheneOS/platform_build_soong/tar.gz/refs/heads/15-qpr2","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrapheneOS%2Fplatform_build_soong/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263841584,"owners_count":23518481,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","security"],"created_at":"2024-11-15T18:14:26.891Z","updated_at":"2025-07-06T03:02:45.559Z","avatar_url":"https://github.com/GrapheneOS.png","language":"Go","funding_links":["https://github.com/sponsors/thestinger","https://grapheneos.org/donate"],"categories":[],"sub_categories":[],"readme":"# Soong\n\nSoong is one of the build systems used in Android. There are altogether three:\n* The legacy Make-based build system that is controlled by files called\n  `Android.mk`.\n* Soong, which is controlled by files called `Android.bp`.\n* The upcoming Bazel-based build system that is controlled by files called\n  `BUILD.bazel`.\n\n`Android.bp` file are JSON-like declarative descriptions of \"modules\" to build;\na \"module\" is the basic unit of building that Soong understands, similarly to\nhow \"target\" is the basic unit of building for Bazel (and Make, although the\ntwo kinds of \"targets\" are very different)\n\nSee [Simple Build\nConfiguration](https://source.android.com/compatibility/tests/development/blueprints)\non source.android.com to read how Soong is configured for testing.\n\n### Contributing\n\nCode reviews are handled through the usual code review system of Android,\navailable [here](https://android-review.googlesource.com/dashboard/self).\n\nFor simple changes (fixing typos, obvious optimizations, etc.), sending a code\nreview request is enough. For more substantial changes, file a bug in our\n[bug tracker](https://issuetracker.google.com/issues/new?component=381517) or\nor write us at android-building@googlegroups.com .\n\n## Android.bp file format\n\nBy design, Android.bp files are very simple.  There are no conditionals or\ncontrol flow statements - any complexity is handled in build logic written in\nGo.  The syntax and semantics of Android.bp files are intentionally similar\nto [Bazel BUILD files](https://bazel.build/concepts/build-files) when possible.\n\n### Modules\n\nA module in an Android.bp file starts with a module type, followed by a set of\nproperties in `name: value,` format:\n\n```\ncc_binary {\n    name: \"gzip\",\n    srcs: [\"src/test/minigzip.c\"],\n    shared_libs: [\"libz\"],\n    stl: \"none\",\n}\n```\n\nEvery module must have a `name` property, and the value must be unique across\nall Android.bp files.\n\nThe list of valid module types and their properties can be generated by calling\n`m soong_docs`. It will be written to `$OUT_DIR/soong/docs/soong_build.html`.\nThis 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).\n\n### File lists\n\nProperties that take a list of files can also take glob patterns and output path\nexpansions.\n\n* Glob patterns can contain the normal Unix wildcard `*`, for example `\"*.java\"`.\n\n  Glob patterns can also contain a single `**` wildcard as a path element, which\n  will match zero or more path elements. For example, `java/**/*.java` will match\n  `java/Main.java` and `java/com/android/Main.java`.\n\n* Output path expansions take the format `:module` or `:module{.tag}`, where\n  `module` is the name of a module that produces output files, and it expands to\n  a list of those output files. With the optional `{.tag}` suffix, the module\n  may produce a different list of outputs according to `tag`.\n\n  For example, a `droiddoc` module with the name \"my-docs\" would return its\n  `.stubs.srcjar` output with `\":my-docs\"`, and its `.doc.zip` file with\n  `\":my-docs{.doc.zip}\"`.\n\n  This is commonly used to reference `filegroup` modules, whose output files\n  consist of their `srcs`.\n\n### Variables\n\nAn Android.bp file may contain top-level variable assignments:\n```\ngzip_srcs = [\"src/test/minigzip.c\"],\n\ncc_binary {\n    name: \"gzip\",\n    srcs: gzip_srcs,\n    shared_libs: [\"libz\"],\n    stl: \"none\",\n}\n```\n\nVariables are scoped to the remainder of the file they are declared in, as well\nas any child Android.bp files.  Variables are immutable with one exception - they\ncan be appended to with a += assignment, but only before they have been\nreferenced.\n\n### Comments\n\nAndroid.bp files can contain C-style multiline `/* */` and C++ style single-line\n`//` comments.\n\n### Types\n\nVariables and properties are strongly typed. Variables are dynamically typed\nbased on the first assignment, and properties are statically typed by the\nmodule type.  The supported types are:\n* Bool (`true` or `false`)\n* Integers (`int`)\n* Strings (`\"string\"`)\n* Lists of strings (`[\"string1\", \"string2\"]`)\n* Maps (`{key1: \"value1\", key2: [\"value2\"]}`)\n\nMaps may contain values of any type, including nested maps. Lists and maps may\nhave trailing commas after the last value.\n\nStrings can contain double quotes using `\\\"`, for example `\"cat \\\"a b\\\"\"`.\n\n### Operators\n\nThe `+` operator:\n* Sums integers.\n* Concatenates strings and lists.\n* Produces the union of maps.\n\nConcatenating maps produces a map whose keys are the union of the given maps'\nkeys, and whose mapped values are the union of the given maps' corresponding\nmapped values.\n\n### Defaults modules\n\nA `defaults` module can be used to repeat the same properties in multiple\nmodules. For example:\n\n```\ncc_defaults {\n    name: \"gzip_defaults\",\n    shared_libs: [\"libz\"],\n    stl: \"none\",\n}\n\ncc_binary {\n    name: \"gzip\",\n    defaults: [\"gzip_defaults\"],\n    srcs: [\"src/test/minigzip.c\"],\n}\n```\n\n### Packages\n\nThe build is organized into packages where each package is a collection of related files and a\nspecification of the dependencies among them in the form of modules.\n\nA package is defined as a directory containing a file named `Android.bp`, residing beneath the\ntop-level directory in the build and its name is its path relative to the top-level directory. A\npackage includes all files in its directory, plus all subdirectories beneath it, except those which\nthemselves contain an `Android.bp` file.\n\nThe modules in a package's `Android.bp` and included files are part of the module.\n\nFor example, in the following directory tree (where `.../android/` is the top-level Android\ndirectory) there are two packages, `my/app`, and the subpackage `my/app/tests`. Note that\n`my/app/data` is not a package, but a directory belonging to package `my/app`.\n\n    .../android/my/app/Android.bp\n    .../android/my/app/app.cc\n    .../android/my/app/data/input.txt\n    .../android/my/app/tests/Android.bp\n    .../android/my/app/tests/test.cc\n\nThis is based on the Bazel package concept.\n\nThe `package` module type allows information to be specified about a package. Only a single\n`package` module can be specified per package and in the case where there are multiple `.bp` files\nin the same package directory it is highly recommended that the `package` module (if required) is\nspecified in the `Android.bp` file.\n\nUnlike most module type `package` does not have a `name` property. Instead the name is set to the\nname of the package, e.g. if the package is in `top/intermediate/package` then the package name is\n`//top/intermediate/package`.\n\nE.g. The following will set the default visibility for all the modules defined in the package and\nany subpackages that do not set their own default visibility (irrespective of whether they are in\nthe same `.bp` file as the `package` module) to be visible to all the subpackages by default.\n\n```\npackage {\n    default_visibility: [\":__subpackages__\"]\n}\n```\n\n### Referencing Modules\n\nA module `libfoo` can be referenced by its name\n\n```\ncc_binary {\n    name: \"app\",\n    shared_libs: [\"libfoo\"],\n}\n```\n\nObviously, this works only if there is only one `libfoo` module in the source\ntree. Ensuring such name uniqueness for larger trees may become problematic. We\nmight also want to use the same name in multiple mutually exclusive subtrees\n(for example, implementing different devices) deliberately in order to describe\na functionally equivalent module. Enter Soong namespaces.\n\n#### Namespaces\n\nThe presence of the `soong_namespace {..}` in an Android.bp file defines a\n**namespace**. For instance, having\n\n```\nsoong_namespace {\n    ...\n}\n...\n```\n\nin `device/google/bonito/Android.bp` informs Soong that within the\n`device/google/bonito` package the module names are unique, that is, all the\nmodules defined in the Android.bp files in the `device/google/bonito/` tree have\nunique names. However, there may be modules with the same names outside\n`device/google/bonito` tree. Indeed, there is a module `\"pixelstats-vendor\"`\nboth in `device/google/bonito/pixelstats` and in\n`device/google/coral/pixelstats`.\n\nThe name of a namespace is the path of its directory. The name of the namespace\nin the example above is thus `device/google/bonito`.\n\nAn implicit **global namespace** corresponds to the source tree as a whole. It\nhas empty name.\n\nA module name's **scope** is the smallest namespace containing it. Suppose a\nsource tree has `device/my` and `device/my/display` namespaces. If `libfoo`\nmodule is defined in `device/my/display/lib/Android.bp`, its namespace is\n`device/my/display`.\n\nThe name uniqueness thus means that module's name is unique within its scope. In\nother words, \"//_scope_:_name_\" is globally unique module reference, e.g,\n`\"//device/google/bonito:pixelstats-vendor\"`. _Note_ that the name of the\nnamespace for a module may be different from module's package name: `libfoo`\nbelongs to `device/my/display` namespace but is contained in\n`device/my/display/lib` package.\n\n#### Name Resolution\n\nThe form of a module reference determines how Soong locates the module.\n\nFor a **global reference** of the \"//_scope_:_name_\" form, Soong verifies there\nis a namespace called \"_scope_\", then verifies it contains a \"_name_\" module and\nuses it. Soong verifies there is only one \"_name_\" in \"_scope_\" at the beginning\nwhen it parses Android.bp files.\n\nA **local reference** has \"_name_\" form, and resolving it involves looking for a\nmodule \"_name_\" in one or more namespaces. By default only the global namespace\nis searched for \"_name_\" (in other words, only the modules not belonging to an\nexplicitly defined scope are considered). The `imports` attribute of the\n`soong_namespaces` allows to specify where to look for modules . For instance,\nwith `device/google/bonito/Android.bp` containing\n\n```\nsoong_namespace {\n    imports: [\n        \"hardware/google/interfaces\",\n        \"hardware/google/pixel\",\n        \"hardware/qcom/bootctrl\",\n    ],\n}\n```\n\na reference to `\"libpixelstats\"` will resolve to the module defined in\n`hardware/google/pixel/pixelstats/Android.bp` because this module is in\n`hardware/google/pixel` namespace.\n\n**TODO**: Conventionally, languages with similar concepts provide separate\nconstructs for namespace definition and name resolution (`namespace` and `using`\nin C++, for instance). Should Soong do that, too?\n\n#### Referencing modules in makefiles\n\nWhile we are gradually converting makefiles to Android.bp files, Android build\nis described by a mixture of Android.bp and Android.mk files, and a module\ndefined in an Android.mk file can reference a module defined in Android.bp file.\nFor instance, a binary still defined in an Android.mk file may have a library\ndefined in already converted Android.bp as a dependency.\n\nA module defined in an Android.bp file and belonging to the global namespace can\nbe referenced from a makefile without additional effort. If a module belongs to\nan explicit namespace, it can be referenced from a makefile only after after the\nname of the namespace has been added to the value of PRODUCT_SOONG_NAMESPACES\nvariable.\n\nNote that makefiles have no notion of namespaces and exposing namespaces with\nthe same modules via PRODUCT_SOONG_NAMESPACES may cause Make failure. For\ninstance, exposing both `device/google/bonito` and `device/google/coral`\nnamespaces will cause Make failure because it will see two targets for the\n`pixelstats-vendor` module.\n\n### Visibility\n\nThe `visibility` property on a module controls whether the module can be\nused by other packages. Modules are always visible to other modules declared\nin the same package. This is based on the Bazel visibility mechanism.\n\nIf specified the `visibility` property must contain at least one rule.\n\nEach rule in the property must be in one of the following forms:\n* `[\"//visibility:public\"]`: Anyone can use this module.\n* `[\"//visibility:private\"]`: Only rules in the module's package (not its\nsubpackages) can use this module.\n* `[\"//visibility:override\"]`: Discards any rules inherited from defaults or a\ncreating module. Can only be used at the beginning of a list of visibility\nrules.\n* `[\"//visibility:any_partition\"]`: Any modules of type android_filesystem\nor android_system_image can use this module. Intended for modules that no one\nshould link against, but should still be included in soong-built partitions.\n* `[\"//some/package:__pkg__\", \"//other/package:__pkg__\"]`: Only modules in\n`some/package` and `other/package` (defined in `some/package/*.bp` and\n`other/package/*.bp`) have access to this module. Note that sub-packages do not\nhave access to the rule; for example, `//some/package/foo:bar` or\n`//other/package/testing:bla` wouldn't have access. `__pkg__` is a special\nmodule and must be used verbatim. It represents all of the modules in the\npackage.\n* `[\"//project:__subpackages__\", \"//other:__subpackages__\"]`: Only modules in\npackages `project` or `other` or in one of their sub-packages have access to\nthis module. For example, `//project:rule`, `//project/library:lib` or\n`//other/testing/internal:munge` are allowed to depend on this rule (but not\n`//independent:evil`)\n* `[\"//project\"]`: This is shorthand for `[\"//project:__pkg__\"]`\n* `[\":__subpackages__\"]`: This is shorthand for `[\"//project:__subpackages__\"]`\nwhere `//project` is the module's package, e.g. using `[\":__subpackages__\"]` in\n`packages/apps/Settings/Android.bp` is equivalent to\n`//packages/apps/Settings:__subpackages__`.\n* `[\"//visibility:legacy_public\"]`: The default visibility, behaves as\n`//visibility:public` for now. It is an error if it is used in a module.\n\nThe visibility rules of `//visibility:public` and `//visibility:private` cannot\nbe combined with any other visibility specifications, except\n`//visibility:public` is allowed to override visibility specifications imported\nthrough the `defaults` property.\n\nPackages outside `vendor/` cannot make themselves visible to specific packages\nin `vendor/`, e.g. a module in `libcore` cannot declare that it is visible to\nsay `vendor/google`, instead it must make itself visible to all packages within\n`vendor/` using `//vendor:__subpackages__`.\n\nIf a module does not specify the `visibility` property then it uses the\n`default_visibility` property of the `package` module in the module's package.\n\nIf the `default_visibility` property is not set for the module's package then\nit will use the `default_visibility` of its closest ancestor package for which\na `default_visibility` property is specified.\n\nIf no `default_visibility` property can be found then the module uses the\nglobal default of `//visibility:legacy_public`.\n\nThe `visibility` property has no effect on a defaults module although it does\napply to any non-defaults module that uses it. To set the visibility of a\ndefaults module, use the `defaults_visibility` property on the defaults module;\nnot to be confused with the `default_visibility` property on the package module.\n\nOnce the build has been completely switched over to soong it is possible that a\nglobal refactoring will be done to change this to `//visibility:private` at\nwhich point all packages that do not currently specify a `default_visibility`\nproperty will be updated to have\n`default_visibility = [//visibility:legacy_public]` added. It will then be the\nowner's responsibility to replace that with a more appropriate visibility.\n\n### Formatter\n\nSoong includes a canonical formatter for Android.bp files, similar to\n[gofmt](https://golang.org/cmd/gofmt/).  To recursively reformat all Android.bp files\nin the current directory:\n```\nbpfmt -w .\n```\n\nThe canonical format includes 4 space indents, newlines after every element of a\nmulti-element list, and always includes a trailing comma in lists and maps.\n\n### Convert Android.mk files\n\nSoong includes a tool perform a first pass at converting Android.mk files\nto Android.bp files:\n\n```\nandroidmk Android.mk \u003e Android.bp\n```\n\nThe tool converts variables, modules, comments, and some conditionals, but any\ncustom Makefile rules, complex conditionals or extra includes must be converted\nby hand.\n\n#### Differences between Android.mk and Android.bp\n\n* Android.mk files often have multiple modules with the same name (for example\nfor static and shared version of a library, or for host and device versions).\nAndroid.bp files require unique names for every module, but a single module can\nbe built in multiple variants, for example by adding `host_supported: true`.\nThe androidmk converter will produce multiple conflicting modules, which must\nbe resolved by hand to a single module with any differences inside\n`target: { android: { }, host: { } }` blocks.\n\n### Conditionals\n\nSoong deliberately does not support most conditionals in Android.bp files.  We\nsuggest removing most conditionals from the build.  See\n[Best Practices](docs/best_practices.md#removing-conditionals) for some\nexamples on how to remove conditionals.\n\nMost conditionals supported natively by Soong are converted to a map\nproperty.  When building the module one of the properties in the map will be\nselected, and its values appended to the property with the same name at the\ntop level of the module.\n\nFor example, to support architecture specific files:\n```\ncc_library {\n    ...\n    srcs: [\"generic.cpp\"],\n    arch: {\n        arm: {\n            srcs: [\"arm.cpp\"],\n        },\n        x86: {\n            srcs: [\"x86.cpp\"],\n        },\n    },\n}\n```\n\nWhen building the module for arm the `generic.cpp` and `arm.cpp` sources will\nbe built.  When building for x86 the `generic.cpp` and 'x86.cpp' sources will\nbe built.\n\n#### Soong Config Variables\n\nWhen converting vendor modules that contain conditionals, simple conditionals\ncan be supported through Soong config variables using `soong_config_*`\nmodules that describe the module types, variables and possible values:\n\n```\nsoong_config_module_type {\n    name: \"acme_cc_defaults\",\n    module_type: \"cc_defaults\",\n    config_namespace: \"acme\",\n    variables: [\"board\"],\n    bool_variables: [\"feature\"],\n    list_variables: [\"impl\"],\n    value_variables: [\"width\"],\n    properties: [\"cflags\", \"srcs\"],\n}\n\nsoong_config_string_variable {\n    name: \"board\",\n    values: [\"soc_a\", \"soc_b\", \"soc_c\"],\n}\n```\n\nThis example describes a new `acme_cc_defaults` module type that extends the\n`cc_defaults` module type, with four additional conditionals based on variables\n`board`, `feature`, `impl` and `width` which can affect properties `cflags` and\n`srcs`. The four types of soong variables control properties in the following\nways.\n\n* bool variable (e.g. `feature`): Properties are applied if set to `true`.\n* list variable (e.g. `impl`): (lists of strings properties only) Properties are\n  applied for each value in the list, using `%s` substitution. For example, if\n  the property is `[\"%s.cpp\", \"%s.h\"]` and the list value is `foo bar`,\n  the result is `[\"foo.cpp\", \"foo.h\", \"bar.cpp\", \"bar.h\"]`.\n* value variable (e.g. `width`): (strings or lists of strings) The value are\n  directly substituted into properties using `%s`.\n* string variable (e.g. `board`): Properties are applied only if they match the\n  variable's value.\n\nAdditionally, each conditional containing a `conditions_default` property can\naffect `cflags` and `srcs` in the following conditions:\n\n* bool variable (e.g. `feature`): the variable is unspecified or not set to\n  `true`\n* list variable (e.g. `impl`): the variable is unspecified\n* value variable (e.g. `width`): the variable is unspecified\n* string variable (e.g. `board`): the variable is unspecified or the variable is\n  set to a string unused in the given module. For example, with `board`, if the\n  `board` conditional contains the properties `soc_a` and `conditions_default`,\n  when `board` is `soc_b`, the `cflags` and `srcs` values under\n  `conditions_default` is used. To specify that no properties should be amended\n  for `soc_b`, you can set `soc_b: {},`.\n\nThe values of the variables can be set from a product's `BoardConfig.mk` file:\n```\n$(call soong_config_set,acme,board,soc_a)\n$(call soong_config_set,acme,feature,true)\n$(call soong_config_set,acme,impl,foo.cpp bar.cpp)\n$(call soong_config_set,acme,width,200)\n```\n\nThe `acme_cc_defaults` module type can be used anywhere after the definition in\nthe file where it is defined, or can be imported into another file with:\n```\nsoong_config_module_type_import {\n    from: \"device/acme/Android.bp\",\n    module_types: [\"acme_cc_defaults\"],\n}\n```\n\nIt can used like any other module type:\n```\nacme_cc_defaults {\n    name: \"acme_defaults\",\n    cflags: [\"-DGENERIC\"],\n    soong_config_variables: {\n        board: {\n            soc_a: {\n                cflags: [\"-DSOC_A\"],\n            },\n            soc_b: {\n                cflags: [\"-DSOC_B\"],\n            },\n            conditions_default: {\n                cflags: [\"-DSOC_DEFAULT\"],\n            },\n        },\n        feature: {\n            cflags: [\"-DFEATURE\"],\n            conditions_default: {\n                cflags: [\"-DFEATURE_DEFAULT\"],\n            },\n        },\n        width: {\n            cflags: [\"-DWIDTH=%s\"],\n            conditions_default: {\n                cflags: [\"-DWIDTH=DEFAULT\"],\n            },\n        },\n        impl: {\n            srcs: [\"impl/%s\"],\n            conditions_default: {\n                srcs: [\"impl/default.cpp\"],\n            },\n        },\n    },\n}\n\ncc_library {\n    name: \"libacme_foo\",\n    defaults: [\"acme_defaults\"],\n    srcs: [\"*.cpp\"],\n}\n```\n\nWith the `BoardConfig.mk` snippet above, `libacme_foo` would build with\n`cflags: \"-DGENERIC -DSOC_A -DFEATURE -DWIDTH=200\"` and\n`srcs: [\"*.cpp\", \"impl/foo.cpp\", \"impl/bar.cpp\"]`.\n\nAlternatively, with `DefaultBoardConfig.mk`:\n\n```\nSOONG_CONFIG_NAMESPACES += acme\nSOONG_CONFIG_acme += \\\n    board \\\n    feature \\\n    impl \\\n    width \\\n\nSOONG_CONFIG_acme_feature := false\n```\n\nthen `libacme_foo` would build with `cflags: \"-DGENERIC -DSOC_DEFAULT -DFEATURE_DEFAULT -DSIZE=DEFAULT\"`\nand `srcs: [\"*.cpp\", \"impl/default.cpp\"]`.\n\nAlternatively, with `DefaultBoardConfig.mk`:\n\n```\nSOONG_CONFIG_NAMESPACES += acme\nSOONG_CONFIG_acme += \\\n    board \\\n    feature \\\n    impl \\\n    width \\\n\nSOONG_CONFIG_acme_board := soc_c\nSOONG_CONFIG_acme_impl := baz\n```\n\nthen `libacme_foo` would build with `cflags: \"-DGENERIC -DSOC_DEFAULT\n-DFEATURE_DEFAULT -DSIZE=DEFAULT\"` and `srcs: [\"*.cpp\", \"impl/baz.cpp\"]`.\n\n`soong_config_module_type` modules will work best when used to wrap defaults\nmodules (`cc_defaults`, `java_defaults`, etc.), which can then be referenced\nby all of the vendor's other modules using the normal namespace and visibility\nrules.\n\n## Build logic\n\nThe build logic is written in Go using the\n[blueprint](https://android.googlesource.com/platform/build/blueprint)\nframework.  Build logic receives module definitions parsed into Go structures\nusing reflection and produces build rules.  The build rules are collected by\nblueprint and written to a [ninja](http://ninja-build.org) build file.\n\n## Environment Variables Config File\n\nSoong can optionally load environment variables from a pre-specified\nconfiguration file during startup. These environment variables can be used\nto control the behavior of the build. For example, these variables can determine\nwhether remote-execution should be used for the build or not.\n\nThe `ANDROID_BUILD_ENVIRONMENT_CONFIG_DIR` environment variable specifies the\ndirectory in which the config file should be searched for. The\n`ANDROID_BUILD_ENVIRONMENT_CONFIG` variable determines the name of the config\nfile to be searched for within the config directory. For example, the following\nbuild comand will load `ENV_VAR_1` and `ENV_VAR_2` environment variables from\nthe `example_config.json` file inside the `build/soong` directory.\n\n```\nANDROID_BUILD_ENVIRONMENT_CONFIG_DIR=build/soong \\\n  ANDROID_BUILD_ENVIRONMENT_CONFIG=example_config \\\n  build/soong/soong_ui.bash\n```\n\n## Other documentation\n\n* [Best Practices](docs/best_practices.md)\n* [Build Performance](docs/perf.md)\n* [Generating CLion Projects](docs/clion.md)\n* [Generating YouCompleteMe/VSCode compile\\_commands.json file](docs/compdb.md)\n* Make-specific documentation: [build/make/README.md](https://android.googlesource.com/platform/build/+/main/README.md)\n\n## Developing for Soong\n\nTo load the code of Soong in IntelliJ:\n\n* File -\u003e Open, open the `build/soong` directory. It will be opened as a new\n  project.\n* File -\u003e Settings, then Languages \u0026 Frameworks -\u003e Go -\u003e GOROOT, then set it to\n  `prebuilts/go/linux-x86`\n* File -\u003e Project Structure, then, Project Settings -\u003e Modules, then Add\n  Content Root, then add the `build/blueprint` directory.\n* Optional: also add the `external/golang-protobuf` directory. In practice,\n  IntelliJ seems to work well enough without this, too.\n\n### Running Soong in a debugger\n\nBoth the Android build driver (`soong_ui`) and Soong proper (`soong_build`) are\nGo applications and can be debugged with the help of the standard Go debugger\ncalled Delve. A client (e.g., IntelliJ IDEA) communicates with Delve via IP port\nthat Delve listens to (the port number is passed to it on invocation).\n\n#### Debugging Android Build Driver ####\nTo make `soong_ui` wait for a debugger connection, use the `SOONG_UI_DELVE`\nvariable:\n\n```\nSOONG_UI_DELVE=5006 m nothing\n```\n\n#### Debugging Soong Proper ####\n\nTo make `soong_build` wait for a debugger connection, install `dlv` and then\nstart the build with `SOONG_DELVE=\u003clisten addr\u003e` in the environment.\nFor example:\n```bash\nSOONG_DELVE=5006 m nothing\n```\nAndroid build driver invokes `soong_build` multiple times, and by default each\ninvocation is run in the debugger. Setting `SOONG_DELVE_STEPS` controls which\ninvocations are run in the debugger, e.g., running\n```bash\nSOONG_DELVE=2345 SOONG_DELVE_STEPS='build,modulegraph' m\n```\nresults in only `build` (main build step) and `modulegraph` being run in the debugger.\nThe allowed step names are `build`, `soong_docs`.\n\nNote setting or unsetting `SOONG_DELVE` causes a recompilation of `soong_build`. This\nis because in order to debug the binary, it needs to be built with debug\nsymbols.\n#### Delve Troubleshooting ####\nTo test the debugger connection, run this command:\n\n```\ndlv connect :5006\n```\n\nIf you see an error:\n```\nCould not attach to pid 593: this could be caused by a kernel\nsecurity setting, try writing \"0\" to /proc/sys/kernel/yama/ptrace_scope\n```\nyou can temporarily disable\n[Yama's ptrace protection](https://www.kernel.org/doc/Documentation/security/Yama.txt)\nusing:\n```bash\nsudo sysctl -w kernel.yama.ptrace_scope=0\n```\n\n#### IntelliJ Setup ####\nTo connect to the process using IntelliJ:\n\n* Run -\u003e Edit Configurations...\n* Choose \"Go Remote\" on the left\n* Click on the \"+\" buttion on the top-left\n* Give it a nice _name_ and set \"Host\" to `localhost` and \"Port\" to the port in the\n  environment variable (`SOONG_UI_DELVE` for `soong_ui`, `SOONG_DELVE` for\n  `soong_build`)\n* Set the breakpoints where you want application to stop\n* Run the build from the command line\n* In IntelliJ, click Run -\u003e Debug _name_\n* Observe _Connecting..._ message in the debugger pane. It changes to\n  _Connected_ once the communication with the debugger has been established; the\n  terminal window where the build started will display\n  `API server listening at ...` message\n\n\nSometimes the `dlv` process hangs on connection. A symptom of this is `dlv`\nspinning a core or two. In that case, `kill -9` `dlv` and try again.\nAnecdotally, it _feels_ like waiting a minute after the start of `soong_build`\nhelps.\n\n## Contact\n\nEmail android-building@googlegroups.com (external) for any questions, or see\n[go/soong](http://go/soong) (internal).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrapheneos%2Fplatform_build_soong","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrapheneos%2Fplatform_build_soong","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrapheneos%2Fplatform_build_soong/lists"}