project

Documentation

Overview

Package project provides metadata and VCS information of a project.

Index

• Constants
• type ErrProject
  • func (e *ErrProject) Error() string
  • func (e *ErrProject) Is(err error) bool
  • func (e *ErrProject) Unwrap() error
• type GoModuleID
  • func GoModuleFromFile(dirAbs string) (*GoModuleID, error)
  • func GoModuleFromImportPath(importPath string) (*GoModuleID, error)
  • func (gm GoModuleID) ExecName() string
  • func (gm GoModuleID) String() string
• type Metadata
  • func New(opts ...Option) (*Metadata, error)
  • func (m Metadata) Options() Options
• type Option
  • func WithBaseOutputDir(dir string) Option
  • func WithDefaultVersion(defaultVersion string) Option
  • func WithDisplayName(name string) Option
  • func WithModulePath(path string) Option
  • func WithModuleVersion(version *semver.Version) Option
  • func WithName(name string) Option
  • func WithVCSKind(kind vcs.Kind) Option
  • func WithWandDataDir(wandDataDir string) Option
• type Options

Constants

const (
	// ErrDeriveVCSInformation indicates that the derivation of VCS version information failed.
	ErrDeriveVCSInformation = wErr.ErrString("failed to derive VCS version information")

	// ErrDetectProjectRootDirPath indicates that the detection of a project root directory path failed.
	ErrDetectProjectRootDirPath = wErr.ErrString("failed to detect project root directory path")

	// ErrDetermineGoModuleInformation indicates that a determination of Go module information failed.
	ErrDetermineGoModuleInformation = wErr.ErrString("failed to determine Go module information")

	// ErrPathNotRelative indicates that a path is not relative.
	ErrPathNotRelative = wErr.ErrString("path is not relative")
)

const (
	// GoModuleDefaultBuildInfoVersion is the default version for the build info of a Go module when it is not set or no
	// when no version was detected by the [runtime/debug.ReadBuildInfo] function. [As of Go 1.18] this defaults to [this
	// value] instead of an empty string and [the `go version -m` documentation] also describes the meaning of the value.
	//
	// [runtime/debug.ReadBuildInfo]: https://pkg.go.dev/runtime/debug@go1.18#ReadBuildInfo
	// [As of Go 1.18]: https://github.com/golang/go/commit/9cec77ac11b012283e654b423cf85cf9976bedd9#diff-abdadaf0d85a2e6c8e45da716909b2697d830b0c75149b9e35accda9c38622bdR2234
	// [this value]: https://github.com/golang/go/blob/122a22e0e9eba7fe712030d429fc4bcf6f447f5e/src/cmd/go/internal/load/pkg.go#L2288
	// [the `go version -m` documentation]: https://go.dev/ref/mod#modules-overview#go-version-m
	GoModuleDefaultBuildInfoVersion = "(devel)"

	// GoModuleDefaultFileName is the default name for a Go module file.
	GoModuleDefaultFileName = "go.mod"

	// GoModuleVersionLatest is the "version query suffix" for the latest version of a Go module.
	// See https://golang.org/ref/mod#version-queries for more details.
	GoModuleVersionLatest = "latest"

	// GoModuleVersionSuffixSeparator is the character that separates the Go module version from a import path.
	GoModuleVersionSuffixSeparator = "@"
)

const (
	// AppRelPath is the path for the project when registered as application by a wand.Wand.
	AppRelPath = ""

	// DefaultBaseOutputDir is the default base output directory relative to Options.RootDirPathAbs for compile, test
	// and production artifacts as well as distribution bundles, static web files or metric/statistic reports.
	DefaultBaseOutputDir = "out"

	// DefaultWandCacheDataDir is the default directory for wand specific cache data.
	DefaultWandCacheDataDir = "cache"

	// DefaultWandDir is the default directory for wand specific data.
	DefaultWandDir = ".wand"

	// DefaultVersion is the default version for a project vcs.Repository.
	DefaultVersion = "v0.0.0"
)

Types

type ErrProject

type ErrProject struct {
	// Err is a wrapped error.
	Err error
	// Kind is the error kind.
	Kind error
}

ErrProject represents a project error.

func (*ErrProject) Error

func (e *ErrProject) Error() string

func (*ErrProject) Is

func (e *ErrProject) Is(err error) bool

Is enables usage of errors.Is() to determine the kind of error that occurred.

func (*ErrProject) Unwrap

func (e *ErrProject) Unwrap() error

Unwrap returns the underlying error for usage with errors.Unwrap().

type GoModuleID

