/bazel-distribution

Bazel rules for assembling and deploying software distributions (see @vaticle for usage example)

Primary LanguageStarlarkApache License 2.0Apache-2.0

assemble_crate

assemble_crate(name, authors, categories, description, documentation, homepage, keywords, license,
               readme_file, repository, target, version_file)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
authors Project authors List of strings optional []
categories Project categories List of strings optional []
description The description is a short blurb about the package. crates.io will display this with your package. This should be plain text (not Markdown). https://doc.rust-lang.org/cargo/reference/manifest.html#the-description-field String required
documentation Link to documentation of the project String optional ""
homepage Link to homepage of the project String required
keywords The keywords field is an array of strings that describe this package. This can help when searching for the package on a registry, and you may choose any words that would help someone find this crate.

Note: crates.io has a maximum of 5 keywords. Each keyword must be ASCII text, start with a letter, and only contain letters, numbers, _ or -, and have at most 20 characters.

https://doc.rust-lang.org/cargo/reference/manifest.html#the-keywords-field
List of strings optional []
license The license field contains the name of the software license that the package is released under. https://doc.rust-lang.org/cargo/reference/manifest.html#the-license-and-license-file-fields String required
readme_file README of the project Label optional None
repository Repository of the project String required
target rust_library label to be included in the package Label required
version_file File containing version string. Alternatively, pass --define version=VERSION to Bazel invocation. Not specifying version at all defaults to '0.0.0' Label optional None

assemble_maven

assemble_maven(name, license, project_description, project_name, project_url, scm_url, target,
               version_file, version_overrides, workspace_refs)

Assemble Java package for subsequent deployment to Maven repo

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
license Project license to fill into pom.xml String optional "apache"
project_description Project description to fill into pom.xml String optional "PROJECT_DESCRIPTION"
project_name Project name to fill into pom.xml String optional "PROJECT_NAME"
project_url Project URL to fill into pom.xml String optional "PROJECT_URL"
scm_url Project source control URL to fill into pom.xml String optional "PROJECT_URL"
target Java target for subsequent deployment Label required
version_file File containing version string. Alternatively, pass --define version=VERSION to Bazel invocation. Not specifying version at all defaults to '0.0.0' Label optional None
version_overrides Dictionary of maven artifact : version to pin artifact versions to Dictionary: String -> String optional {}
workspace_refs JSON file describing dependencies to other Bazel workspaces Label optional None

assemble_npm

assemble_npm(name, target, version_file)

Assemble npm_package target for further deployment. Currently does not support remote execution (RBE).

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
target npm_library label to be included in the package Label required
version_file File containing version string. Alternatively, pass --define version=VERSION to Bazel invocation. Not specifying version at all defaults to '0.0.0' Label optional None

assemble_pip

assemble_pip(name, author, author_email, classifiers, description, keywords, license,
             long_description_file, package_name, requirements_file, target, url, version_file)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
author Details about the author String required
author_email The email for the author String required
classifiers A list of strings, containing Python package classifiers List of strings required
description A string with the short description of the package String required
keywords A list of strings, containing keywords List of strings required
license The type of license to use String required
long_description_file A label with the long description of the package. Usually a README or README.rst file Label required
package_name A string with Python pip package name String required
requirements_file A file with the list of required packages for this one Label required
target py_library label to be included in the package Label required
url A homepage for the project String required
version_file File containing version string. Alternatively, pass --define version=VERSION to Bazel invocation. Not specifying version at all defaults to '0.0.0' Label optional None

assemble_versioned

assemble_versioned(name, targets, version_file)

Version multiple archives for subsequent simultaneous deployment

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
targets Archives to version and put into output archive List of labels optional []
version_file File containing version string Label optional None

checksum

checksum(name, archive)

Computes SHA256 checksum of file

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
archive Archive to compute checksum of Label required

deploy_apt

deploy_apt(name, release, snapshot, target)

Deploy package built with assemble_apt to APT repository

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
release Release repository to deploy apt artifact to String required
snapshot Snapshot repository to deploy apt artifact to String required
target assemble_apt label to deploy Label optional None

deploy_brew

deploy_brew(name, checksum, formula, release, snapshot, type, version_file)

Deploy Homebrew (Caskroom) formula to Homebrew tap

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
checksum Checksum of deployed artifact Label optional None
formula The brew formula definition Label required
release Release repository to deploy brew artifact to String required
snapshot Snapshot repository to deploy brew artifact to String required
type Type of deployment (Homebrew/Caskroom). Cask is generally used for graphic applications String optional "brew"
version_file File containing version string. Alternatively, pass --define version=VERSION to Bazel invocation. Not specifying version at all defaults to '0.0.0' Label optional None

deploy_crate

deploy_crate(name, release, snapshot, target)

Deploy assemble_crate target into Crate repo

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
release Release repository to release Crate artifact to String required
snapshot Snapshot repository to release Crate artifact to String required
target assemble_crate target to deploy Label required

deploy_github

