README
¶
binr
Binr is a Go package that implements a very simply way to for acquire command-line programs.
While developed with binaries in mind, this will also work well for any command line application which can be sourced programmatically.
!!!! Warning !!!
This is a work in progress.
This is pre-1.0. Please expect bugs and for the API to change. Use at your own risk, and please open issues with questions or bugs.
Usage
Import the binr library and call .Get for the absolute path to a locally-
installed command-line-utility. The provided Source will be utilized if
the command is not yet available.
Commands are downloaded to ~/.config/binr by default, though
XDG_CONFIG_HOME can be used to alter the location of ~/.config.
See the Godocs for more.
Roadmap
- Simple Fetching
- Content-addressed Caching
- Namespaces
- Checksum Validation
- Nonstandard Source Resolution
- Convenience Source Implementations
- Command Execution Environment Helper
- CI
- Releases
Architecture
See [[ARCHITECTURE.md]] for how it works and how the code is structured.
Contributing
See [[CONTRIBUTING.md]] for how to hack on binr.
Documentation
¶
Index ¶
Constants ¶
const ( LogDebug = zerolog.DebugLevel LogInfo = zerolog.DebugLevel LogWarn = zerolog.WarnLevel LogDisabled = zerolog.Disabled )
const DefaultLogLevel = LogDisabled
DefaultLogLevel for binr is logging disabled. Use SetLogLevel to change.
Variables ¶
This section is empty.
Functions ¶
func Get ¶
func Get(ctx context.Context, namespace, command, version string, source Source, options ...option) (path string, err error)
Get the path to a binary.
`namespace` is generally the name of the application or system which is utilizing binr. By default commands will be downloaded to this namespace within the current user's config directory (~/.config/binr/[namespace])
`command` is the name of the command to get. It is made available by default as ~/.config/binr/[namespace]/[command] and also ~/.config/binr/[namespace]/[command]-[version]
Version is the specific version to get. TODO: currently expects an exact (vX.Y.Z), but will soon support semver major and minor (vX and vX.Y).
The provided Source is a function which returns a final location at which the command and its checksum can be downloaded for a given os, architecture and version.
func Path ¶
Path returns the absolute path at which the given command for the given namespace is expected to exist. It does not validate the command's existence (see Get).
Version is optional, and if not provided will point to a "floating" link which is always updated to the current version. If provided, it must be a semver
func SetLogLevel ¶
func SetLogLevel(l logLevel)
SetLogLevel to LogDebug, LogInfo, LogWarn, or LogDisabled Errors are always returned as values.
func WithUpdate ¶
func WithUpdate() func(*config)
WithUpdate instructs the system to update extant binaries. The default behavior is to never replace a binary once it has been provided. Note that this option worls in concert with version and checksum URL. TODO: implement and document:
Has no effect if either the version is explicit (vX.Y.Z), or there is no checksum URL returned from the source implementation. If the version is omitted (aka "latest"), but a checksum URL is provided from the source implementation, WithUpdate will result in a call to .Get checking if the checksum differs from the currently cached binary, and replacing with the latest via download. If the version is provided, but is not explicit (vX.Y or vX), the source implementation should provide the checksum URL and source URL to the latest implementation which adheres to the specified semver, and the WithUpdate option causes this to be utilized.
Source Files
Directories