1 ;;; ede/base.el --- Baseclasses for EDE.
3 ;; Copyright (C) 2010-2015 Free Software Foundation, Inc.
5 ;; Author: Eric M. Ludlam <zappo@gnu.org>
7 ;; This file is part of GNU Emacs.
9 ;; GNU Emacs is free software: you can redistribute it and/or modify
10 ;; it under the terms of the GNU General Public License as published by
11 ;; the Free Software Foundation, either version 3 of the License, or
12 ;; (at your option) any later version.
14 ;; GNU Emacs is distributed in the hope that it will be useful,
15 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
16 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 ;; GNU General Public License for more details.
19 ;; You should have received a copy of the GNU General Public License
20 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
24 ;; Baseclasses for EDE.
26 ;; Contains all the base structures needed by EDE.
30 (require 'eieio-speedbar)
36 (defvar ede-object-root-project)
38 (declare-function data-debug-new-buffer "data-debug")
39 (declare-function data-debug-insert-object-slots "eieio-datadebug")
40 (declare-function ede-parent-project "ede" (&optional obj))
41 (declare-function ede-current-project "ede" (&optional dir))
45 ;; The TARGET is an entity in a project that knows about files
46 ;; and features of those files.
48 (defclass ede-target (eieio-speedbar-directory-button)
49 ((buttonface :initform speedbar-file-face) ;override for superclass
55 :documentation "Name of this target.")
56 ;; @todo - I think this should be "dir", and not "path".
60 ;:label "Path to target"
61 ;:group (default name)
62 :documentation "The path to the sources of this target.
63 Relative to the path of the project it belongs to.")
64 (source :initarg :source
66 ;; I'd prefer a list of strings.
68 :custom (repeat (string :tag "File"))
70 :group (default source)
71 :documentation "Source files in this target.")
72 (versionsource :initarg :versionsource
75 :custom (repeat (string :tag "File"))
76 :label "Source Files with Version String"
79 "Source files with a version string in them.
80 These files are checked for a version string whenever the EDE version
81 of the master project is changed. When strings are found, the version
82 previously there is updated.")
85 (sourcetype :allocation :class
86 :type list ;; list of symbols
88 "A list of `ede-sourcecode' objects this class will handle.
89 This is used to match target objects with the compilers they can use, and
90 which files this object is interested in."
91 :accessor ede-object-sourcecode)
92 (keybindings :allocation :class
93 :initform (("D" . ede-debug-target))
95 "Keybindings specialized to this type of target."
96 :accessor ede-object-keybindings)
97 (menu :allocation :class
98 :initform ( [ "Debug target" ede-debug-target
99 (ede-buffer-belongs-to-target-p) ]
100 [ "Run target" ede-run-target
101 (ede-buffer-belongs-to-target-p) ]
103 :documentation "Menu specialized to this type of target."
104 :accessor ede-object-menu)
106 "A target is a structure that describes a file set that produces something.
107 Targets, as with 'Make', is an entity that will manage a file set
108 and knows how to compile or otherwise transform those files into some
109 other desired outcome.")
111 ;;; PROJECT/PLACEHOLDER
113 ;; Project placeholders are minimum parts of a project used
114 ;; by the project cache. The project cache can refer to these placeholders,
115 ;; and swap them out with the real-deal when that project is loaded.
117 (defclass ede-project-placeholder (eieio-speedbar-directory-button)
118 ((name :initarg :name
123 :group (default name)
124 :documentation "The name used when generating distribution files.")
125 (version :initarg :version
130 :group (default name)
131 :documentation "The version number used when distributing files.")
132 (directory :type string
134 :documentation "Directory this project is associated with.")
135 (dirinode :documentation "The inode id for :directory.")
138 :documentation "The File uniquely tagging this project instance.
139 For some project types, this will be the file that stores the project configuration.
140 In other projects types, this file is merely a unique identifier to this type of project.")
141 (rootproject ; :initarg - no initarg, don't save this slot!
143 :type (or null ede-project-placeholder-child)
144 :documentation "Pointer to our root project.")
146 "Placeholder object for projects not loaded into memory.
147 Projects placeholders will be stored in a user specific location
148 and querying them will cause the actual project to get loaded.")
152 ;; An EDE project controls a set of TARGETS, and can also contain
153 ;; multiple SUBPROJECTS.
155 ;; The project defines a set of features that need to be built from
156 ;; files, in addition as to controlling what to do with the file set,
157 ;; such as creating distributions, compilation, and web sites.
159 ;; Projects can also affect how EDE works, by changing what appears in
160 ;; the EDE menu, or how some keys are bound.
162 (unless (fboundp 'ede-target-list-p)
163 (cl-deftype ede-target-list () '(list-of ede-target)))
165 (defclass ede-project (ede-project-placeholder)
166 ((subproj :initform nil
168 :documentation "Sub projects controlled by this project.
169 For Automake based projects, each directory is treated as a project.")
170 (targets :initarg :targets
171 :type ede-target-list
172 :custom (repeat (object :objectcreatefcn ede-new-target-custom))
173 :label "Local Targets"
175 :documentation "List of top level targets in this project.")
176 (locate-obj :type (or null ede-locate-base-child)
178 "A locate object to use as a backup to `ede-expand-filename'.")
179 (tool-cache :initarg :tool-cache
181 :custom (repeat object)
184 :documentation "List of tool cache configurations in this project.
185 This allows any tool to create, manage, and persist project-specific settings.")
186 (mailinglist :initarg :mailinglist
190 :label "Mailing List Address"
193 "An email address where users might send email for help.")
194 (web-site-url :initarg :web-site-url
198 :label "Web Site URL"
200 :documentation "URL to this projects web site.
201 This is a URL to be sent to a web site for documentation.")
202 (web-site-directory :initarg :web-site-directory
205 :label "Web Page Directory"
208 "A directory where web pages can be found by Emacs.
209 For remote locations use a path compatible with ange-ftp or EFS.
210 You can also use TRAMP for use with rcp & scp.")
211 (web-site-file :initarg :web-site-file
214 :label "Web Page File"
217 "A file which contains the home page for this project.
218 This file can be relative to slot `web-site-directory'.
219 This can be a local file, use ange-ftp, EFS, or TRAMP.")
220 (ftp-site :initarg :ftp-site
227 "FTP site where this project's distribution can be found.
228 This FTP site should be in Emacs form, as needed by `ange-ftp', but can
229 also be of a form used by TRAMP for use with scp, or rcp.")
230 (ftp-upload-site :initarg :ftp-upload-site
234 :label "FTP Upload site"
237 "FTP Site to upload new distributions to.
238 This FTP site should be in Emacs form as needed by `ange-ftp'.
239 If this slot is nil, then use `ftp-site' instead.")
240 (configurations :initarg :configurations
241 :initform ("debug" "release")
243 :custom (repeat string)
244 :label "Configuration Options"
246 :documentation "List of available configuration types.
247 Individual target/project types can form associations between a configuration,
248 and target specific elements such as build variables.")
249 (configuration-default :initarg :configuration-default
252 :label "Current Configuration"
254 :documentation "The default configuration.")
255 (local-variables :initarg :local-variables
257 :custom (repeat (cons (sexp :tag "Variable")
258 (sexp :tag "Value")))
259 :label "Project Local Variables"
261 :documentation "Project local variables")
262 (keybindings :allocation :class
263 :initform (("D" . ede-debug-target)
264 ("R" . ede-run-target))
265 :documentation "Keybindings specialized to this type of target."
266 :accessor ede-object-keybindings)
267 (menu :allocation :class
270 [ "Update Version" ede-update-version ede-object ]
271 [ "Version Control Status" ede-vc-project-directory ede-object ]
272 [ "Edit Project Homepage" ede-edit-web-page
273 (and ede-object (oref (ede-toplevel) web-site-file)) ]
274 [ "Browse Project URL" ede-web-browse-home
276 (not (string= "" (oref (ede-toplevel) web-site-url)))) ]
278 [ "Rescan Project Files" ede-rescan-toplevel t ]
279 [ "Edit Projectfile" ede-edit-file-target
280 (ede-buffer-belongs-to-project-p) ]
282 :documentation "Menu specialized to this type of target."
283 :accessor ede-object-menu)
285 "Top level EDE project specification.
286 All specific project types must derive from this project."
287 :method-invocation-order :depth-first)
289 ;;; Important macros for doing commands.
291 (defmacro ede-with-projectfile (obj &rest forms)
292 "For the project in which OBJ resides, execute FORMS."
294 (unless (symbolp obj)
295 (message "Beware! ede-with-projectfile's first arg is copied: %S" obj))
296 `(let* ((pf (if (obj-of-class-p ,obj 'ede-target)
297 (ede-target-parent ,obj)
299 (dbka (get-file-buffer (oref pf file))))
301 (if (not dbka) (find-file-noselect (oref pf file))
304 (if (not dbka) (kill-buffer (current-buffer))))))
306 ;;; The EDE persistent cache.
308 ;; The cache is a way to mark where all known projects live without
309 ;; loading those projects into memory, or scanning for them each time
312 (defcustom ede-project-placeholder-cache-file
313 (locate-user-emacs-file "ede-projects.el" ".projects.ede")
314 "File containing the list of projects EDE has viewed.
315 If set to nil, then the cache is not saved."
319 (defvar ede-project-cache-files nil
320 "List of project files EDE has seen before.")
322 (defun ede-save-cache ()
323 "Save a cache of EDE objects that Emacs has seen before."
325 (when ede-project-placeholder-cache-file
326 (let ((p ede-projects)
327 (c ede-project-cache-files)
328 (recentf-exclude '( (lambda (f) t) ))
332 (set-buffer (find-file-noselect ede-project-placeholder-cache-file t))
334 (insert ";; EDE project cache file.
335 ;; This contains a list of projects you have visited.\n(")
337 (when (and (car p) (ede-project-p p))
338 (let ((f (oref (car p) file)))
339 (when (file-exists-p f)
340 (insert "\n \"" f "\""))))
343 (insert "\n \"" (car c) "\"")
349 (message "File %s could not be saved."
350 ede-project-placeholder-cache-file)))
351 (kill-buffer (current-buffer))
354 (message "File %s could not be read."
355 ede-project-placeholder-cache-file))
359 (defun ede-load-cache ()
360 "Load the cache of EDE projects."
362 (let ((cachebuffer (get-buffer-create "*ede cache*")))
364 (with-current-buffer cachebuffer
366 (when (file-exists-p ede-project-placeholder-cache-file)
367 (insert-file-contents ede-project-placeholder-cache-file))
368 (goto-char (point-min))
369 (let ((c (read (current-buffer)))
372 ;; Remove loaded projects from the cache.
374 (setq c (delete (oref (car p) file) c))
376 ;; Remove projects that aren't on the filesystem
379 (when (file-exists-p (car c))
380 (setq new (cons (car c) new)))
383 (setq ede-project-cache-files (nreverse new))))
385 (when cachebuffer (kill-buffer cachebuffer))
388 ;;; Get the cache usable.
390 ;; @TODO - Remove this cache setup, or use this for something helpful.
391 ;;(add-hook 'kill-emacs-hook 'ede-save-cache)
392 ;;(when (not noninteractive)
393 ;; ;; No need to load the EDE cache if we aren't interactive.
394 ;; ;; This occurs during batch byte-compiling of other tools.
400 ;; The methods in ede-base handle project related behavior, and DO NOT
401 ;; related to EDE mode commands directory, such as keybindings.
403 ;; Mode related methods are in ede.el. These methods are related
404 ;; project specific activities not directly tied to a keybinding.
405 (defmethod ede-subproject-relative-path ((proj ede-project) &optional parent-in)
406 "Get a path name for PROJ which is relative to the parent project.
407 If PARENT is specified, then be relative to the PARENT project.
408 Specifying PARENT is useful for sub-sub projects relative to the root project."
409 (let* ((parent (or parent-in (ede-parent-project proj)))
410 (dir (file-name-directory (oref proj file))))
411 (if (and parent (not (eq parent proj)))
412 (file-relative-name dir (file-name-directory (oref parent file)))
415 (defmethod ede-subproject-p ((proj ede-project))
416 "Return non-nil if PROJ is a sub project."
417 ;; @TODO - Use this in more places, and also pay attention to
418 ;; metasubproject in ede/proj.el
419 (ede-parent-project proj))
422 ;;; Default descriptive methods for EDE classes
424 ;; These are methods which you might want to override, but there is
425 ;; no need to in most situations because they are either a) simple, or
428 (defmethod ede-name ((this ede-target))
429 "Return the name of THIS target."
432 (defmethod ede-target-name ((this ede-target))
433 "Return the name of THIS target, suitable for make or debug style commands."
436 (defmethod ede-name ((this ede-project))
437 "Return a short-name for THIS project file.
438 Do this by extracting the lowest directory name."
441 (defmethod ede-description ((this ede-project))
442 "Return a description suitable for the minibuffer about THIS."
443 (format "Project %s: %d subprojects, %d targets."
444 (ede-name this) (length (oref this subproj))
445 (length (oref this targets))))
447 (defmethod ede-description ((this ede-target))
448 "Return a description suitable for the minibuffer about THIS."
449 (format "Target %s: with %d source files."
450 (ede-name this) (length (oref this source))))
454 ;; Targets and projects are often associated with other files, such as
455 ;; header files, documentation files and the like. Have strong
456 ;; associations can make useful user commands to quickly navigate
457 ;; between the files based on their associations.
459 (defun ede-header-file ()
460 "Return the header file for the current buffer.
461 Not all buffers need headers, so return nil if no applicable."
463 (ede-buffer-header-file ede-object (current-buffer))
466 (defmethod ede-buffer-header-file ((this ede-project) buffer)
467 "Return nil, projects don't have header files."
470 (defmethod ede-buffer-header-file ((this ede-target) buffer)
471 "There are no default header files in EDE.
472 Do a quick check to see if there is a Header tag in this buffer."
473 (with-current-buffer buffer
474 (if (re-search-forward "::Header:: \\([a-zA-Z0-9.]+\\)" nil t)
475 (buffer-substring-no-properties (match-beginning 1)
477 (let ((src (ede-target-sourcecode this))
479 (while (and src (not found))
480 (setq found (ede-buffer-header-file (car src) (buffer-file-name))
484 (defun ede-documentation-files ()
485 "Return the documentation files for the current buffer.
486 Not all buffers need documentations, so return nil if no applicable.
487 Some projects may have multiple documentation files, so return a list."
489 (ede-buffer-documentation-files ede-object (current-buffer))
492 (defmethod ede-buffer-documentation-files ((this ede-project) buffer)
493 "Return all documentation in project THIS based on BUFFER."
494 ;; Find the info node.
495 (ede-documentation this))
497 (defmethod ede-buffer-documentation-files ((this ede-target) buffer)
498 "Check for some documentation files for THIS.
499 Also do a quick check to see if there is a Documentation tag in this BUFFER."
500 (with-current-buffer buffer
501 (if (re-search-forward "::Documentation:: \\([a-zA-Z0-9.]+\\)" nil t)
502 (buffer-substring-no-properties (match-beginning 1)
504 ;; Check the master project
505 (let ((cp (ede-toplevel)))
506 (ede-buffer-documentation-files cp (current-buffer))))))
508 (defmethod ede-documentation ((this ede-project))
509 "Return a list of files that provide documentation.
510 Documentation is not for object THIS, but is provided by THIS for other
511 files in the project."
512 (let ((targ (oref this targets))
513 (proj (oref this subproj))
516 (setq found (append (ede-documentation (car targ)) found)
519 (setq found (append (ede-documentation (car proj)) found)
523 (defmethod ede-documentation ((this ede-target))
524 "Return a list of files that provide documentation.
525 Documentation is not for object THIS, but is provided by THIS for other
526 files in the project."
529 (defun ede-html-documentation-files ()
530 "Return a list of HTML documentation files associated with this project."
531 (ede-html-documentation (ede-toplevel))
534 (defmethod ede-html-documentation ((this ede-project))
535 "Return a list of HTML files provided by project THIS."
539 ;;; Default "WANT" methods.
541 ;; These methods are used to determine if a target "wants", or could
542 ;; somehow handle a file, or some source type.
544 (defmethod ede-want-file-p ((this ede-target) file)
545 "Return non-nil if THIS target wants FILE."
546 ;; By default, all targets reference the source object, and let it decide.
547 (let ((src (ede-target-sourcecode this)))
548 (while (and src (not (ede-want-file-p (car src) file)))
549 (setq src (cdr src)))
552 (defmethod ede-want-file-source-p ((this ede-target) file)
553 "Return non-nil if THIS target wants FILE."
554 ;; By default, all targets reference the source object, and let it decide.
555 (let ((src (ede-target-sourcecode this)))
556 (while (and src (not (ede-want-file-source-p (car src) file)))
557 (setq src (cdr src)))
560 (defmethod ede-target-sourcecode ((this ede-target))
561 "Return the sourcecode objects which THIS permits."
562 (let ((sc (oref this sourcetype))
564 (while (and (listp sc) sc)
565 (setq rs (cons (symbol-value (car sc)) rs)
572 (defun ede-adebug-project ()
573 "Run adebug against the current EDE project.
574 Display the results as a debug list."
576 (require 'data-debug)
577 (when (ede-current-project)
578 (data-debug-new-buffer "*Analyzer ADEBUG*")
579 (data-debug-insert-object-slots (ede-current-project) "")
582 (defun ede-adebug-project-parent ()
583 "Run adebug against the current EDE parent project.
584 Display the results as a debug list."
586 (require 'data-debug)
587 (when (ede-parent-project)
588 (data-debug-new-buffer "*Analyzer ADEBUG*")
589 (data-debug-insert-object-slots (ede-parent-project) "")
592 (defun ede-adebug-project-root ()
593 "Run adebug against the current EDE parent project.
594 Display the results as a debug list."
596 (require 'data-debug)
598 (data-debug-new-buffer "*Analyzer ADEBUG*")
599 (data-debug-insert-object-slots (ede-toplevel) "")
606 ;; The toplevel project is a way to identify the EDE structure that belongs
607 ;; to the top of a project.
609 (defun ede-toplevel (&optional subproj)
610 "Return the ede project which is the root of the current project.
611 Optional argument SUBPROJ indicates a subproject to start from
612 instead of the current project."
613 (or (when (not subproj) ede-object-root-project)
614 (let* ((cp (or subproj (ede-current-project))))
615 (or (and cp (ede-project-root cp))
617 (while (ede-parent-project cp)
618 (setq cp (ede-parent-project cp)))
622 ;;; Utility functions
625 (defun ede-normalize-file/directory (this project-file-name)
626 "Fills :directory or :file slots if they're missing in project THIS.
627 The other slot will be used to calculate values.
628 PROJECT-FILE-NAME is a name of project file (short name, like 'pom.xml', etc."
629 (when (and (or (not (slot-boundp this :file))
630 (not (oref this :file)))
631 (slot-boundp this :directory)
632 (oref this :directory))
633 (oset this :file (expand-file-name project-file-name (oref this :directory))))
634 (when (and (or (not (slot-boundp this :directory))
635 (not (oref this :directory)))
636 (slot-boundp this :file)
638 (oset this :directory (file-name-directory (oref this :file))))
644 ;;; Hooks & Autoloads
646 ;; These let us watch various activities, and respond appropriately.
648 ;; (add-hook 'edebug-setup-hook
650 ;; (def-edebug-spec ede-with-projectfile
651 ;; (form def-body))))
656 ;; generated-autoload-file: "loaddefs.el"
657 ;; generated-autoload-load-name: "ede/base"
660 ;;; ede/base.el ends here