deploy_github(name, archive, draft, organisation, release_description, repository, title,
              title_append_version, version_file)

Deploy assemble_versioned target to GitHub Releases

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
archive assemble_versioned label to be deployed. Label optional None
draft Creates an unpublished / draft release when set to True. Defaults to True. Boolean optional True
organisation Github organisation to deploy to String required
release_description Description of GitHub release Label optional None
repository Github repository to deploy to within organisation String required
title Title of GitHub release String optional ""
title_append_version Append version to GitHub release title Boolean optional False
version_file File containing version string. Alternatively, pass --define version=VERSION to Bazel invocation. Not specifying version at all defaults to '0.0.0' Label optional None

deploy_maven

deploy_maven(name, release, snapshot, target)

Deploy assemble_maven target into Maven repo

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
release Release repository to release maven artifact to String required
snapshot Snapshot repository to release maven artifact to String required
target assemble_maven target to deploy Label required

deploy_npm

deploy_npm(name, release, snapshot, target)
Deploy `assemble_npm` target into npm registry using token authentication

## How to generate an auth token

### On `npmjs.com`
1. Sign in to the user account at https://npmjs.com that is used in your CI and has permissions to publish the package
2. Navigate to the account's "Access Tokens", generate a new one and store it somewhere safe

### On `repo.vaticle.com`, or any other `npm` repository
1. Run `npm adduser <repo_url>` (example: `npm adduser --registry=https://repo.vaticle.com/repository/npm-private`)
2. When prompted, provide login credentials to sign in to the user account that is used in your CI and has permissions to publish the package
3. If successful, a line will be added to your `.npmrc` file (`$HOME/.npmrc` on Unix) which looks like: `//repo.vaticle.com/repository/npm-snapshot/:_authToken=NpmToken.00000000-0000-0000-0000-000000000000`. The token is the value of `_authToken`, in this case `NpmToken.00000000-0000-0000-0000-000000000000`.
4. Save the auth token somewhere safe and then delete it from your `.npmrc` file

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
release Release repository to deploy npm artifact to String required
snapshot Snapshot repository to deploy npm artifact to String required
target assemble_npm target to be included in the package Label required

deploy_packer

deploy_packer(name, overwrite, target)

Execute Packer to perform deployment

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
overwrite Overwrite already-existing image Boolean optional False
target assemble_packer label to be deployed. Label optional None

deploy_pip

deploy_pip(name, release, snapshot, target)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
release Remote repository to deploy pip release to String required
snapshot Remote repository to deploy pip snapshot to String required
target assemble_pip label to be included in the package Label required

deploy_rpm

deploy_rpm(name, release, snapshot, target)

Deploy package built with assemble_rpm to RPM repository

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
release Remote repository to deploy rpm release to String required
snapshot Remote repository to deploy rpm snapshot to String required
target assemble_rpm target to deploy Label optional None

generate_json_config

generate_json_config(name, substitutions, template)

Fills in JSON template with provided values

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
substitutions Values to fill in Dictionary: String -> String optional {}
template JSON template to fill in values Label optional None

java_deps

java_deps(name, java_deps_root, java_deps_root_overrides, maven_name, target, version_file)

Packs Java library alongside with its dependencies into archive

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
java_deps_root Folder inside archive to put JARs into String optional ""
java_deps_root_overrides JARs with filenames matching the given patterns will be placed into the specified folders inside the archive, instead of the default folder. Patterns can be either the full name of a JAR, or a prefix followed by a '*'. Dictionary: String -> String optional {}
maven_name Name JAR files inside archive based on Maven coordinates Boolean optional False
target Java target to pack into archive Label required
version_file File containing version string. Alternatively, pass --define version=VERSION to Bazel invocation. Not specifying version at all defaults to '0.0.0' Label optional None

tgz2zip

tgz2zip(name, output_filename, tgz)

Converts .tar.gz into .zip

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
output_filename Resulting filename String required
tgz Input .tar.gz archive Label required

JarToMavenCoordinatesMapping

JarToMavenCoordinatesMapping(filename, maven_coordinates)

FIELDS

Name Description
filename jar filename
maven_coordinates Maven coordinates of the jar

MavenDeploymentInfo

MavenDeploymentInfo(jar, srcjar, pom)

FIELDS

Name Description
jar JAR file to deploy
srcjar JAR file with sources
pom Accompanying pom.xml file

TransitiveJarToMavenCoordinatesMapping

TransitiveJarToMavenCoordinatesMapping(mapping)

FIELDS

Name Description
mapping maps jar filename to coordinates

assemble_apt

assemble_apt(name, package_name, maintainer, description, version_file, installation_dir,
             workspace_refs, archives, empty_dirs, files, depends, symlinks, permissions)

Assemble package for installation with APT

PARAMETERS

