Contribute SDK packages

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:

1. Prerequisites.
2. Create a package API surface.
3. Explore package contents.
4. Contribute to an API in the SDK.

Prerequisites

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.)

Create a package API surface

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:

• Files inside meta/
• Files in the base package

Explore package contents

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

Contribute to an API in the SDK

To contribute a package to the Fuchsia API surface, follow the guidelines below:

1. 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).

2. 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.

3. Pay attention to the declared API surface, represented by the expected_files_exactand expected_files_present parameters of the sdk_fuchsia_package target.

   (see Create a package API surface.)

4. 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
   

5. Follow the printed instructions for copying the generated content_checklist.json file to its golden file location.

6. 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.

7. 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
   

8. (Optional) Enter the SDK build directory and preview your SDK package manifest.

   From your build directory (for example, out/default), do the following:

   1. Change the directory to sdk/archive, for example:

      cd sdk/archive
      

   2. 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