butler

package module
v1.9.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 18, 2023 License: Apache-2.0 Imports: 3 Imported by: 0

README

butler

Go reference GitHub last commit GitHub Go Report Card GitHub release (latest SemVer) GitHub issues Libraries.io dependency status for GitHub repo

butler helps you to create, build, debug, test and run your Go projects.

When you often create new apps using Go, it quickly becomes annoying when you realize all the steps it takes to configure the basics. You need to manually create the source files, version info requires more steps to be injected into the executable, using Visual Studio Code requires you to manually setup the tasks you want to run…

Using the butler tool, you can automate and streamline this process. The tool will take care of initializing your project, running your project, debugging it, building it and running the tests.

You should be using butler if:

  • you're tired of setting up your projects manually
  • you don't want to have to specify the main package every time you want build or run your project
  • you keep on forgetting how to setup debugging Visual Studio Code
  • you don't want to setup your tasks file manually in Visual Studio Code
  • you want to have the Git revision, branch name and version number automatically in your project
  • you're tired of manually writing Makefiles to build, test and run your project
  • you want a better way to do tasks before and after the build than writing non-portable shell scripts
  • you want an easy way to cross-compile for all common GOOS/GOARCH combinations
  • you want a way to build, run and test your project in a cross-platform manner

Requirements

Installation

Using go get

You can run the following command to install butler:

go install github.com/robertranjan/butler/cmd/butler@latest

This will create the butler command in your $GOPATH/bin folder.

The tool is self-contained and doesn't have any external dependencies.

Manually

To install it manually, download the butler executable from the releases and place it in $GOPATH/bin.

Starting a new project

To start a new project, you can use the new subcommand as follows:

butler new --path=<target path> \
         --package=<package> \
         --name=<name of your project> \
         --description=<description of your project> \
         --copyright=<copyright of your project> \
         [--with-git] \
         [--with-docker] \
         [--with-github-action] \
         [--with-gitlab-ci] \
         [--overwrite]

When you run it, you'll get the following output:

➜ butler new --path go-example --package github.com/robertranjan/go-example
Creating package: github.com/robertranjan/go-example
Project path: /Users/pclaerhout/Desktop/go-example
Writing: go-example
Writing: go-example/butler.json
Writing: go-example/.vscode
Writing: go-example/.vscode/tasks.json
Writing: go-example/.vscode/settings.json
Writing: go-example/.vscode/launch.json
Writing: go-example/LICENSE
Writing: go-example/.gitignore
Writing: go-example/.dockerignore
Writing: go-example/Dockerfile
Writing: go-example/README.md
Writing: go-example/scripts/post_build
Writing: go-example/scripts/post_build/post_build.example.go
Writing: go-example/library.go
Writing: go-example/library_test.go
Writing: go-example/cmd/go-example
Writing: go-example/cmd/go-example/main.go
Writing: go-example/versioninfo
Writing: go-example/versioninfo/versioninfo.go
Writing: go-example/scripts/pre_build
Writing: go-example/scripts/pre_build/pre_build.example.go
Writing: go-example/go.mod

It will automatically create the following folder and file structure:

go-example
├── LICENSE
├── README.md
├── cmd
│   └── main
│       └── main.go
├── butler.json
├── go.mod
├── library.go
├── library_test.go
├── scripts
│   ├── post_build
│   │   └── post_build.example.go
│   └── pre_build
│       └── pre_build.example.go
└── versioninfo
    └── versioninfo.go

An important file which is generated and can be used to further customize the project and it's settings is the butler.json file which sits next to the go.mod file.

You can specify the following options:

  • --path: the path where the new project should be created, e.g. /home/username/go-example (if not specified, it will create a directory with the name of the prject in the current path)
  • --package: the main package for the new project, e.g. github.com/robertranjan/go-example (defaults to the project name if specified)
  • --name: the name of the project, if not specified, the last part of the path is used
  • --description: the description of the project, used for the readme
  • --copyright: the copyright of the project, used for the readme
  • --with-git: if specified, a local Git repository will be created for the project and the source files will automatically be committed.
  • --with-docker: if specified, a sample Dockerfile and .dockerignore file will be created.
  • --with-github-action: if specified, a sample Github Actions file will be created.
  • --with-gitlab-ci: if specified, a sample Gitlab-CI file will be created.
  • --overwrite: if the destination path already exists, overwrite it (be careful, the original folder will be replaced)

