ido-taskrunner

ido-taskrunner is a ido 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. 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/ido-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!

ido-taskrunner in action

GIF’s coming soon

Installation

MELPA

This package will be submitted to melpa shortly.

Manually

To install this package, you will need the following:

• projectile
• taskrunner
• emacs-async

Usage

Functions

There are several entry points for this package:

• ido-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 ido 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 now 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 ido-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 places(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 ido-taskrunner. This means that using the currently visited directory will be ignored. This means that if there is a project where the command make build is invoked from a folder called ~~/my-project/some-folder~ then ido-taskrunner will call the command and run it in the directory ~~/my-project/build~.

• ido-taskrunner-buffers: Every time a command is ran, a new buffer is spawned containing that commands output. This command displays a ido buffer letting the user select one of these command buffers and switch to it. It can be used to quickly check the status of running tasks.
• ido-taskrunner-kill-all-buffers: Kill all command buffers.
• ido-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 ido 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.
• ido-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.
• ido-taskrunner-update-cache: To speed up the task process and minimize wait time for the user, ido-taskrunner uses a cache for targets/tasks collected. When the ido-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.
• ido-taskrunner-command-history: Show a ido instance filled with the latest commands ran in the current project.

Minor mode

ido-taskrunner comes with its own minor mode called ido-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 ido-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 ido 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 IdT.

Variables

Some variables of interest are:

• ido-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.
• ido-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.
• ido-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 ido-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.
• ido-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 ido-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.
• ido-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.
• ido-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.
• ido-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.
• ido-taskrunner-command-history-size: This variable controls the number of saved commands in the history cache. Its default value is 10.
• ido-taskrunner-use-fuzzy-match: Whether or not ido uses fuzzy-matching or not. Its default is t.
• ido-taskrunner-prompt-before-show: The ido-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 ido buffer is shown for selection after targets which have not been cached/retrieved before are ready to be displayed 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.

• ido-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.
• ido-taskrunner-project-warning: Warning used when the currently visited buffer is not in a project recognized by projectile.
• ido-taskrunner-no-targets-found-warning: Warning used when there have been no targets/tasks found in the current project.
• ido-taskrunner-no-files-found-warning: Warning used when there have been no configuration files found for the build/taskrunner system in the current project.
• ido-taskrunner-command-history-empty-warning: Warning used when there are no items in the command history for the currently visited project.
• ido-taskrunner-no-buffers-warning: Warning used when there are no ido-taskrunner compilation buffers.
• ido-taskrunner-tasks-being-retrieved-warning: Warning used to indicate that tasks are being retrieved in the background. It is only shown if the ido-taskrunner-minor-mode is toggled on.
• ido-taskrunner-no-location-selected-warning: Warning used when the user selects a command to run but does not select a location.

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] leinengen
• [X] rake
• [X] Make
• [X] CMake
• [X] Meson/Ninja
• [X] go-task
• [X] mage
• [X] doit
• [X] mask
• [X] just
• [X] cargo-make
• [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

Systems

• [ ] Apache maven
• [ ] waf
• [ ] pants
• [ ] 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 emacs-taskrunner repository.