diff --git a/bake/README.adoc b/bake/README.adoc index d88ad21..e15e32a 100644 --- a/bake/README.adoc +++ b/bake/README.adoc @@ -2,19 +2,39 @@ Go Build + Something like Make = Bake ¯\_(ツ)_/¯ 🤷 -== Installation +== Getting Started -Run: +In any directory, run: `bake _bake init` to create a `bake/` directory with an empty project. ----- -go install github.com/DavidGamba/go-getoptions/bake@bake ----- +Then run: `bake` to see the available tasks. -Then add this to your bashrc: +== Install +* Install using go: ++ +Install the binary into your `~/go/bin`: ++ +---- +go install github.com/DavidGamba/dgtools/bake@latest +---- ++ +Then setup the completion. ++ +For bash: ++ ---- complete -o default -C bake bake ---- ++ +For zsh: ++ +[source, zsh] +---- +export ZSHELL="true" +autoload -U +X compinit && compinit +autoload -U +X bashcompinit && bashcompinit +complete -o default -C bake bake +---- == Example Task @@ -27,17 +47,11 @@ package main import ( "context" "fmt" - "log" "os" "github.com/DavidGamba/go-getoptions" - "github.com/DavidGamba/go-getoptions/dag" ) -var Logger = log.New(os.Stderr, "", log.LstdFlags) - -var TM *dag.TaskMap - // say:hello - This is a greeting func Hello(opt *getoptions.GetOpt) getoptions.CommandFn { var lang string @@ -76,12 +90,16 @@ Bake is a Make like tool that allows you to define and run tasks defined in Go c First it searches to see if the current directory is named `bake/`, next it searches for `bake/` inside the current directory, next it searches for `bake/` in the root of the Go project (the `go.mod` file dir) and finally it searches for `bake/` in the root of the Git repo. This allows to run bake from anywhere in the repo. -Once a `bake/` dir is found, it will compile the code as a Go plugin and load it (`go build -buildmode=plugin -o=bake.so`). -The plugin is only recompiled if the source code is changed (using https://github.com/DavidGamba/dgtools/tree/master/fsmodtime[fsmodtime]). +Once a `bake/` dir is found, it will parse the AST of the Go files in that directory to find functions that match the proper signature. +It will then generate an entry point file that uses those functions, this file is auto-generated any time your source code changes. +Finally it will compile the binary and run it. + +Having a go binary that bake runs allows to debug your code directly without having to worry about the bake internals. +The binary is only recompiled if the source code is changed (using https://github.com/DavidGamba/dgtools/tree/master/fsmodtime[fsmodtime]). -Once the plugin is loaded, the source code is parsed to find function declarations matching the bake Task signature (`func(*getoptions.GetOpt) getoptions.CommandFn`). -Additionally, it tries to load a `dag.TaskMap` global named `TM`. +The bake binary loads your functions as tasks and subtasks and makes their options available for completion. +The bake Task signature is `func(opt *getoptions.GetOpt) getoptions.CommandFn`. The functions are loaded as `go-getoptions` commands and subcommands, by parsing the comment description. For example: @@ -102,37 +120,14 @@ This allows to generate custom task graphs. Since the plugin tasks are added to the bake command's `go-getoptions` instance, completions are automatically generated. -== Known Issues - -Working with plugins has a few downsides. -In particular: +=== Debugging -* The version of Go must match between the `bake` binary and the plugin. -Because of that, the recommended install method is using `go install` rather than a package manager. +Go to the `bake/` directory and run and you should see the `bake` binary. -* The versions of the dependencies must match between the `bake` binary and the plugin. -A helper will be added to alleviate this task. +Set your IDE Debugger to run `./bake` with the proper arguments for your task. == ROADMAP -* Add helper to generate go.mod with the same dependencies as the bake binary. +* Currently only `opt.String` is supported, add support for all `go-getoptions` types. * Automated cancellation on timeout when passing -t flag. - -* Allow to compile a static binary with the bundled plugin. - -* Allow two operation modes: -+ -1. Using golang plugins as currently done. -2. Adding a main function and compiling a full static executable, then executing that binary using exec. -Ensure bake is handling the completions but once execution is set to run the exec the binary. - -=== Debugging - -TODO: This section needs work, waiting on https://github.com/go-delve/delve/issues/1628[delve#1628] - -Install with Debug flags: - ----- -go install -trimpath -gcflags "all=-N -l" github.com/DavidGamba/go-getoptions/bake@bake -----