type GoModuleID struct {
	// IsLatest indicates whether the Go module version uses GoModuleVersionLatest as "version query suffix".
	IsLatest bool

	// Path is the canonical name for a module, declared with the module directive in the module's go.mod file.
	//
	// References
	//
	//   (1) https://golang.org/ref/mod#module-path
	//   (2) https://golang.org/ref/mod#go-mod-file-module
	//   (3) https://golang.org/ref/mod#glos-go-mod-file
	Path string

	// Version identifies an immutable snapshot of a module starting with the letter "v", followed by a semantic
	// version.
	// Note that a nil value is resolved using GoModuleVersionLatest s "version query suffix".
	//
	// References
	//
	//   (1) https://golang.org/ref/mod#versions
	//   (2) https://golang.org/ref/mod#version-queries
	//   (3) https://semver.org/spec/v2.0.0.html
	//   (4) https://golang.org/cmd/go/#hdr-Pseudo_versions
	//   (5) https://blog.golang.org/publishing-go-modules
	Version *semver.Version
}

GoModuleID stores partial information to identify a Go module.

See https://golang.org/ref/mod#modules-overview for more details.

func GoModuleFromFile

func GoModuleFromFile(dirAbs string) (*GoModuleID, error)

GoModuleFromFile parses a Go module file (GoModuleDefaultBuildInfoVersion). This is required because as of Go 1.18 the debug.ReadBuildInfo function does not work for Mage executables anymore because the way how module information is stored changed. Therefore the fields of the returned [debug.Module] type only has zero values, including the module path. The [debug.Module.Version] field has a default value (GoModuleDefaultBuildInfoVersion) which is not Semver compatible and causes the parsing to fail.

To get the required module information that was previously provided by the runtime/debug package the official golang.org/x/mod/modfile package is used instead.

func GoModuleFromImportPath

func GoModuleFromImportPath(importPath string) (*GoModuleID, error)

GoModuleFromImportPath creates a GoModuleID from the given import path. The path must be a valid Go module import path, that can optionally include the version suffix, in the "pkg@version" format.

func (GoModuleID) ExecName

func (gm GoModuleID) ExecName() string

ExecName returns the name of the compiled executable when the Go module Path is a "main" package.

func (GoModuleID) String

func (gm GoModuleID) String() string

type Metadata

type Metadata struct {
	// contains filtered or unexported fields
}

Metadata represents information about a project.

func New

func New(opts ...Option) (*Metadata, error)

New creates new project metadata.

The absolute path to the root directory is automatically set based on the current working directory while the Go module name is determined using the runtime/debug package.

The project version is derived from the vcs.Repository if not of type vcs.KindNone. The currently only supported vcs.Kind is vcs.KindGit. To set the vcs.Kind the WithVCSKind() project Option can be used.

If any error occurs nil is returned along with an error of type *ErrProject.

func (Metadata) Options

func (m Metadata) Options() Options

Options returns the project Options.

type Option

type Option func(*Options)

Option is a project option.

func WithBaseOutputDir

func WithBaseOutputDir(dir string) Option

WithBaseOutputDir sets the base output directory.

func WithDefaultVersion

func WithDefaultVersion(defaultVersion string) Option

WithDefaultVersion set the project default version.

func WithDisplayName

func WithDisplayName(name string) Option

WithDisplayName sets the project display name.

func WithModulePath

func WithModulePath(path string) Option

WithModulePath sets the module import path.

func WithModuleVersion

func WithModuleVersion(version *semver.Version) Option

WithModuleVersion sets the module version.

func WithName

func WithName(name string) Option

WithName sets the project name.

func WithVCSKind

func WithVCSKind(kind vcs.Kind) Option

WithVCSKind sets the vcs.Kind of the project vcs.Repository.

func WithWandDataDir

func WithWandDataDir(wandDataDir string) Option

WithWandDataDir sets the path to the directory for wand specific data.

type Options

type Options struct {
	// BaseOutputDir is the base project output directory, relative to RootDirPathAbs, for compile, test and production
	// artifacts as well as distribution bundles, static web files or metric/statistic reports.
	BaseOutputDir string

	// DefaultVersion is the default project version.
	DefaultVersion string

	// DisplayName is the project display name.
	DisplayName string

	// GoModule is the project Go module.
	GoModule *GoModuleID

	// Name is the project name.
	Name string

	// Repository is the project repository.
	Repository vcs.Repository

	// RootDirPathAbs is the absolute path to the project root directory.
	RootDirPathAbs string

	// VCSKind is the VCS kind of the project Repository.
	VCSKind vcs.Kind

	// WandDataDir is the path to the directory for wand specific data.
	WandDataDir string
}

Options stores project options.