DEV Community: y-yagi

CLI for Windows with Go

y-yagi — Sun, 13 Dec 2020 04:49:02 +0000

Recently, I created a CLI for windows. I learned about some TIPS. Let's describe that in this article. Sample code exists in https://github.com/y-yagi/cli-for-windows

"GUI binary" or "console binary"

By default, Go build a binary as "console binary". This means a window console is kept showing when a binary is executed. It is good for applications that will finish immediately. But that's not good for some kind of applications(e.g. GUI application, HTTP server).

In the case of such applications, we can build binary as "GUI binary". In "GUI binary", a window console doesn't show when a binary is executed.

In order to build with "GUI binary", you need to specify "-H windowsgui" to ldflags.
On Windows, -H windowsgui writes a "GUI binary" instead of a "console binary."

$ go build -ldflags "-H windowsgui"

Embed icon to a binary file

Maybe you want to include an icon in your CLI. Go build binary as a Portable Executable format. Portable Executable format has a section for resources(rsrc section). We need to add an icon to that section.

When embed data to Go binary, need to prepare syso file. There is a tool called rsrc that will generate syso file for embedding in the rsrc section, so let's use that.

$ go get github.com/akavel/rsrc
$ rsrc -ico your-icon.ico -arch=amd64

You need to prepare syso files per architecture. syso file will link automatically when run go build. So we don't need to specify options or files to go build.

Notification Area

If you choose "GUI binary" applications, maybe we need to consider how the exit of applications.
In the case of "console binary", if want to exit, simplify close the console. But in the case of "GUI binary", we can't do that.
Of course, we can exit applications via the Task Manager. But maybe it difficult for people who unfamiliar with Windows.

So let's consider to use "Notification Area"(or called "System Tray").

The notification area is located at the right end of the taskbar, it can be operated to applications by GUI.

Of course, already exists that library for using Notification Area.
getlantern/systray

Here's an example code with systray.

func main() {
    systray.Run(onReady, onExit) // (1)
    return
}

func onReady() {
    systray.SetIcon(icon) // (2)
    systray.SetTitle("My CLI")
    systray.SetTooltip("My CLI")

    mQuit := systray.AddMenuItem("Quit", "Quit") // (3)
    <-mQuit.ClickedCh
    systray.Quit()
}

func onExit() {
  // clean up
}

(1) systray.Run initializes GUI and starts the event loop. Also, you can pass two functions that run when applications starting and exiting.
(2) systray.SetIcon accept to array bytes of icon data. This means you need to prepare array bytes of an icon. 2goarray can use in this case. 2goarray can encode files into array bytes.

$ go get github.com/cratonica/2goarray
$ 2goarray icon main < icon.png > icon.go

(3) systray.AddMenuItem add a menu item to an application. In this example, add a menu item that quit an application.

This example shows as follows on Windows.

CI

Of course, we need to consider the CI. Before, we have little choice for CI. But now we have some choices. For example, AppVeyor, CircleCI, and GitHub Actions.

In my personal opinion, if you are using GitHub, I recommend GitHub Actions. Because it can use easily and don't' need to create an extra account.

An example of GitHub Actions is the following. It needs to add a file to .github/workflows/ directory for use(e.g. .github/workflows/ci.yml).

name: CI
on: [push]
jobs:

  build:
    name: Build
    runs-on: windows-latest
    steps:

    - name: Set up Go # (1)
      uses: actions/setup-go@v2
      with:
        go-version: 1.15

    - name: Check out code # (2)
      uses: actions/checkout@v2

    - name: Run test (3)
      run: |
        go test ./...
      env:
        GO111MODULE: on

(1) Set up Go environment by setup-go action.
(2) Checks-out my repository by checkout action.
(3) Run tests.

That's it!

If you want to run golangci-lint in CI, you can use golangci-lint-action same as other actions.

Release

Finally, let's consider the management of release binaries. If you are using GitHub, I think GitHub Releases is good for that. It can manage source and binaries in the same place.

GitHub Releases are based on Git tags. So I wanted to upload binaries to GitHub Releases when push gi tags. We can use GitHub Actions also this case. Here is an example of a setting.

name: Release
on:
  push:
    tags:
      - 'v*' # (1)

jobs:
  windows:
    runs-on: windows-latest
    steps:
      - name: Set up Go
        uses: actions/setup-go@v2
        with:
          go-version: 1.15

      - name: Check out code into the Go module directory
        uses: actions/checkout@v2

      - name: Run release # (2)
        uses: goreleaser/goreleaser-action@v2
        with:
          version: latest
          args: release --rm-dist
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

(1) Restrict that only run when git tag started with v(e.g. v1.0.0).
(2) Use GoReleaser action for upload binaries to GitHub Releases.

GoReleaser settings as follows.

builds:
  - binary: "MY CLI"
    goos:
      - windows
    ldflags: -H windowsgui
    goarch:
      - amd64
      - 386
archives:
  -
    format: zip
