mk-project.el: An Emacs project library

What is it?

mk-project.el is an Emacs library to quickly switch between projects and perform operations on a per-project basis. A 'project' in this sense is a directory of related files, usually a directory of source files. Projects are configured in pure elisp and do not require configuration files in the project's directory which makes mk-project.el easier to use with certain version control systems than other libraries.

The 'mk' in 'mk-project' used to stand for me, Matt Keller, but now that I've published this library, let's say it stands for 'make' as in 'make project'.

How does it work?

A project is configured in 100% pure elisp. For example:

(project-def "my-java-project"
      '((basedir          "/home/me/my-java-project/")
        (src-patterns     ("*.java" "*.jsp"))
        (ignore-patterns  ("*.class" "*.wsdl"))
        (tags-file        "/home/me/.my-java-project/TAGS")
        (file-list-cache  "/home/me/.my-java-project/files")
        (open-files-cache "/home/me/.my-java-project/open-files")
        (vcs              git)
        (compile-cmd      "ant")
        (ack-args         "--java")
        (startup-hook     my-java-project-startup)
        (shutdown-hook    nil)))

(defun my-java-project-startup ()
  (setq c-basic-offset 3))

Once a project is configured, the following project functions can be used:

project-load
Set project variables, open files named in the open-files-cache, run the user-defined startup hook.
project-unload
Save open files names to the open-files-cache, run shutdown hook, run the user-defined shutdown hook, unset project variables, prompt to close all project files.
project-compile
Run the project's compile command with the given arguments.
project-grep
Run find-grep on the project's basedir, ignoring any files that match ignore-patterns or are excluded by the VCS setting. mk-project.el knows how to avoid the VCS-specific files and directories of git, cvs, subversion and bzr. If given a C-u arguement, start the search from the current buffer's directory.
project-ack
Run ack from the project's basedir. If given a C-u arguement, run ack from the current buffer's directory.
project-find-file
Quickly open a file in the project's basedir by regex. The search excludes files matching ignore-patterns or excluded by the VCS setting.
project-find-file-ido
Quickly open a file in basedir using 'ido'
project-index
Re-index the project files. The index is stored in buffer *file-index* and is used by project-find-file. The index can be cached to the file set in file-list-cache.
project-tags
Regenerate the project's TAGS file. Only files matching src-patterns are indexed.
project-dired
Open 'dired' on the project's basedir
project-status
Print values of project variables
project-home
cd to the project's basedir

As mk-project.el relies heavily on find-grep, it is only suited for unix-like operating systems. Perhaps cygwin would work, but it hasn't been tested.

Where can I get it?

Releases of mk-project are uploaded to the Emacs Wiki.

You can track recent versions (> 1.0.3) of the code at github: http://github.com/mattkeller/mk-project.

Older versions (< 1.0.3) are can be found in my .emacs git repo.

How do I install it?

Download mk-project.el. Place it in your emacs load-path. Load the library with (require 'mk-project). Optionally compile the library with byte-compile-file. Then define your projects in your .emacs file. The following key bindings are useful:

(global-set-key (kbd "C-c p c") 'project-compile)
(global-set-key (kbd "C-c p l") 'project-load)
(global-set-key (kbd "C-c p g") 'project-grep)
(global-set-key (kbd "C-c p a") 'project-ack)
(global-set-key (kbd "C-c p u") 'project-unload)
(global-set-key (kbd "C-c p f") 'project-find-file) ; or project-find-file-ido
(global-set-key (kbd "C-c p i") 'project-index)
(global-set-key (kbd "C-c p s") 'project-status)
(global-set-key (kbd "C-c p h") 'project-home)
(global-set-key (kbd "C-c p d") 'project-dired)
(global-set-key (kbd "C-c p t") 'project-tags)

What's going on with it?

Why is it?

There are several Emacs libraries that do similar things (ProjMan, project-root.el), but none of them fit all my needs. Uniquely, mk-project.el allows users to define projects in pure elisp while most of the existing projects required per-directory config files which don't always fit well with your version control software. Specifically, the libraries I mentioned do not work well with Clearcase's dynamic views.