Initializing an existing project

When you already have an existing folder structure, you can run the init command to add the missing pieces.

butler init

This command is supposed to run from the project's directory and doesn't take any arguments.

Building a project

From within the project root, run the build command to build the executable:

butler build [-v] [--output=<path>] [--goos=<os>] [--goarch=<arch>]

By default, the output is put in the build subdirectory but can be customized in the configuration file.

You can specify the following options:

  • -v: the packages which are built will be listed.
  • --output: you can override the default output path as specified in the configuration file.
  • --goos: you can override the GOOS environment variable which indicates for which OS you are compiling.
  • --goarch: you can override the GOARCH environment variable which indicates for which architecture you are compiling.

You can read more about the GOOS and GOARCH environment variables here.

As part of the build process, the versioninfo package will be filled with the following details:

With every build, these variables are automatically updated.

Pre-build and post-build hooks

Just before the build, if a file called <project_root>/scripts/pre_build/pre_build.go is present, it will be executed and will get a lot of info about the build injected. It's a plain Go file, so use whatever trick or tool you know. A sample pre-build script looks as follows:

package main

import (
    "github.com/robertranjan/butler"
    "github.com/pieterclaerhout/go-log"
)

func main() {

    args, err := butler.ParseBuildArgs()
    log.CheckError(err)

    log.InfoDump(args, "pre_build arguments")

}

You can also execute a script after the build. To do so, create a file <project_root>/scripts/post_build/post_build.go with contents similar to:

package main

import (
    "github.com/robertranjan/butler"
    "github.com/pieterclaerhout/go-log"
)

func main() {

    args, err := butler.ParseBuildArgs()
    log.CheckError(err)

    log.InfoDump(args, "post_build arguments")

}

Parsing arguments in pre/post build scripts.

To parse the arguments, you can use butler.ParseBuildArgs()

The parameters it gets are are struct of the type butler.BuildArgs:

butler.BuildArgs{
ProjectPath: "/home/user/butler",
OutputPath: "/home/user/butler/build/butler",
GOOS: "darwin",
GOARCH: "amd64",
ProjectName: "butler",
ProjectDescription: "butler helps you to create, build, test and run your Go projects",
ProjectCopyright: "© 2023-2025 Copyright Robert Thanulingam",
Version: "0.7.0",
Revision: "2065b13",
Branch: "main",
RawBuildCommand: []string{
    "go",
    "build",
    "-o",
    "build/butler",
    "-ldflags",
    "-s -w 
    -X github.com/robertranjan/butler/versioninfo.ProjectName=butler 
    ...
    ...
    -X github.com/robertranjan/butler/versioninfo.Version=1.9.1
    -X github.com/robertranjan/butler/versioninfo.Revision=4a7e9a7 
    -X github.com/robertranjan/butler/versioninfo.Branch=main",
    "-trimpath",
    "github.com/robertranjan/butler/cmd/butler",
},
}

The same information is also available in the following environment variables:

BUTLER_BRANCH="main"
BUTLER_GOARCH="amd64"
BUTLER_GOOS="darwin"
BUTLER_OUTPUT_PATH="/home/user/butler/build/butler"
...
...
BUTLER_PROJECT_NAME="butler"
BUTLER_PROJECT_PATH="/home/user/butler"
BUTLER_REVISION="2065b13"
BUTLER_VERSION="1.9.1"

Using Bash scripts for pre/post build actions.

If you prefer to use a bash script instead for the pre/post build actions, you can create a file called:

<project_root>/scripts/post_build/pre_build.sh

or

<project_root>/scripts/post_build/post_build.sh

It should be marked as executable.

Using Batch files for pre/post build actions.

If you prefer to use a batch file on Windows instead for the pre/post build actions, you can create a file called:

<project_root>/scripts/post_build/pre_build.bat

