mingo

README

Mingo - compute the minimum usable version of Go

This is mingo, a library and command-line tool for analyzing Go code to determine the minimum version of Go necessary to compile it.

Installation

For the command-line tool:

go install github.com/bobg/mingo/cmd/mingo@latest

For the library:

go get github.com/bobg/mingo@latest

Usage

For library usage please see the package doc.

Command-line usage:

mingo [-v] [-deps (all|direct|none)] [-tests] [-check] [-api API] [DIR]

This command runs mingo on the Go module in the given directory DIR (the current directory by default).

The flags and their meanings are:

flag	meaning
-v	Run verbosely
-deps	Dependencies to include - all (the default), direct only, or none
-tests	Include tests
-check	Check that the module declares the right version of Go
-api API	Find the Go API files in the directory API instead of the default $GOROOT/api

Normal output is the lowest minor version of Go (the x in Go 1.x) that is safe to declare in the go directive of the module’s go.mod file.

Running with -check causes mingo to exit with a 0 status code and no output if the module declares the correct version of Go, or a non-zero status and an error message otherwise.

Including dependencies with -deps all (the default) allows go directives in imported modules’ go.mod files to change the result. This includes both direct and indirect imports. Use -deps direct to consider direct imports only, and -deps none to exclude imports.

Discussion

What version of Go should you declare in your go.mod file?

For maximum compatibility it should be the oldest version of Go that can compile your code.

For example, if your code uses a for range statement that does not include a variable assignment, you need at least Go 1.4, which first introduced variable-free for range statements. And if you use the context package from the standard library, you need at least Go 1.7. On the other hand if you use the function context.Cause that requirement bumps up to Go 1.20.

One thing you should not do is to routinely increase the version in your go.mod when a new version of Go comes out. When you do you risk breaking compatibility for some of your callers.

Practically speaking there’s no point declaring a version of Go earlier than 1.11 in your go.mod, since that’s the first version that understood go.mod files. But mingo will still report earlier version numbers when warranted (somewhat pedantically).

How this works

Mingo is a good illustration of how to write a static analysis tool in and for Go. See Tour.md for an in-depth discussion of how the code works.

Documentation

Overview

Package mingo contains logic for scanning the packages in a Go module to determine the lowest-numbered version of Go that can build it.

Index

• Constants
• type Result
• type Scanner
  • func (s *Scanner) Analyzer() (*analysis.Analyzer, error)
  • func (s *Scanner) ScanDir(dir string) (Result, error)
  • func (s *Scanner) ScanPackages(pkgs []*packages.Package) (Result, error)
• type VersionError
  • func (e VersionError) Error() string

Constants

const Mode = packages.NeedName | packages.NeedFiles | packages.NeedSyntax | packages.NeedTypes | packages.NeedTypesInfo | packages.NeedModule

Mode is the minimum mode needed when using packages.Load to scan packages.

Types

type Result

type Result interface {
	Version() int   // The lowest minor version of Go 1.x required.
	String() string // A descriptive string explaining the result.
}

Result is the type of a result returned by Scanner.ScanDir and Scanner.ScanPackages.

type Scanner

type Scanner struct {
	Deps     bool   // include dependencies
	Indirect bool   // with Deps, include indirect dependencies
	Verbose  bool   // be verbose
	Tests    bool   // scan *_test.go files
	Check    bool   // produce an error if the module declares the wrong version in go.mod
	HistDir  string // find Go stdlib history in this directory (default: $GOROOT/api)

	Result Result
	// contains filtered or unexported fields
}

Scanner scans a directory or set of packages to determine the lowest-numbered version of Go 1.x that can build them.

func (*Scanner) Analyzer

func (s *Scanner) Analyzer() (*analysis.Analyzer, error)

Analyzer produces an analysis.Analyzer that can be used to scan packages. The result (which may depend on scanning multiple packages) is available in s.Result.

func (*Scanner) ScanDir

func (s *Scanner) ScanDir(dir string) (Result, error)

ScanDir scans the module in a directory to determine the lowest-numbered version of Go 1.x that can build it.

func (*Scanner) ScanPackages

func (s *Scanner) ScanPackages(pkgs []*packages.Package) (Result, error)

ScanPackages scans the given packages to determine the lowest-numbered version of Go 1.x that can build them. The packages must all be in the same module. When using packages.Load to load the packages, the value for packages.Config.Mode must be at least Mode.

type VersionError

type VersionError struct {
	Computed Result
	Declared int
}

VersionError is the error returned by Scanner.ScanDir or Scanner.ScanPackages when [Scanner.Check] is enabled.

func (VersionError) Error

func (e VersionError) Error() string