release:
  github:
    owner: y-yagi
    name: cli-for-windows

You need to specify github section under the release section` for upload binaries to GitHub Releases.

Automatically change Go version with `gvm` and `zsh`

y-yagi — Thu, 26 Mar 2020 02:55:43 +0000

gvm does not change Go version automatically. This is a little inconvenience when developing multiple projects that use different Go versions. Let's change Go version when moved to the directory of Go project like rbenv.

Get Go version

Normally, we don't have a file that described Go version(like .ruby-version, .node-version).
But since Go 1.12, go.mod includes Go version 1. This probably the same with the projects' Go version. Let's reuse this.

This can do as following with zsh.

_change_go_version() {
  if [ -f "go.mod" ]; then
    local version=(`grep -Po "^go \K([0-9\.]*)$" go.mod`)
    gvm use ${version}
  fi
}

Change Go version when directory changed

zsh provides some hook functions. One of them, chpwd executed whenever the current working directory is changed 2. This function can use inside zshrc. Let's call _change_go_version inside this function.

# .zshrc
chpwd()
{
  _change_go_version
}

As a result, autosomally call gvm use when moved directory that has the go.mod file. If you use another version manager, please change gvm use inside _change_go_version.

Have a nice day!

Intro to `cacher` that simple cache library

y-yagi — Fri, 04 Oct 2019 00:18:30 +0000

I created the cache library for the Go language. It's named cacher.
GitHub: https://github.com/y-yagi/cacher

cacher supports to use a file system to store cache data.

Why this need?

I create CLI tools often and sometimes want to use cache in that. For example, when the same HTTP API is called many times and the result of API rarely changes.
Normally, using Redis or memcached(or something similar) for the cache. But in the case of CLI, it may not be using those middlewares. So I wanted a cache library that supports to file system.

How to use

Example:

package main

import (
    "fmt"
    "time"

    "github.com/y-yagi/cacher"
)

func main() {
    // Specify a directory that stores cache data.
    c := cacher.WithFileStore("/tmp/")

    // Arguments are cache key, data and expiry time. If uses `cacher.Forever`, cache never expires.
    c.Write("cache-key", []byte("value"), cacher.Forever)
    value, _ := c.Read("cache-key")
    fmt.Print(string(value))

    c.Write("cache-key2", []byte("value"), 1*time.Second)

    time.Sleep(2 * time.Second)

    // If the cache expired. `Read` returns nil.
    value, _ = c.Read("cache-key2")
    fmt.Print(string(value))
}

For more detail, please see the API doc.

How to store data to file?

Go supports multiple formats to store data. This time I use gob package. The gob package can handle Go data structure as is. A simple example is followed.

package main

import (
    "bytes"
    "encoding/gob"
    "fmt"
    "log"
)

type entry struct {
    Value      []byte
    Expiration int64
}

func main() {
    e := &entry{Value: []byte("value"), Expiration: 0}
    encodedEntry := encode(e)

    fmt.Printf("%#v\n", encodedEntry)

    decodedEntry := decode(encodedEntry)
    fmt.Printf("%#v\n", decodedEntry)
}

func encode(e *entry) []byte {
    buf := bytes.NewBuffer(nil)
    err := gob.NewEncoder(buf).Encode(e)
    if err != nil {
        log.Fatal("encode error:", err)
    }
    return buf.Bytes()
}

func decode(data []byte) *entry {
    var e entry
    buf := bytes.NewBuffer(data)
    err := gob.NewDecoder(buf).Decode(&e)
    if err != nil {
        log.Fatal("decode error:", err)
    }
    return &e
}

For more detail, please see the blog entry and API doc.

Wrapping up

I introduced my cache library that assumed to using CLI. But may more appropriate approaches/libraries exist I think. If you know something, please tell me. Thanks!

Show parameter name in usage message of flag

y-yagi — Sun, 18 Nov 2018 07:37:34 +0000

Flag package provides features about command-line flag parsing. It includes a usage message of course. For example, it shows them as following.

package main

import (
    "flag"
    "os"
)

func main() {
    var importFile string
    var config bool
    var number int

    flags := flag.NewFlagSet("mycmd", flag.ExitOnError)
    flags.StringVar(&importFile, "import", "", "import file.")
    flags.BoolVar(&config, "c", false, "edit config.")
    flags.IntVar(&number, "n", 0, "number of executions.")

    flags.Parse(os.Args[1:])
}

$ ./mycmd --help
Usage of mycmd:
  -c    edit config.
  -import string
        import file.
  -n int
        number of executions.

This build automatically. The parameter name uses the flag's type. But sometimes want to customize parameter name.
For example, in the example above, I would like to use file as an argument to -import and number as an argument to -n(Because that is surely more natural ;)).

This can specify from usage argument xxVar methods. If includes a back-quoted name in usage, it uses for the parameter name.

package main

import (
    "flag"
    "os"
)

func main() {
    var importFile string
    var config bool
    var number int

    flags := flag.NewFlagSet("mycmd", flag.ExitOnError)
    flags.StringVar(&importFile, "import", "", "Import `file`.")
    flags.BoolVar(&config, "c", false, "Edit config.")
    flags.IntVar(&number, "n", 0, "`Number` of executions.")

    flags.Parse(os.Args[1:])
}

$ ./mycmd --help 
Usage of mycmd:
  -c    edit config.
  -import file
        import file.
  -n number
        number of executions.

I didn't know long about this. This describes in the doc of PrintDefaults func.

I hope this helps someone.

Avoiding the `master` branch is used in `go get`

y-yagi — Wed, 31 Oct 2018 04:44:12 +0000

go get retrieves the default branch of the package by default. This is often using the master branch. But the master branch is including work in progress code sometimes, so want to avoid to use it.
To solve this problem, there is an approach of dividing the default branch and the development branch. But this is just a little complex.

Other approaches to solving this problem, use a branch or tag named go1.
go get has a rule for looks for a branch of tag that matches the locally installed version of Go. It describes in the doc.

When checking out or updating a package, get looks for a branch or tag that matches the locally installed version of Go. The most important rule is that if the local installation is running version "go1", get searches for a branch or tag named "go1". If no such version exists it retrieves the default branch of the package.

https://golang.org/cmd/go/#hdr-Download_and_install_packages_and_dependencies

This is also can confirm in get.go. Below is the code of the corresponding part.

// selectTag returns the closest matching tag for a given version.
// Closest means the latest one that is not after the current release.
// Version "goX" (or "goX.Y" or "goX.Y.Z") matches tags of the same form.
// Version "release.rN" matches tags of the form "go.rN" (N being a floating-point number).
// Version "weekly.YYYY-MM-DD" matches tags like "go.weekly.YYYY-MM-DD".
//
// NOTE(rsc): Eventually we will need to decide on some logic here.
// For now, there is only "go1". This matches the docs in go help get.
func selectTag(goVersion string, tags []string) (match string) {
    for _, t := range tags {
        if t == "go1" {
            return "go1"
        }
    }
    return ""
}

https://github.com/golang/go/blob/fde4b9ed14e339b5064373c1d4a73e211ec32ac4/src/cmd/go/internal/get/get.go#L541-L556

Unfortunately, we can use go1 tar or branch only now.

But can use go1 to control the version used. Let's try to use it.

Show comments in GoDoc

y-yagi — Sun, 21 Oct 2018 06:15:52 +0000

GoDoc show comments in code when runs godoc command with notes option. The notes option can specify regular expression matching note markers to show(default is BUG).

$ godoc --help
usage: godoc package [name ...] 
(snip)
  -notes string
        regular expression matching note markers to show (default "BUG")

package exter

type Exter struct {
}

func NewExter() {
    // TODO(who): implement
    return Exter{}
}

func (exter *Exter) Run() error {
    // BUG(who): Not return correct value
    return nil
}

For example, there is a code the above, doc shows as follows.

But if you remove (who) from comment, comment not shows in GoDoc.

This is because of the limit of GoDoc.

The notes need to write a comment as MARKER(uid): note body. Also, MAKER needs 2 or more uppercase [A-Z] letters and a UID of at least one character.

This is describing at Note type comment.
https://godoc.org/go/doc#Note

Regex for MARKER is here: https://github.com/golang/go/blob/035f9e8102d3b46877b7462fcd365324272d1d0e/src/go/doc/reader.go#L435

It is a little unusual for (uid) to be mandatory (at least for me ;) ), so be careful.

Check deprecated things in Go

y-yagi — Thu, 11 Oct 2018 00:25:21 +0000

How deprecate functions?

Go official suggest to using Deprecated: comment in the doc that wants to deprecate functions, struct fields.
Godoc: documenting Go code

It is using in standard libraries. Ref: standard library.

For example, SEEK_SET const of os/file.go , using comment as follows.

// Deprecated: Use io.SeekStart, io.SeekCurrent, and io.SeekEnd.
const (
    SEEK_SET int = 0 // seek relative to the origin of the file
    SEEK_CUR int = 1 // seek relative to the current offset
    SEEK_END int = 2 // seek relative to the end
)

So we should follow this rule in our libraries.

But if you follow this rule, deprecated functions show in Go doc now(Related discussion).
Also, golint does not check about deprecated comments(Related discussion).
As such, go official tools does not have particular behavior for deprecated comments.

Using `staticcheck` for check

staticcheck in go-tools can check deprecated things.

staticcheck reports as follows if using deprecated things.

package main

import (
    "net/http/httputil"
)

func main() {
    httputil.NewClientConn(nil, nil)
}

$ staticcheck main.go
deprecated.go:8:2: httputil.NewClientConn is deprecated: Use the Client or Transport in package net/http instead.  (SA1019)

staticcheck shows comments as it is behinds Deprecated:. Using this in CI is good.

Conclusion

Using Deprecated:comment for deprecated things.
Check to deprecated things with staticcheck.