or

<project_root>/scripts/post_build/post_build.bat

How butler defines which pre/post build script to run

butler will search for pre/post build scripts in the following order:

  • pre_build.go / post_build.go
  • pre_build.sh / post_build.sh
  • pre_build.bat / post_build.bat

Packaging a project

From within the project root, run the package command to build the executable for windows / darwin / linux in the 386 and amd64 variants and compresses the result as a .zip (windows) or .tgz (linux / mac):

butler package [-v] [--concurrency=4]

By default, the output is put in the build subdirectory but can be customized in the configuration file.

The filenames which are constructed use the following convention:

build/<project.name>_<goos>-<goarch>_v<project.version>.[zip,tgz]

The executable will be compressed and, if present in the project, the project's README.md file as well.

You can specify the following options:

  • -v: the packages which are built will be listed.
  • --concurrency: how many package processes should run in parallel, defaults to the number of CPUs.

As part of the build process, the versioninfo package will be filled with the following details:

  • versioninfo.ProjectName: the name of the project from the configuration file
  • versioninfo.ProjectDescription: the description of the project from the configuration file
  • versioninfo.Version: the version of the project from the configuration file
  • versioninfo.Revision: the current Git commit hash
  • versioninfo.Branch: the current Git branch name

With every build, these variables are automatically updated.

Debugging a project

From within the project root, run:

butler debug

This will build the project and run it's main target through the Delve debugger. If the dlv command is not yet present in your $GOPATH/bin folder, it will automaticall be installed the first time you run it.

When creating a new project or performing init on an existing project, it also configures debugging from within Visual Studio Code. It's a simple as setting one or more breakpoints and choose "Start" > "Debug" from the menu. It creates a launch configuration called Debug.

Running a project

From within the project root, run:

butler run <args>

This will build the project and run it's main target passing the <args> to the command.

Testing a project

From within the project root, run:

butler test

This will run all the tests defined in the package.

Installing the executable

To install the main executable of your project in $GOPATH/bin, simply run the install command.

