maker

README

maker

GNU make snippets manager

---

📝 Table of Contents

• About
• Getting Started
• Usage
• Built Using
• TODO
• Contributing
• Authors
• Acknowledgments

🧐 About

Maker provides CLI tools to manage and use GNU make-compliant snippet files, which contain rules to deal with specific domains such as programming language toolchains or helper tools as docker, linters, dependency injectors (google wire, uber fx, etc) that are needed during any stage of a repository management.

Those snippet files rely on a convention-over-configuration style that uses variables that can be either set before the include happens or overridden later on. They also should not be modified directly on the client repositories, as they are meant to be updated with the upstream version.

Why?

• GNU make is true to the Unix philosophy: it does one thing, and does it well (since 1976!)
• newer language tool kits (2010+ at least) often include their own tool chain, which adds extra commands and flags to learn and repeat yourself when using them
• convention-over-configuration for common/best practices, which speed up project creation, maintenance and usage

🏁 Getting Started

Clone the repository and use make/make all to build, lint, test and generate coverage information.

To contribute please make sure you have installed the pre-commit hooks before committing.

Prerequisites

For building locally:

• Golang 1.15+
• GNU Make (optional)

For contributing:

• pre-commit tool
• golangci-lint binary on path
• hadolint binary on path

Install pre-commit using your package manager and then run pre-commit install once to configure the repository hooks. You can then commit normally.

🔧 Running the tests

All tests can be run using make test. Coverage is done through make coverage.

🎈 Usage

Add notes about how to use the system.

🔧 Built Using

• GNU make - 🖤
• Golang - base language

🧑‍💻 Authors

• @wwmoraes - Idea & Initial work

🎉 Acknowledgements

• Hat tip to anyone whose code was used
• Inspiration
• References

Documentation

Overview

Package maker provides CLI tools to manage and use GNU make-compliant snippet files, which contain rules to deal with specific domains such as programming language toolchains or helper tools as docker, linters, dependency injectors (google wire, uber fx, etc) that are needed during any stage of a repository management.

Those snippet files rely on a convention-over-configuration style that uses variables that can be either set before the include happens or overridden later on. They also should not be modified directly on the client repositories, as they are meant to be updated with the upstream version.

Copyright (c) William Artero. MIT License

Index

• Constants
• type Config
  • func (config *Config) AddRepository(repo *Repository) error
  • func (config *Config) GetRepository(reference string) (*Repository, error)
• type File
• type FileReader
• type Lock
  • func (lock Lock) Get(repo, name string) string
  • func (lock Lock) Set(repo, name, version string)
  • func (lock Lock) Unset(repo, name string)
• type Lockable
• type Maker
  • func New(conf, lock File, directory billy.Filesystem) (mk *Maker, err error)
  • func NewDefault() (mk *Maker, err error)
  • func (mk *Maker) Add(name string) error
  • func (mk *Maker) Init() error
  • func (mk *Maker) Install(force bool) (err error)
  • func (mk *Maker) Remove(name string) error
  • func (mk *Maker) Sync() (err error)
• type Repository
  • func (repository *Repository) AddSnippet(name, version string) error
  • func (repository *Repository) Get(reference, name string) (FileReader, error)
  • func (repository *Repository) HasSnippet(name string) bool
  • func (repository *Repository) Init() error
  • func (repository *Repository) SetSnippet(name, version string)
• type Truncable
• type UnlockCloser
• type Unlockable

Constants

const (
	SnippetsDirectory = ".make"
	ConfFilename      = "maker.yaml"
	LockFilename      = "maker.lock"
)

Types

type Config

type Config struct {
	Repositories []*Repository `yaml:"repositories"`
}

Config stores the snippets required and any extra Maker setting

func (*Config) AddRepository

func (config *Config) AddRepository(repo *Repository) error

func (*Config) GetRepository

func (config *Config) GetRepository(reference string) (*Repository, error)

GetRepository returns a repository for the given reference, which can be either an alias or an URL. An empty reference returns the first (i.e. default) entry found in the configuration.

type File

type File interface {
	io.Reader
	io.Writer
	io.Seeker

	Truncable
	Lockable
	Unlockable
}

File represents a descriptor object that supports read, write, seek, truncate and lock operations.

type FileReader

type FileReader interface {
	ID() plumbing.Hash
	Reader() (io.ReadCloser, error)
}

type Lock

type Lock map[string]map[string]string

Lock stores the md5 hash sum for each managed snippet

func (Lock) Get

func (lock Lock) Get(repo, name string) string

func (Lock) Set

func (lock Lock) Set(repo, name, version string)

func (Lock) Unset

func (lock Lock) Unset(repo, name string)

type Lockable

type Lockable interface {
	// Lock applies an advisory lock e.g. flock. It protects against access from
	// other processes
	Lock() error
}

Lockable represents an IO object that supports locking its access to the current process

type Maker

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

Maker manages the configuration, lock data and snippet files on a directory

func New

func New(conf, lock File, directory billy.Filesystem) (mk *Maker, err error)

New returns an instance of Maker using the provided file descriptors to read and write data from, and a target directory to manage the snippets within.

The caller is responsible for closing both file descriptors

func NewDefault

func NewDefault() (mk *Maker, err error)

NewDefault creates a standard Maker instance using the OS filesystem and the current directory as the repository root.

func (*Maker) Add

func (mk *Maker) Add(name string) error

Add fetches a snippet file and adds its info into the config and lock files

func (*Maker) Init

func (mk *Maker) Init() error

Init creates an empty configuration data with the default repository

func (*Maker) Install

func (mk *Maker) Install(force bool) (err error)

Install fetches the snippets if they're not present, or if there's any local changes

func (*Maker) Remove

func (mk *Maker) Remove(name string) error

Remove removes a snippet file and its info from the config and lock files

func (*Maker) Sync

func (mk *Maker) Sync() (err error)

Sync marshals the current configuration and lock data back into their respective file handlers. Flushing/syncing to an underlying persistent media is the caller's responsibility.

type Repository

type Repository struct {
	*git.Repository `yaml:"-"`

	Snippets map[string]string `yaml:"snippets"`
	Alias    string            `yaml:"alias,omitempty"`
	URL      string            `yaml:"url"`

	sync.Mutex `yaml:"-"`
}

func (*Repository) AddSnippet

func (repository *Repository) AddSnippet(name, version string) error

func (*Repository) Get

func (repository *Repository) Get(reference, name string) (FileReader, error)

Get returns the snippet file contents reader. The caller is responsible for closing it after usage.

func (*Repository) HasSnippet

func (repository *Repository) HasSnippet(name string) bool

func (*Repository) Init

func (repository *Repository) Init() error

func (*Repository) SetSnippet

func (repository *Repository) SetSnippet(name, version string)

type Truncable

type Truncable interface {
	// Truncate changes the size of the object. It does not change the I/O offset
	Truncate(size int64) error
}

Truncable represents an IO object that supports truncating its size to a specific value

type UnlockCloser

type UnlockCloser interface {
	io.Closer
	Unlockable
}

UnlockCloser represents an IO object that supports unlocking and closing

type Unlockable

type Unlockable interface {
	// Unlock removes the advisory lock to enable other processes to access it
	Unlock() error
}

Unlockable represents an IO object that supports unlocking its access to be accessible by any process