# Publish prebuilt packages to CIPD

This page explains how to integrate your software into the Fuchsia project as a
[prebuilt CIPD package](/docs/development/prebuilt_packages/prebuilt_cipd_packages_in_fuchsia.md).

To publish your prebuilt package to
[CIPD](https://github.com/luci/luci-go/tree/HEAD/cipd){:.external},
see the following guidelines:

*   [Prerequisites](#prerequisites)
*   [Choose a CIPD package path](#choose-a-cipd-package-path)
*   [Set CIPD package versioning](#set-cipd-package-versioning)
*   [Upload a CIPD package](#upload-a-cipd-package)

After publishing your prebuilt package to CIDP,
[update the Fuchsia Jiri manifests](/docs/development/prebuilt_packages/make_your_cipd_package_visible_to_fuchsia_developers.md)
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](/docs/development/source_code/archive_format.md)) to publish your prebuilt
package, see
[Build a package](/docs/development/idk/documentation/packages.md#build-package)
(using FAR).

Note: Provide only one Fuchsia archive (FAR) file per prebuilt package (for example,
`chromium.far`, `webrunner.far`).

If your prebuilt package contains
[ELF](https://en.wikipedia.org/wiki/Executable_and_Linkable_Format){:.external}
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](/docs/development/prebuilt_packages/publish_a_cipd_symbols_package_for_elf_binaries.md)
to support symbolization and debugging.

## Choose a CIPD package path {#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 {#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:

```none
<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:

*   [chromium/fuchsia/webrunner-arm64](https://chrome-infra-packages.appspot.com/p/chromium/fuchsia/webrunner-arm64/+/){: .external}
*   [chromium/fuchsia/castrunner-amd64](https://chrome-infra-packages.appspot.com/p/chromium/fuchsia/castrunner-amd64/+/){: .external}

Note: A prebuilt package contributed by an external project needs to include
either a `LICENSE` file or a `NOTICE` file that contains the legal notices
of the software.

### A CIPD package generated by the Fuchsia project {#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:

    ```none
    <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:

    ```none
    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 {#set-cipd-package-versioning}

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

Note: Fuchsia recommends that your project's documentation provides instructions
on how to obtain the sources that match a given package instance's version
identifier.

### version

To identify the source of prebuilt packages,
[tag](https://github.com/luci/luci-go/tree/HEAD/cipd#tags){: .external} each
revision with a version identifier in the form of:

```none
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:

```none
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 {#upload-a-cipd-package}

Note: Whenever possible, use
[LUCI Recipes](https://github.com/luci/recipes-py){: .external} to build and
upload CIPD packages. This guarantees hermetic and reproducible builds, running
on securely isolated bots. Follow the content of this section only when this is
not possible.

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](https://g3doc.corp.google.com/company/teams/chrome/ops/luci/cipd.md?cl=head#creating-a-new-package){: .external}.

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:

```none
# 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](/docs/development/prebuilt_packages/publish_a_cipd_symbols_package_for_elf_binaries.md)
if your package contains Fuchsia ELF binaries.