Branch	Status
main
dev

Table of Contents

• Overview
• Schema
• Using build-info-go as a CLI
  • Build the CLI from Sources
  • Generating Build-Info
  • Logs
• Go APIs
  • Creating a New Build
  • Generating Build-Info
  • Collecting Environment Variables
  • Get the Complete Build-Info
  • Clean the Build Cache
• Tests

Overview

build-info-go is a Go library, which allows generating build-info for a source code project. The library is also packaged as a CLI. Read more about build-info at buildinfo.org.

Schema

The build-info schema is available here.

Using build-info-go as a CLI

Download the CLI executable

	Linux	386	amd64	arm	arm64	s390x	ppc64	ppc64le

	Mac	386	arm64

	Windows	amd64

Build the CLI from Sources

Make sure Go is installed by running:

go version

Clone the sources and CD to the root directory of the project:

git clone https://github.com/jfrog/build-info-go
cd build-info-go

Build the sources as follows:

On Unix based systems run:

./buildscripts/build.sh

On Windows run:

.\buildscripts\build.bat

Once completed, you'll find the bi executable at the current directory.

Generating Build-Info Using the CLI

The Build-Info CLI allows generating build-info for your project easily and quickly.

All you need to do is to navigate to the project's root directory and run one of the following commands (depending on the package manager you use). The complete build-info will be sent to the stdout.

Go

bi go

Maven

bi mvn

Gradle

bi gradle

npm

bi npm [npm command] [command options]

Note: checksums calculation is not yet supported for npm projects.

Yarn

bi yarn [Yarn command] [command options]

Note: checksums calculation is not yet supported for Yarn projects.

pip

bi pip [pip command] [command options]

Note: checksums calculation is not yet supported for pip projects.

pipenv

bi pipenv [pipenv command] [command options]

Note: checksums calculation is not yet supported for pipenv projects.

twine

bi twine [twine command] [command options]

Dotnet

bi dotnet [Dotnet command] [command options]

Nuget

bi nuget [Nuget command] [command options]

Conversion to CycloneDX

You can generate build-info and have it converted into the CycloneDX format by adding to the command --format cyclonedx/xml or --format cyclonedx/json.

Logs

The default log level of the Build-Info CLI is INFO.

You can change the log level by setting the BUILD_INFO_LOG_LEVEL environment variable to either DEBUG, INFO, WARN or ERROR.

All log messages are sent to the stderr, to allow picking up the generated build-info, which is sent to the stdout.

Go APIs

Collecting and building build-info for your project is easier than ever using the BuildInfoService:

Creating a New Build

To use the APIs below, you need to create a new instance of BuildInfoService and then create a new Build (or get an existing one):

service := build.NewBuildInfoService()
bld, err := service.GetOrCreateBuild(buildName, buildNumber)

It's important to invoke this function at the very beginning of the build, so that the start time property in the build-info will be accurate.

Generating Build-Info

After you created a Build, you can create a new build-info module for your specific project type and collect its dependencies:

Go

// You can pass an empty string as an argument, if the root of the Go project is the working directory.
goModule, err := bld.AddGoModule(goProjectPath)
// Calculate the dependencies used by this module, and store them in the module struct.
err = goModule.CalcDependencies()

// You can also add artifacts to that module.
artifact1 := entities.Artifact{Name: "v1.0.0.mod", Type: "mod", Checksum: &entities.Checksum{Sha1: "123", Md5: "456", Sha256: "789"}}
err = goModule.AddArtifacts(artifact1, artifact2, ...)

Maven

// You can pass an empty string as an argument, if the root of the Maven project is the working directory.
mavenModule, err := bld.AddMavenModule(mavenProjectPath)
// Calculate the dependencies used by this module, and store them in the module struct.
err = mavenModule.CalcDependencies()

Gradle

// You can pass an empty string as an argument, if the root of the Gradle project is the working directory.
gradleModule, err := bld.AddGradleModule(gradleProjectPath)
// Calculate the dependencies used by this module, and store them in the module struct.
err = gradleModule.CalcDependencies()

npm

// You can pass an empty string as an argument, if the root of the npm project is the working directory.
npmModule, err := bld.AddNpmModule(npmProjectPath)
// Checksum calculation is not supported for npm projects, so you can add a function that calculates them.
npmModule.SetTraverseDependenciesFunc(func (dependency *entities.Dependency) (bool, error) {
dependency.Checksum = &entities.Checksum{Sha1: "123"}
return true, nil
})
// Calculate the dependencies used by this module, and store them in the module struct.
err = npmModule.CalcDependencies()

// You can also add artifacts to that module.
artifact1 := entities.Artifact{Name: "json", Type: "tgz", Checksum: &entities.Checksum{Sha1: "123", Md5: "456"}}
err = npmModule.AddArtifacts(artifact1, artifact2, ...)

Yarn

// You can pass an empty string as an argument, if the root of the Yarn project is the working directory.
yarnModule, err := bld.AddYarnModule(npmProjectPath)
// Checksum calculation is not supported for Yarn projects, so you can add a function that calculates them.
yarnModule.SetTraverseDependenciesFunc(func (dependency *entities.Dependency) (bool, error) {
dependency.Checksum = &entities.Checksum{Sha1: "123"}
return true, nil
})
// By default, your project will be built with the 'yarn install' command. If you want, you can set another command.
yarnModule.SetArgs([]string{"install", "--json"})
// Build the project, calculate the dependencies used by it and store them in the module struct.
err = yarnModule.Build()

// You can also add artifacts to that module.
artifact1 := entities.Artifact{Name: "json", Type: "tgz", Checksum: &entities.Checksum{Sha1: "123", Md5: "456"}}
err = yarnModule.AddArtifacts(artifact1, artifact2, ...)

Dotnet

// You can pass an empty string as an argument, if the root of the Dotnet project is the working directory.
dotnetModule, err := bld.AddDotnetModules(nugetProjectPath)
// Calculate the dependencies used by this module, and store them in the module struct.
err = dotnetModule.CalcDependencies()

Nuget

// You can pass an empty string as an argument, if the root of the Nuget project is the working directory.
nugetModule, err := bld.AddNugetModules(nugetProjectPath)
// Calculate the dependencies used by this module, and store them in the module struct.
err = nugetModule.CalcDependencies()

Collecting Environment Variables

Using CollectEnv() you can collect environment variables and attach them to the build.

After calling ToBuildInfo() (see below), you can also filter the environment variables using the IncludeEnv() and ExcludeEnv() methods of BuildInfo.

err := bld.CollectEnv()
buildInfo, err := bld.ToBuildInfo()
err = buildInfo.IncludeEnv("ENV_VAR", "JFROG_CLI_*")
err = buildInfo.ExcludeEnv("*password*", "*secret*", "*token*")

Get the Complete Build-Info

Using the ToBuildInfo() method you can create a complete BuildInfo struct with all the information collected:

buildInfo, err := bld.ToBuildInfo()
err = bld.Clean()

Clean the Build Cache

The process of generating build-info uses the local file system as a caching layer. This allows using this library by multiple processes.

If you finished working on a certain Build and you want to delete it from the cache, all you need to do is to call this function:

err := bld.Clean()

Tests

To run the tests, execute the following command from within the root directory of the project:

go test -v ./...