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