README.org

ivy-taskrunner

Ivy-taskrunner is a ivy interface to the 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. 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 here. Thanks!

ivy-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 spring-framework and the gradle daemon takes a bit of time to initialize.

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 ivy-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:

If the tasks have been previously cached(as in, you have called ivy-taskrunner atleast 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:

• projectile
• ivy/swiper
• (OPTIONAL) counsel-projectile
• taskrunner

Usage

Functions

There are several entry points for this package:

• ivy-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 ivy buffer where the user can select one of them to run or customize. 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

Additionally, you can select a task and customize it(i.e. Add arguments to it). When a task is customized, it is saved and will persist across sessions until it is deleted.

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.

• ivy-taskrunner-delete-all-custom-commands: This command will delete all custom commands for the project if any exist.
• ivy-taskrunner-delete-custom-command: This command will display an ivy interface containing all of the custom commands for the project. You can then select one and delete it.
• ivy-taskrunner-buffers: Every time a command is ran, a new buffer is spawned containing that commands output. This command displays a ivy 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
• ivy-taskrunner-kill-all-buffers: Kill all command buffers.
• ivy-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 ivy 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.
• ivy-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.
• ivy-taskrunner-update-cache: To speed up the task process and minimize wait time for the user, ivy-taskrunner uses a cache for targets/tasks collected. When the ivy-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, more tasks can be 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.
• ivy-taskrunner-command-history: Show a ivy 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.

• ivy-taskrunner-notifications-on: Turn on notifications which are shown when a task is finished running.
• ivy-taskrunner-notifications-off: Turn off notifications.

Minor mode

ivy-taskrunner comes with its own minor mode called ivy-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 ivy-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 ivy 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 instead of being queried manually.

The minor mode will appear in the modeline as IvT.

Variables

Some variables of interest are:

• ivy-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.
• ivy-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.
• ivy-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 ivy-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.
• ivy-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 ivy-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.
• ivy-taskrunner-go-task-bin-path: This variable contains the path used to locate the folder containing the golang binary for the go-task taskrunner. Its default is /home/USER/go/bin.
• ivy-taskrunner-mage-bin-path: This variable contains the path used to locate the folder containing the golang binary for the mage taskrunner. Its default is /home/USER/go/bin.
• ivy-taskrunner-doit-bin-path: This variable contains the path used to locate the folder containing the binary for the doit taskrunner. Its default is /home/USER/.local/bin.
• ivy-taskrunner-command-history-size: This variable controls the number of saved commands in the history cache. Its default value is 10.
• ivy-taskrunner-prompt-before-show: The ivy-taskrunner tasks/targets are retrieved asynchronously and this can sometimes take a while. 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 ivy buffer is shown for selection(just in case you do not end up typing into it) then set this to t. Its default is nil.

Warnings

If English is not your preferred language then you can set these warnings to whatever you would like.

• ivy-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.
• ivy-taskrunner-project-warning: Warning used when the currently visited buffer is not in a project recognized by projectile.
• ivy-taskrunner-no-targets-found-warning: Warning used when there have been no targets/tasks found in the current project.
• ivy-taskrunner-no-files-found-warning: Warning used when there have been no configuration files found for the build/taskrunner system in the current project.
• ivy-taskrunner-command-history-empty-warning: Warning used when there are no items in the command history for the currently visited project.
• ivy-taskrunner-no-buffers-warning: Warning used when there are no ivy-taskrunner compilation buffers.
• ivy-taskrunner-tasks-being-retrieved-warning: Warning used to indicate that tasks are being retrieved in the background. It is only shown if the ivy-taskrunner-minor-mode is toggled on.
• ivy-taskrunner-no-custom-commands-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] go-task
• [X] mage
• [X] doit
• [X] mask
• [X] just
• [X] cargo-make
• [X] buidler
• [X] Tusk
• [X] 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
• [ ] waf
• [ ] pants
• [ ] phulp
• [ ] foy
• [ ] tasks.json(VSCode)
• [ ] Ninja
• [ ] sbt
• [ ] Buck
• [ ] Bazel
• [ ] msbuild(Maybe)

Contributors

Thanks to these people for helping me with various aspects of this package:

• @leungbk for helping me clean up the code and giving me advice on adding support for users which do not use package.el as their package manager.

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 echancment requests should go to the emacs-taskrunner repository.