declarative-project-mode

An Emacs minor mode for declarative project resource management. Define your project’s dependencies, files, symlinks, and workspace assignments in a single .project file, then install everything with one keybinding.

Installation

straight.el / Doom Emacs

;; straight.el
(straight-use-package
 '(declarative-project-mode
   :host github
   :repo "cuttlefisch/declarative-project-mode"))

;; Doom Emacs (packages.el)
(package! declarative-project-mode
  :recipe (:host github
           :repo "cuttlefisch/declarative-project-mode"))

Manual

git clone https://github.com/cuttlefisch/declarative-project-mode.git

(add-to-list 'load-path "/path/to/declarative-project-mode")
(require 'declarative-project-mode)

Usage

Create a .project file in your project root. The mode activates automatically when you visit a .project file.

Press C-c C-c i to install all declared resources.

Example .project (YAML)

project-name: "My Project"
required-resources:
  - README.org
  - src/main.el
deps:
  - src: git@github.com:user/repo.git
    dest: vendor/repo
  - src: git@github.com:user/other.git
    args: "--branch develop"
local-files:
  - src: ~/templates/makefile
    dest: Makefile
symlinks:
  - targ: ~/notes/my-project.org
    link: docs/notes.org
treemacs-workspaces:
  - "Emacs Packages"

Auto-install

To install resources automatically when the mode activates:

(setq declarative-project-auto-install t)

Org-Babel Integration

Embed project specs in org files as declarative-project src blocks:

project-name: "My Project"
deps:
  - src: git@github.com:user/repo.git
    dest: repo

Execute with C-c C-c on the src block. The :dir header argument sets the project root directory (defaults to default-directory).

Enable in your config:

(add-to-list 'org-babel-load-languages '(declarative-project . t))
(org-babel-do-load-languages 'org-babel-load-languages org-babel-load-languages)

Treemacs Workspace Integration

The optional declarative-project-treemacs-mode manages treemacs workspaces from .project files. Each project declares which workspaces it belongs to, and the mode ensures those assignments exist.

(require 'declarative-project-treemacs)
(declarative-project-treemacs-mode 1)

When enabled, project installation creates or updates treemacs workspace entries. Set declarative-project-treemacs-autoprune to nil to disable automatic removal of stale project entries on mode init.

Framework-specific configuration

Doom Emacs

In packages.el:

(package! declarative-project-mode
  :recipe (:host github :repo "cuttlefisch/declarative-project-mode"))

In config.el:

(use-package! declarative-project-mode
  :config
  (after! treemacs
    (require 'declarative-project-treemacs)
    (setq declarative-project-treemacs-cache-file
          (expand-file-name "treemacs-declared-workspaces.el" doom-cache-dir))
    (declarative-project-treemacs-mode 1)))

Spacemacs

In dotspacemacs-additional-packages:

(declarative-project-mode
 :location (recipe :fetcher github :repo "cuttlefisch/declarative-project-mode"))

In dotspacemacs/user-config:

(require 'declarative-project-treemacs)
(setq declarative-project-treemacs-cache-file
      (expand-file-name "treemacs-declared-workspaces.el" spacemacs-cache-directory))
(declarative-project-treemacs-mode 1)

Vanilla Emacs

(require 'declarative-project-treemacs)
(declarative-project-treemacs-mode 1)
;; Cache file defaults to user-emacs-directory; customize if needed:
;; (setq declarative-project-treemacs-cache-file "~/.cache/emacs/treemacs-declared-workspaces.el")

Spec Reference

Field	Type	Description
project-name	string	Display name for the project
required-resources	list(string)	Paths that must exist; warns on missing
deps	list(object)	Git repos to clone (src, dest, args)
local-files	list(object)	Files to copy into the project (src, dest)
symlinks	list(object)	Symlinks to create (targ, link)
treemacs-workspaces	list(string)	Treemacs workspaces to assign this project to

For deps, local-files, and symlinks: omitting dest or link defaults to placing the resource in the project root directory.

Configuration

Variable	Default	Description
declarative-project-auto-install	nil	Auto-run installation when mode activates
declarative-project-treemacs-autoprune	t	Remove stale project entries on treemacs mode init
declarative-project-treemacs-cache-file	user-emacs-directory	Path to the workspace cache file

Development

cask install
make test    # 96 Buttercup specs

See CONTRIBUTING.org for the full development guide.

License

GNU General Public License v3.0