gogenlicense

README

gogenlicense

gogenlicense finds and formats package licenses for use in go programs. It is intended to comply with license requirements, but has not been vetted by a lawyer.

Concretely this package generates go code that contains a single string variable which includes all legal notices. It also generates appropriate comments for godoc.

Quickstart

Install the command using standard go tools:

go install github.com/tkw1536/gogenlicense/cmd/gogenlicense@latest

gogenlicense is most commonly invoked using a 'go:generate' comment like so:

//go:generate gogenlicense -m

After adding such a comment, run the go generate command.

Once a source file has been generated, your go code can make use of the generated notices. For example to add a legal flag that prints notices:

var legalFlag bool
flag.BoolVar(&legalFlag, "legal", legalFlag, "print legal notices and exit")
defer func() {
	if legalFlag {
		fmt.Println("This executable contains code from several different go packages. ")
		fmt.Println("Some of these packages require licensing information to be made available to the end user. ")
		fmt.Println(legal.Notices) // this references the generated constant!
		os.Exit(0)
	}
}()

For a more complete example, see the source code of the gogenlicense command. The notices constant is implemented in the github.com/tkw1536/gogenlicense/legal subpackage. The legal flag is implemented in the main package.

Usage

gogenlicense [-legal] [-help] [-o FILE] [-t THRESHOLD] [-p PACKAGE] [-n NAME] [-m] [MODULE [MODULE...]]
-legal
  Print legal notices and exit.
-help
  Print a usage message and exit.
-p PACKAGE
  Package name of go source code file to generate.
  Defaults to the 'GOPACKAGE' environment variable, or to 'notices' if unset.
-n string
  Name of declaration to generate (default 'Notices')
-t THRESHOLD
 Threshold to use for the license classifier, between 0 and 1.
 Defaults to 0.9.
-o filename
  Path to write output to.
  Defaults to appending a suffix '_notices' to the source file pointed to by the 'GOFILE' environment variable.
  If 'GOFILE' is not provided, uses the filename 'notices.go'.
MODULE
  Import path of module to scan for module dependencies.
-m
  automatically find the current 'go module' containing the working directory and include it in MODULE list.

Acknowledgements

This package was inspired by the https://classic.yarnpkg.com/lang/en/docs/cli/licenses/#toc-yarn-licenses-generate-disclaimer command. Internally the command relies on the excellent https://github.com/google/go-licenses package. See also the legal subpackage for full licenses of used packages.

Changelog

Version 1.2.7 (Released Apr 22 2024)

• use a constant declaration instead of a variable one
• update dependencies

Version 1.2.6 (Released Aug 19 2023)

• add 'DO NOT EDIT' comment to template
• update spellchecker template
• update to go 1.20

Version 1.2.5 (Released Aug 8 2023)

• add 'spellchecker:disable' comment to template
• fix typos in documentation
• update dependencies

Version 1.2.4 (Released Aug 15 2022)

• properly handle repositories in or under $GOROOT

Version 1.2.3 (Released Aug 15 2022)

• fix typo in error message

Version 1.2.2 (Released Apr 28 2022)

• minor dependency updates

Version 1.2.1 (Released Nov 18 2021)

• Bugfix: Fix using correct templates for godoc and value string

Version 1.2.0 (Released Nov 18 2021)

• Add lots of documentation.
• Add an '-m' flag to automatically use the current go.module
• Use '$GOPACKAGE' and '$GOFILE' as default parameters
• Update go to 1.17
• various internal improvements

Version 1.1.0 (Released Feb 21 2021)

• Bugfix: Do not include modules with '.go' in the license file name

Version 1.0.0 (Released Dec 8 2020)

• Initial release

Documentation

Overview

Package gogenlicense implements the gogenlicense command. See github.com/tkw1536/gogenlicense/cmd/gogenlicense.

Index

• func FindModulePath(path string) (pkg string, err error)
• func FindModuleRoot(path string) (root string, err error)
• func Format(ctx context.Context, options Options) (res string, err error)
• type Library
• type Options

Examples

• FindModulePath

Functions

func FindModulePath

func FindModulePath(path string) (pkg string, err error)

FindModulePath finds the package path to the module containing path. This works by finding the path to 'go.mod', starting recursively at path.

Returns the package import path, if any. if no package import path exists, returns an error

Example

// get the current directory - module containing this example
dir, err := os.Getwd()
if err != nil {
	panic(err)
}

// find the import path to the module
module, err := FindModulePath(dir)
if err != nil {
	panic(err)
}
fmt.Println(module)

Output:

github.com/tkw1536/gogenlicense

func FindModuleRoot

func FindModuleRoot(path string) (root string, err error)

FindModuleRoot finds the directory containing the module at path. This works by finding a directory containing 'go.mod', starting recursively at path.

Returns the path to a directory containing 'go.mod'. If no 'go.mod' file exists, returns an error.

func Format

func Format(ctx context.Context, options Options) (res string, err error)

Format formats licenses according to options

Types

type Library

type Library struct {
	Path  string
	Title string // like path, but with "Module" prefix

	LicenseName string
	LicenseText string
	LibraryURL  string
}

Library is an internal representation of a library

type Options

type Options struct {
	// ModulePaths are go import paths to generate license information for.
	ModulePaths []string

	// By default the root modules are not used.
	// When set to true, include them.
	IncludeRoots bool

	// ConfidenceThreshold is the confidence threshold for the license classifier.
	// The default is 0.9.
	ConfidenceThreshold float64

	// Name of the package to output
	OutPackage string

	// Name of the declaration
	DeclarationName string
}

Options are options for the Format function.