Publish prebuilt packages to CIPD

This page explains how to integrate your software into the Fuchsia project as a prebuilt CIPD package.

To publish your prebuilt package to CIPD, see the following guidelines:

After publishing your prebuilt package to CIDP, update the Fuchsia Jiri manifests to ensure that the content of the package is available to Fuchsia's continuous integration (CI) and Fuchsia developers.

Prerequisites

If you plan on using a Fuchsia archive (FAR) to publish your prebuilt package, see Build a package (using FAR).

If your prebuilt package contains ELF binaries (whether inside a FAR or not), they need to be stripped. Additionally, for Fuchsia ELF binaries, you need to generate and upload a companion symbols package to support symbolization and debugging.

Choose a CIPD package path

Each CIPD package has a distinctive path in the CIPD store. The naming convention of this path depends on whether the prebuilts are generated (or maintained) by the Fuchsia project.

A CIPD package contributed by an external project

For a prebuilt CIPD package contributed by an external team or project, use the following CIPD path naming convention:

<PROJECT>/fuchsia/<PACKAGE>-<CIPD_TARGET_ARCHITECTURE>

<CIPD_TARGET_ARCHITECTURE> is a CIPD-compatible CPU architecture name (for instance, amd64 for 64-bit Intel binaries, not x64 or x86_64).

See the following examples:

A CIPD package generated by the Fuchsia project

For prebuilt packages that are generated or maintained by the Fuchsia project, use the following CIPD path naming conventions:

  • Use fuchsia/ as the root project directory for all prebuilt packages.

  • For prebuilts generated from third-party open source projects, use a path under fuchsia/third_party/.

    For example, fuchsia/third_party/ninja/ contains packages for prebuilt binaries of the Ninja build tool, while fuchsia/sdk/core contains packages corresponding to Fuchsia IDK archives generated by the Fuchsia project.

  • For the last directory entry of host prebuilts, use the following convention:

    <CIPD_OS>-<CIPD_HOST_ARCHITECTURE>
    • <CIPD_OS> is a CIPD-compatible OS name.
      • Use linux or mac for <CIPD_OS> (not Linux, osx, darwin or mach).
    • <CIPD_HOST_ARCHITECTURE> a CIPD-compatible CPU architecture name.
      • Use i386, amd64 or arm64 for <CIPD_HOST_ARCHITECTURE> (not x86, x64 or aarch64).

    For example, fuchsia/third_party/clang/mac-amd64 is the path used for the CIPD package that contains the 64-bit Intel OS X Clang toolchain binaries.

  • Fuchsia ELF prebuilts need to use a path that ends with the following:

    arch/<ARCH>

    • <ARCH> is a Fuchsia-compatible CPU architecture name.

      • Use x64 or arm64 (not amd64, x86_64 or aarch64).

    In the case of 64-bit Intel binaries, amd64 is only used for host prebuilts while x64 is only used for Fuchsia ELF prebuilts.

    For example, fuchsia/third_party/swiftshader/arch/x64 is the path used for the SwiftShader-based Vulkan ICD/driver that is built for Fuchsia.

Set CIPD package versioning

Fuchsia developers need to be able to identify which source code is used to generate each CIPD package instance.

version

To identify the source of prebuilt packages, tag each revision with a version identifier in the form of:

version:<VERSION_ID_OF_INSTANCE>

For example, version:77.0.3835.0 and version:176326.

git_revision

In addition to specifying version, if available (for example, building third-party open source projects), include a Git commit hash:

git_revision:<GIT_COMMIT_HASH>

This git_revision tag identifies the exact Git commit of the source tree used to build the binaries.

If several revisions are built from the same Git commit hash (for example, the first instance was mistakenly built in debug, instead of release mode), you can use a suffix separated with a dash (-), as in git_revision:<GIT_COMMIT_HASH>-2, for the new revision's tag.

Upload a CIPD package

Manually uploading a new CIPD package revision requires you to be authentified with cipd auth-login, then run the cipd create command. Example instructions are available from this CIPD page.

Using a cipd.yaml file is strongly recommended. A good practice is to auto-generate this file from your rebuild script and include uploading instructions in a comment, as shown in the following pseudo-example:

# This file was auto-generated by build-project-fuchsia-package.sh
# For more information, see http://myproject.url/docs/fuchsia/
#
# To upload the files in this CIPD package do:
#
#   TAG=git_revision:cd13435a975057b0ad0b72636f6c8323113c9c8b
#   VERSION=version:22.0.773.345
#   cipd create -pkg-defs cipd.yaml -tag $TAG -tag $VERSION
#
package: myproject/fuchsia/mypackage-arm64
description: mypackage's Fuchsia binaries from myproject.
data:
  - file: LICENSE # or NOTICE(.txt)
  - file: mypackage.far

Don't forget to also upload a companion symbols package if your package contains Fuchsia ELF binaries.