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?
- 2010/01/30: Release version 1.3 with custom find command support.
- 2009/12/16: Released version 1.2.1 with a bug fix.
- 2009/09/09: Released version 1.2 with ido integration.
- 2009/06/11: Released version 1.1 with ack support.
- 2009/05/26: Pushed mk-project v1.0.3 to github.
- 2009/05/26: Released version 1.0.2
- 2009/05/23: Released version 1.0.1
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.