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, the following elisp code...

(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))

...defines a project called "my-java-project" under the "/home/me/my-java-project" directory with additional, optional settings to help identify which files should be included in your TAGS file, which files should be excluded from a grep operation, etc.

Once a project is configured via project-def and loaded via project-load, the following project functions can be used:

Function Recommended Key Binding Details
project-load C-c p l Set project variables, open files named in the open-files-cache, run the user-defined startup hook.
project-unload C-c p u 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 C-c p c Run the project's compile command with the given arguments.
project-grep C-c p g 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 C-c p a Run ack from the project's basedir. If given a C-u arguement, run ack from the current buffer's directory.
project-find-file C-c p f 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 C-c p f Quickly open a file in basedir using 'ido'
project-index C-c p i 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 C-c p t Regenerate the project's TAGS file. Only files matching src-patterns are indexed.
project-dired C-c p d Open 'dired' on the project's basedir
project-status C-c p s Print values of project variables
project-home C-c p h cd to the project's basedir

As mk-project.el relies heavily on the find and grep commands in your environment. Unix and Linux systems certainly have find and grep. Cygwin can provide these commands for Windows.

More information on how to define and configure projects is availabe in the mk-project.el file.

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.

Found a bug or have a feature request?

Feel free to contact me at .