To integrate your software into the Fuchsia project as prebuilt packages, you need to publish your prebuilt packages to Chrome Infrastructure Package Deployment (CIPD). A prebuilt package is a Fuchsia archive (FAR) file that contains the binaries and metadata of your software.
Once you set up continuous integration (CI) with Fuchsia, whenever you publish new versions of the prebuilt packages to CIPD, Fuchsia’s CI system fetches those new packages and roll them into Fuchsia through the global integration process.
Before you start working on publishing prebuilt packages, you need to know how to build a prebuilt package.
A CIPD package
The main purpose of publishing prebuilt packages to CIPD is for Fuchsia’s CI system to fetch your most recent prebuilt packages from CIPD for global integration.
Both Fuchsia and CIPD have the notion of a package. The differences between a prebuilt package and a CIPD package are:
- A prebuilt package - A Fuchsia archive (FAR) file that contains the binaries and metadata of your software.
- A CIPD package - An archive that contains one or more Fuchsia’s prebuilt packages and other relevant files.
Updating the content of a CIPD package creates a new instance of the CIPD package. Every CIPD package maintains the history of its instances (see Figure 1 below).
Publish your prebuilt packages to CIPD
To publish your prebuilt packages to CIPD, see Publish a CIPD package below.
Additionally, if your CIPD package contains ELF binaries, see Publish a CIPD package with unstripped ELF binaries below.
Publish a CIPD package
Fuchsia has the following requirements for a CIPD package:
Use the following naming convention:
LICENSEfile that contains the legal notices of the software.
Provide a Fuchsia archive (FAR) file per prebuilt package. For example,
Tag each instance with a version identifier in the form of:
Create a ref labeled
latestand point it to the most recent instance of your CIPD package.
Fuchsia developers need to be able to identify which source code is used to generate an instance of the CIPD package based on the version identifier of the instance. Fuchsia recommends that in your project’s documentation you provide instructions on how to obtain an instance’s source code.
When you publish a new instance of your CIPD package,
you need to update the
latest ref so that it now points to the new instance.
Fuchsia’s CI system monitors your package’s
when the CI system detects that the
latest ref is updated,
it fetches the new package and rolls it into Fuchsia.
The following example shows the content of a CIPD package:
LICENSE chromium.far webrunner.far
Publish a CIPD package with unstripped ELF binaries
If your CIPD package contains ELF binaries (executables and shared libraries), you need to publish a CIPD package that contains the unstripped versions of those ELF binaries. The unstripped ELF binaries allow Fuchsia developers to debug your software. For example, the unstripped ELF binaries enable symbolizing stack traces.
Typically the owner of prebuilt packages publishes a sibling CIPD package for the unstripped ELF binaries per architecture, in addition to publishing a CIPD package that contains the prebuilt packages. To allow these CIPD packages to be rolled together, the instances of these CIPD packages must share the same version identifier tag.
Fuchsia requires a CIPD package with unstripped ELF binaries to have the following directory structure:
- An instance of a CIPD package contains a
.tar.bz2file per prebuilt package.
.tar.bz2file, once uncompressed and unpacked, is a
.build-iddirectory has subdirectories and the subdirectories contain unstripped ELF binaries.
- Each subdirectory represents
the first two characters of ELF binaries’
build-id(see the example below).
- Each subdirectory represents the first two characters of ELF binaries’
Fuchsia requires the following requirements for an unstripped ELF binary:
- Use the
debugextension, which indicates that the binary contains DWARF debug information.
- Use the first two characters of the
build-idfor the name of the subdirectory and the rest of the
build-idfor its filename. For example, if
1dbca0bd1be33e19, then its subdirectory name is
1dand its unstripped ELF binary filename is
- Include the following information:
NT_GNU_BUILD_IDnote (obtained by passing the
-build-idflag to the linker).
- Debug information
(obtained by passing the
-gflag to the compiler).
This example shows the directory structure of a CIPD package with unstripped ELF binaries:
chromium.symbols.tar.bz2 1d/ bca0bd1be33e19.debug 2b/ 0e519bcf3942dd.debug 5b/ 66bc85af2da641697328996cbc04d62b84fc58.debug webrunner.symbols.tar.bz2 1f/ 512abdcbe453ee.debug 90dd45623deab1.debug 3d/ aca0b11beff127.debug 5b/ 66bc85af2da641697328996cbc04d62b84fc58.debug
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2019-11-19.