This will build the project and install it in the $GOPATH/bin folder. The name of the executable is the basename of build output path (as specified in the configuration file.

butler install

Uninstalling the executable

Similar to the install command, there is also an uninstall command which removes the executable from $GOPATH/bin.

butler uninstall

Running a static analysis

You can use the staticcheck command to run the staticcheck static analyzer. The binary required to run staticcheck is automatically installed if needed.

butler staticcheck

Building a Docker image

You can use the docker-image command to build a Docker image using the Dockerfile in the project folder. When you create a new project, a starter Dockerfile will be created automatically.

butler docker-container

The config file butler.json

When you create a new project or init an existing one, a butler.json file will be created in the root of your project. This file can be used to configure the project. The full config file is as follows:

{
    "project": {
        "name": "go-example",
        "version": "1.9.1",
        "description": "a go-example program",
        "copyright": "your username",
        "package": "github.com/your_username/go-example",
        "main_package": "github.com/your_username/go-example/cmd/go-example"
    },
    "build": {
        "output_path": "bin/",
        "ld_flags": [
            "-s",
            "-w"
        ],
        "ld_flags_windows": [
            "-s",
            "-w",
            "-H",
            "windowsgui"
        ],
        "ld_flags_darwin": [],
        "ld_flags_linux": [],
        "extra_args": [
            "-trimpath"
        ],
        "use_gotip": false
    },
    "run": {
        "environ": {
            "var": "val"
        }
    },
    "package": {
        "include_readme": true
    },
    "test": {
        "extra_args": [
            "-count=1"
        ]
    },
    "staticcheck": {
        "checks": [
            "all",
            "-ST1005",
            "-ST1000"
        ]
    },
    "docker-image": {
        "name": "butler",
        "repository": "your_username/go-example",
        "tag": "version",
        "prune_images_after_build": true
    }
}

Project Config

  • name: the name of your project (will be availabme under <package>/versioninfo.ProjectName)
  • version: the version of your project (will be availabme under <package>/versioninfo.Version)
  • description: the description of your project (will be availabme under <package>/versioninfo.ProjectDescription)
  • copyright: the description of your project (will be availabme under <package>/versioninfo.ProjectCopyright)
  • package: the root package of your project
  • main_package: the full path to the main package of your app, defaults to <package>/cmd/<project-name>

Build Config

  • output_path: the path where the built executable should be placed. Defaults to build/<project-name>
  • ld_flags: the linker flags you want to use for building. You can find more info about these flags here. These are only used if you don't specify specific parameters for a specifc GOOS.
  • ld_flags_darwin: the linker flags you want to use for building darwin. You can find more info about these flags here.
  • ld_flags_linux: the linker flags you want to use for building for linux. You can find more info about these flags here.
  • ld_flags_windows: the linker flags you want to use for building for windows. You can find more info about these flags here.
  • extra_args: contains any extra command-line parameters you want to add to the go build command when you run butler build.
  • use_gotip: setting this to true uses gotip to compile instead of the regular gocommand. Make sure you have gotip installed.

Run Config

  • environ: the environment variables to use when running the app

Package Config

  • include_readme: boolean indicating if the README.md file should be included in the package or not

Test Config

  • extra_args: contains any extra command-line parameters you want to add to the go test command when you run butler test.

Staticcheck Config

Docker Image Config

  • name: the name of the docker image you want to create. Defaults to the project name.
  • repository: the repository to which you want to push the image. If left empty, the image will only be created locally.
  • tag: can be either revision or version (the default) and indicates what value should be used for the tag.
  • prune_images_after_build: if set to true, a docker image prune -f will be executed after the docker build step.

Bootstrapping butler

If you want to build butler from scratch, you can use the following command (or use the "bootstrap" build task in Visual Studio Code):

go build -v -o build/butler github.com/robertranjan/butler/cmd/butler

If you have a version of butler installed, you can use it to build itself.

Roadmap

To get an idea on what's coming, you can check the GitHub Milestones

Resources & origional author

stamps

visit for stamps

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrArgsMissing is what is returned when no arguments could be found
	ErrArgsMissing = errors.New("No arguments were found")

	// ErrArgsDecodeError is what is returned when the arguments could be decoded (empty or invalid JSON)
	ErrArgsDecodeError = errors.New("Failed to decode arguments")
)

Functions

This section is empty.

Types

type BuildArgs 

type BuildArgs struct {
	ProjectPath        string   `json:"project_path,omitempty"`        // The root path of the project
	OutputPath         string   `json:"output_path,omitempty"`         // The absolute build path
	GOOS               string   `json:"GOOS,omitempty"`                // The GOOS for which was compiled
	GOARCH             string   `json:"GOARCH,omitempty"`              // The GOARCH for which was compiled
	ProjectName        string   `json:"project_name,omitempty"`        // The project name
	ProjectDescription string   `json:"project_description,omitempty"` // The project description
	ProjectCopyright   string   `json:"project_copyright,omitempty"`   // The project copyright
	Version            string   `json:"version,omitempty"`             // The version info
	Revision           string   `json:"revision,omitempty"`            // The project revision
	Branch             string   `json:"branch,omitempty"`              // The project branch
	RawBuildCommand    []string `json:"raw_build_command,omitempty"`   // The raw build command which is executed
}

BuildArgs are the arguments which are passed to the pre_build.go and post_build.go scripts

func ParseBuildArgs 

func ParseBuildArgs() (BuildArgs, error)

ParseBuildArgs parses the build arguments from os.Args

func (BuildArgs) AsMap 

func (b BuildArgs) AsMap() map[string]string

AsMap returns the build arguments as a map

Source Files

View all Source files

Directories

Path Synopsis
cmd
builder
butler
cleaner
creator
debugger
dockerimage
installer
packager
runner
staticcheck
tester
uninstaller
version
builder
cleaner
common
common/compressors
config
creator
debugger
dockerimager
installer
packager
runner
staticchecker
tester
uninstaller
version
Package butler helps you to create, build, debug, test and run your Go projects.
 Package butler helps you to create, build, debug, test and run your Go projects.
scripts
post_build
pre_build

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.