platform_build_soong/starlark_import/README.md

# starlark_import package

This allows soong to read constant information from starlark files. At package initialization
time, soong will read `build/bazel/constants_exported_to_soong.bzl`, and then make the
variables from that file available via `starlark_import.GetStarlarkValue()`. So to import
a new variable, it must be added to `constants_exported_to_soong.bzl` and then it can
be accessed by name.

Only constant information can be read, since this is not a full bazel execution but a
standalone starlark interpreter. This means you can't use bazel contructs like `rule`,
`provider`, `select`, `glob`, etc.

All starlark files that were loaded must be added as ninja deps that cause soong to rerun.
The loaded files can be retrieved via `starlark_import.GetNinjaDeps()`.
Load starlark files from soong There are a number of instances where we are exporting information from soong to bazel via soong_injection. This could be more bazel-centric if the information was instead held in bzl files, and both bazel and soong read it from there. Add a starlark package that will run //build/bazel/constants_exported_to_soong.bzl at initialization time, and then results can be retreived with GetStarlarkValue. Since changes to the starlark files mean that soong has to rerun, add them as ninja deps. Unfortunately, the starlark code has to be run at runtime rather than pregenerating their results, because tests run from intellij wouldn't go through any pregeneration steps. This means that starlark is run multiple times during the build, once per test package and once per primary builder invocation. (currently 3, could be reduced to 2 if we made the symlink forest generation into its own standalone tool) The starlark code we have so far in this cl is very fast, roughly half a millisecond, so it's not a big deal for now, but something to keep an eye on as we add more starlark constants. Bug: 279095899 Test: go test Change-Id: I1e7ca1df1d8d67333cbfc46e8396e229820e4476 2023-02-07 20:38:27 +01:00			`# starlark_import package`

			`This allows soong to read constant information from starlark files. At package initialization`
			time, soong will read `build/bazel/constants_exported_to_soong.bzl`, and then make the
			variables from that file available via `starlark_import.GetStarlarkValue()`. So to import
			a new variable, it must be added to `constants_exported_to_soong.bzl` and then it can
			`be accessed by name.`

			`Only constant information can be read, since this is not a full bazel execution but a`
			standalone starlark interpreter. This means you can't use bazel contructs like `rule`,
			`provider`, `select`, `glob`, etc.

			`All starlark files that were loaded must be added as ninja deps that cause soong to rerun.`
			The loaded files can be retrieved via `starlark_import.GetNinjaDeps()`.