This page serves as a playbook for contributing Fuchsia packages (from here on simply “packages”) to the Fuchsia API surface and the Fuchsia IDK.
The steps are:
For a package to be included in the Fuchsia SDK, the package must be created in the category of partner
or public
. (For more information, see Promoting an API to the partner category.)
The package API surface is created by populating two parameters in the sdk_fuchsia_package()
target: expected_files_present
and expected_files_exact
.
You can use these two parameters to enforce the following:
expected_files_present
: A package file is present in the SDK package's manifest.expected_files_exact
: A package file is present in the SDK package's manifest and its content hash matches the content hash checked in source.A package file can consist of any items in the package's contents, which include:
meta/
Note: For components, it‘s recommended to track the output component manifest (that is, meta/<component_name>.cm
) at the expected_files_exact
level for an API surface. This ensures that anything that changes the package’s functionality (which in turn changes its component manifest content hash) will be surfaced.
Provide a list of the items that make up a package in the package's manifest file (commonly named package_manifest.json
)
See an example manifest file below:
{ "version": "1", "repository": "fuchsia.com", "package": { "name": "example_package", "version": "0" }, "blobs": [ { "source_path": "path/to/meta.far", "path": "meta/", "merkle": "CONTENT_HASH", "size": 0 }, { "source_path": "path/to/bin/example", "path": "bin/example", "merkle": "CONTENT_HASH", "size": 0 }, { "source_path": "path/to/shared/bar.so", "path": "lib/bar.so", "merkle": "CONTENT_HASH", "size": 0 } ] }
In the example above, possible API surface items (besides the meta.far
) are in the blobs/path
entities, which include:
bin/example
lib/far.so
The ffx package far list
command allows you to explore the contents of the meta.far
, for example:
$ ffx package far list path/to/meta.far +-------------------------------+ | path | +===============================+ | meta/contents | +-------------------------------+ | meta/fuchsia.abi/abi-revision | +-------------------------------+ | meta/component_name.cm | +-------------------------------+
In total, the possible API surface items (including meta.far
) from this example now include:
bin/example
lib/far.so
meta/contents
meta/fuchsia.abi/abi-revision
meta/component_name.cm
Tip: See this example Gerrit change for the steps described in this section.
To contribute a package to the Fuchsia API surface, follow the guidelines below:
Prepare to request a code review from an API council member.
This member may ask for adjustments to your API surface (see this example code review of an SDK package).
Create a sdk_fuchsia_package
target for your SDK package (example).
This will likely live next to the fuchsia_package
target that is being exported.
Pay attention to the declared API surface, represented by the expected_files_exact
and expected_files_present
parameters of the sdk_fuchsia_package
target.
(see Create a package API surface.)
Add the sdk_fuchsia_package
target to the dependencies of the sdk_molecule
(“core_packages”) target in the //sdk/BUILD.gn
file (example).
To build the IDK target (which is expected to fail its golden file check), run the following command:
fx build final_fuchsia_idk
Follow the printed instructions for copying the generated content_checklist.json
file to its golden file location.
Confirm that the generated content_checklist.json
file covers the desired API surface (example).
If not, adjust the expected_files_exact
and expected_files_present
parameters and repeat the previous build step.
Build the IDK target after fixing any other SDK manifest-related changes (including updating the //sdk/manifests/fuchsia_idk.manifest
files).
fx build final_fuchsia_idk
(Optional) Enter the SDK build directory and preview your SDK package manifest.
From your build directory (for example, out/default
), do the following:
Change the directory to sdk/archive
, for example:
cd sdk/archive
Run the following command:
mkdir output && tar zxvf fuchsia_idk.tar.gz -C output && cd output
The package manifest of your package targeting x64 will be found at packages/{PACKAGE_DISTRIBUTION_NAME}/x64/release/package_manifest.json