Name Description Default Value
name A unique name for this target. none
package_name Package name for built .deb package https://www.debian.org/doc/debian-policy/ch-controlfields#package none
maintainer The package maintainer's name and email address. The name must come first, then the email address inside angle brackets <> (in RFC822 format) none
description description of the built package https://www.debian.org/doc/debian-policy/ch-controlfields#description none
version_file File containing version number of a package. Alternatively, pass --define version=VERSION to Bazel invocation. Specifying commit SHA will result in prepending '0.0.0' to it to comply with Debian rules. Not specifying version at all defaults to '0.0.0' https://www.debian.org/doc/debian-policy/ch-controlfields#version None
installation_dir directory into which .deb package is unpacked at installation None
workspace_refs JSON file with other Bazel workspace references None
archives Bazel labels of archives that go into .deb package []
empty_dirs list of empty directories created at package installation []
files mapping between Bazel labels of archives that go into .deb package and their resulting location on .deb package installation {}
depends list of Debian packages this package depends on https://www.debian.org/doc/debian-policy/ch-relationships.htm []
symlinks mapping between source and target of symbolic links created at installation {}
permissions mapping between paths and UNIX permissions {}

assemble_aws

assemble_aws(name, ami_name, install, region, files)

Assemble files for AWS deployment

PARAMETERS

Name Description Default Value
name A unique name for this target. none
ami_name AMI name of deployed image none
install Bazel label for install file none
region AWS region to deploy image to none
files Files to include into AWS deployment none

assemble_azure

assemble_azure(name, image_name, resource_group_name, install, image_publisher, image_offer,
               image_sku, disk_size_gb, files)

Assemble files for Azure deployment

PARAMETERS

Name Description Default Value
name A unique name for this target. none
image_name name of deployed image none
resource_group_name name of the resource group to place image in none
install Bazel label for install file none
image_publisher Publisher of the image used as base "Canonical"
image_offer Offer of the image used as base "0001-com-ubuntu-server-focal"
image_sku SKU of the image used as base "20_04-lts"
disk_size_gb Size of the resulting OS disk 60
files Files to include into Azure deployment None

assemble_gcp

assemble_gcp(name, project_id, install, zone, image_name, image_family, files, image_licenses,
             disable_default_service_account, source_image_family)

Assemble files for GCP deployment

PARAMETERS

Name Description Default Value
name A unique name for this target. none
project_id Google project id none
install Bazel label for install file none
zone GCP zone to deploy image to none
image_name name of deployed image none
image_family family of deployed image ""
files Files to include into GCP deployment None
image_licenses licenses to attach to deployed image None
disable_default_service_account disable default service account False
source_image_family Family of GCP base image "ubuntu-1604-lts"

assemble_packer

assemble_packer(name, config, files)

Assemble files for HashiCorp Packer deployment

PARAMETERS

Name Description Default Value
name A unique name for this target. none
config Packer JSON config none
files Files to include into deployment {}

assemble_rpm

assemble_rpm(name, package_name, spec_file, version_file, workspace_refs, installation_dir,
             archives, empty_dirs, files, permissions, symlinks, tags)

Assemble package for installation with RPM

PARAMETERS

Name Description Default Value
name A unique name for this target. none
package_name Package name for built .rpm package none
spec_file The RPM spec file to use none
version_file File containing version number of a package. Alternatively, pass --define version=VERSION to Bazel invocation. Not specifying version defaults to '0.0.0' None
workspace_refs JSON file with other Bazel workspace references None
installation_dir directory into which .rpm package is unpacked at installation None
archives Bazel labels of archives that go into .rpm package []
empty_dirs list of empty directories created at package installation []
files mapping between Bazel labels of archives that go into .rpm package and their resulting location on .rpm package installation {}
permissions mapping between paths and UNIX permissions {}
symlinks mapping between source and target of symbolic links created at installation {}
tags additional tags passed to all wrapped rules []

assemble_targz

assemble_targz(name, output_filename, targets, additional_files, empty_directories, permissions,
               append_version, visibility, tags)

Assemble distribution archive (.tar.gz)

PARAMETERS

Name Description Default Value
name A unique name for this target. none
output_filename filename of resulting archive None
targets Bazel labels of archives that go into .tar.gz package []
additional_files mapping between Bazel labels of files that go into archive and their resulting location in archive {}
empty_directories list of empty directories created at archive installation []
permissions mapping between paths and UNIX permissions {}
append_version append version to root folder inside the archive True
visibility controls whether the target can be used by other packages ["//visibility:private"]
tags

-

[]

assemble_zip

assemble_zip(name, output_filename, targets, additional_files, empty_directories, permissions,
             append_version, visibility, tags)

Assemble distribution archive (.zip)

PARAMETERS

Name Description Default Value
name A unique name for this target. none
output_filename filename of resulting archive none
targets Bazel labels of archives that go into .tar.gz package []
additional_files mapping between Bazel labels of files that go into archive and their resulting location in archive {}
empty_directories list of empty directories created at archive installation []
permissions mapping between paths and UNIX permissions {}
append_version append version to root folder inside the archive True
visibility controls whether the target can be used by other packages ["//visibility:private"]
tags

-

[]