* helm-taskrunner
Helm-taskrunner is a Helm interface to the [[https://github.com/emacs-taskrunner/emacs-taskrunner][emacs-taskrunner]] library. It provides
a convenient way to select targets/tasks within the current project and run them
in a custom compilation buffer.

The majority of the tasks/targets are gathered by either parsing
files(makefiles) or parsing the output of the taskrunner/build systems which
have the ability to list all targets/tasks in the project. This can sometimes be
a bit slow but this is made to be a (usually) one time cost and is
asynchronous. All tasks retrieved are saved in a cache which persists after an
Emacs instance is killed and then loaded up again when emacs/ivy-taskrunner is
started.

*Warning*: I have not worked with most of these build systems/taskrunners but
 support has been provided for them. Since my knowledge is fairly elementary, I
 might miss some subtleties. If you have any advice then please feel free to
 open a pull request on the repository hosting the backend for this project
 which can be found [[https://github.com/emacs-taskrunner/emacs-taskrunner][here]]. Thanks!
** helm-taskrunner in action
*Disclaimer*: Collecting tasks and displaying them does not normally take as long
as it does in these gif's below. This example was ran on the [[https://github.com/spring-projects/spring-framework][spring-framework]]
and the ~gradle~ daemon takes a bit of time to initialize.

[[file:docs/helm-no-prompt.gif]]

You may have noticed that there is a slight problem. Tasks are collected in the
background which leaves the user to edit/run commands as they wish. A problem
might occur if you are typing and all the tasks/targets for the project have
been gathered. This means that the menu will be displayed right away and you
might type text into it which you did not mean to. If you would like to, you can
set the variable ~helm-taskrunner-prompt-before-show~ to ~t~. Doing this will
prompt you before showing tasks which have just been gathered. An example can be
found below:

[[file:docs/helm-prompt.gif]]

If the tasks have been previously cached(as in, you have called ~helm-taskrunner~
at least once in the repository) then they will appear instantly and no prompt
will be displayed. This means that enabling this option will not get in the way
of operation for the majority of times.
** Obligatory "What window manager/color theme are you using?"
I am using ~i3wm~ with ~polybar~ for window manager/status bar combo.
The theme used is ~gruvbox-theme~ and I am running the ~gruvbox-dark-soft~ version.
* Installation
** MELPA
This package will be submitted to melpa shortly.
** Manually
To install this package, you will need the following:

- [[https://github.com/bbatsov/projectile][projectile]] 
- [[https://github.com/emacs-helm/helm][Helm]] 
- [[https://github.com/emacs-taskrunner/emacs-taskrunner][taskrunner]]
- [[https://github.com/jwiegley/emacs-async][emacs-async]] 
- [[https://github.com/bbatsov/helm-projectile][(OPTIONAL) helm-projectile]] 
* Usage
** Functions
There are several entry points for this package:
- ~helm-taskrunner~: This function gathers all of the tasks from the
  taskrunners/build systems at the project root asynchronously. The tasks
  gathered are then presented in a ~helm~ buffer where the user can select one of
  them to run. The tasks can be ran in 6 different places:
  - at project root
  - at project root with extra arguments supplied by the user
  - at directory visited by the current buffer
  - at directory visited by the current buffer with extra arguments supplied by
    the user
  - at a custom directory selected by the user
  - at a custom directory selected by the user with extra arguments supplied by
    the user
    
    *Warning*: This function is asynchronous so the tasks might not appear for a
    few seconds. You are free to continue working until they do. If for some
    reason no tasks can be located, an error message will be displayed in the
    echo buffer.

    *Warning*: Whenever ~helm-taskrunner~ is used to run a command in another
    repository and the project is either one which uses ~Make~ , ~CMake~ or
    ~Meson/Ninja~ then the first four options(at project root, project root with
    args, currently visited directory and currently visited directory with args)
    will always use the build folder path locted by ~helm-taskrunner~. This means
    that using the currently visited directory will be ignored. This also means
    that if there is a project where the command ~make build~ is invoked from a
    folder called ~~/my-project/some-folder~ then ~helm-taskrunner~ will call the
    command and run it in the directory ~~/my-project/build~ (or whatever build
    folder name is detected).
- ~helm-taskrunner-delete-custom-command~: This command will display a ~helm~ 
  interface containing all of the custom commands for the project. You can then
  select one and delete it.
- ~helm-taskrunner-delete-all-custom-commands~: This command will delete *all* custom
  commands for the project if any exist.
- ~helm-taskrunner-buffers~: Every time a command is ran, a new buffer is spawned
  containing that commands output. This command displays a helm buffer letting
  the user select one of these command buffers and use an action on it. There
  are three main choices:
  - Open buffer
  - Kill buffer
  - Kill all command buffers
- ~helm-taskrunner-kill-all-buffers~: Kill all command buffers.
- ~helm-taskrunner-config-files~: The majority of taskrunner/build systems have
  some type of a configuration file associate with them(Make -> Makefile, Grunt
  -> gruntfile and so on...). When this function is invoked, a ~helm~ buffer will
  display all configuration files for all build/taskrunner systems detected at
  project root. The user can then select one of them and the file will be
  opened. This function will also work for build/taskrunner systems which have
  multiple configuration files(ex. Gradle or Cabal). If this is the case then
  the user will be presented with all possible such files and will again be able
  to select one of them to open.
- ~helm-taskrunner-rerun-last-command~: When invoked, this function will rerun the
  last command ran in the project. The command is ran in the same directory as
  before so if a different directory than the project root was selected, the
  command will be ran there again.
- ~helm-taskrunner-update-cache~: To speed up the task process and minimize wait
  time for the user, helm-taskrunner uses a cache for targets/tasks
  collected(located in the user Emacs directory). When the ~helm-taskrunner~
  command is called, the cache is checked. If the tasks have been cached then
  they are returned immediately and displayed to the user. Sometimes, new tasks
  are added to the configuration files of the taskrunner/build system and
  they will not be displayed. When this command is called, the cache is
  overwritten and the tasks are gathered all over again and displayed to the
  user. If you have added new tasks and do not see them then call this function
  to update the cache and include them for selection.
- ~helm-taskrunner-command-history~: Show a helm instance filled with the latest
  commands ran in the current project. From this point, you can select a command
  and re-run it wherever you would like.
  
*Warning*: The functions below are only available if you are running an Emacs
 which is compiled with notifications. If you put these in your ~init~ file and
 then use the file with an emacs which is not configured for this then calling
 these will throw an error since the functions below will not be available in
 the namespace. Additionally, I have not tested the notifications popup on
 Windows or MacOS so if you have any trouble then please file a bug report.

- ~helm-taskrunner-notifications-on~: Turn on notifications which are shown when a
  task is finished running.
- ~helm-taskrunner-notifications-off~: Turn off notifications.
** Minor mode
~helm-taskrunner~ comes with its own minor mode called
~helm-taskrunner-minor-mode~. It is a global minor mode which attaches a function to
the ~projectile-after-switch-project-hook~. When this minor mode is enabled, tasks
for the currently visited project are retrieved in the background so they are
ready whenever you need them. If you attempt to start ~helm-taskrunner~ while the
tasks are being gathered in the background, a warning will be shown to let you
know that they are not available at the moment. As soon as they are gathered, a
~helm~ window will be shown which will let you choose from them. When this mode is
toggled off, the function is removed from the hook.

Using this minor mode is completely optional. The only benefit is that tasks are
retrieved as soon as you switch to a project using ~projectile~.

The minor mode will appear in the modeline as ~HT~.
** Variables
Some variables of interest are:
- ~helm-taskrunner-preferred-js-package-manager~: Choose if you prefer npm or
  yarn. This is usually deduced automatically depending on the presence of a
  ~package-lock.json~ file or ~yarn.lock~ file but if those are not found then this
  variable value is used if it is not nil. If this variable is left nil(its default) then ~npm~ is
  whenever the package manager cannot be deduced.
- ~helm-taskrunner-get-all-make-targets~: When this variable is not nil then all
  make targets are retrieved including those which start with ~_~ (underscore)
  which are usually considered to be "hidden". Its default value is t.
- ~helm-taskrunner-build-dir-list~: This variable holds a list of strings where
  each of them is a possible name of the build folder used in a project. Its
  default value contains: ~build, Build, buildDir, builddir, builds~. When
  helm-taskrunner is attempting to locate a ~Makefile~ for ~CMake~ or a ~build.ninja~
  for ~meson~ then all of the directories in this list are checked one by one. The first
  directory which contains one of these files is used as the build folder and
  build targets are collected from there. If you use a different name for build
  directories which you would like searched then please append the name to the
  list assigned to this variable.
- ~helm-taskrunner-source-dir-list~: This variable is similar to the build-dir-list
  one. It contains a list of strings and each one indicates a possible name for
  the source folder of a project. Its default value is: ~src, Src, source,
  Source~. When helm-taskrunner is attempting to locate the ~CMakeLists.txt~ or
  ~meson.build~ files, it checks these directories in case it is an in-source
  build. If you use a different name for source directories then please append
  that to the list assigned to this variable.
- ~helm-taskrunner-go-task-bin-path~: This variable contains the path used to
  locate the folder containing the golang binary for the [[https://github.com/go-task/task][go-task]] taskrunner. Its default is ~/home/USER/go/bin~.
- ~helm-taskrunner-mage-bin-path~: This variable contains the path used to
  locate the folder containing the golang binary for the [[https://github.com/magefile/mage][mage]] taskrunner. Its default is ~/home/USER/go/bin~.
- ~helm-taskrunner-doit-bin-path~: This variable contains the path used to locate
  the folder containing the binary for the [[https://github.com/pydoit/doit][doit]] taskrunner. Its default is
  ~/home/USER/.local/bin~.
- ~helm-taskrunner-command-history-size~: This variable controls the number of
  saved commands in the history cache. Its default value is 10.
- ~helm-taskrunner-use-fuzzy-match~: Whether or not ~helm~ uses fuzzy-matching or
  not. Its default is ~t~.
- ~helm-taskrunner-prompt-before-show~: The ~helm-taskrunner~ tasks/targets are
  retrieved asynchronously. While this is being done, you are free to do what
  you please(edit text, scroll around and so on). If you would like to be
  prompted before the ~helm~ buffer is shown for selection when the targets are
  not in the cache then set this variable to ~t~. Its default value is ~nil~.
*** Warnings
If English is not your preferred language then you can set these warnings to
whatever you would like.
- ~helm-taskrunner-no-previous-command-ran-warning~: This variable holds a string
  which is displayed to the user when there is no previous command which can be
  reran in the current project. Change this if you would like to see something different.
- ~helm-taskrunner-project-warning~: Warning used when the currently visited
  buffer is not in a  project recognized by ~projectile.~
- ~helm-taskrunner-no-targets-found-warning~: Warning used when there have been no
  targets/tasks found in the current project.
- ~helm-taskrunner-no-files-found-warning~: Warning used when there have been no
  configuration files found for the build/taskrunner system in the current project.
- ~helm-taskrunner-command-history-empty-warning~: Warning used when there are no
  items in the command history for the currently visited project.
- ~helm-taskrunner-no-buffers-warning~: Warning used when there are no 
  ~helm-taskrunner~ compilation buffers.
- ~helm-taskrunner-tasks-being-retrieved-warning~: Warning used to indicate that
  tasks are being retrieved in the background. It is only shown if the
  ~helm-taskrunner-minor-mode~ is toggled on.
- ~helm-taskrunner-custom-command-warning~: Warning used to indicate that the user
  does not have any custom commands for the currently visited project.
* Supported build/taskrunner systems
The following systems are currently supported:
- [X] yarn/npm
- [X] Gulp
- [X] Grunt
- [X] Gradle
- [X] Jake
- [X] Apache ant
- [X] mix
- [X] leiningen
- [X] rake
- [X] Make
- [X] CMake
- [X] Meson/Ninja
- [X] [[https://github.com/go-task/task][go-task]] 
- [X] [[https://github.com/magefile/mage][mage]] 
- [X] [[https://github.com/pydoit/doit][doit]] 
- [X] [[https://github.com/jakedeichert/mask][mask]] 
- [X] [[https://github.com/casey/just][just]] 
- [X] [[https://github.com/sagiegurari/cargo-make][cargo-make]]
- [X] [[https://buidler.dev/][buidler]] 
- [X] [[https://github.com/rliebz/tusk][Tusk]] 
- [X] [[https://dnephin.github.io/dobi/install.html][dobi]] 
- [X] cargo(Limited Support)
- [X] go compiler(Limited support)
- [X] Cask(Limited Support)
- [X] stack(Limited Support)
- [X] cabal(Limited Support)
** Planning to support
*** Features
- [ ] Multiple build folders
- [ ] Add shallow/deep support. Deep support will use ripgrep/ag/grep(whichever
  one is available in that order) and shallow support will work very similarly
  to the way it is done now. This is if the user does not have any of those
  installed or they would not like to spawn too many ripgrep/ag/find processes
  on their system which will scan the project root. Deep support will probably
  be enabled by default but the user will still be able to override this behaviour
*** Systems
- [ ] Apache maven
- [ ] [[https://waf.io/][waf]] 
- [ ] [[https://github.com/pantsbuild/pants][pants]] 
- [ ] [[https://github.com/reisraff/phulp][phulp]] 
- [ ] [[https://github.com/zaaack/foy][foy]] 
- [ ] tasks.json(VSCode)
- [ ] Ninja
- [ ] sbt
- [ ] Buck
- [ ] Bazel
- [ ] msbuild(Maybe)
* Bug Reports and Echancement Requests
If you have a bug report related to the user interface then please submit it
here. Otherwise, all other bug reports and enhancement requests should go to the
[[https://github.com/emacs-taskrunner/emacs-taskrunner][emacs-taskrunner repository]].