Re: EDE documentation

On 08/08/2015 05:59 PM, Stephen Leake wrote:
> Eric Ludlam <[email protected]> writes:
>
>> I took a stab at completely revamping the EDE documentation organization.
>>
>> I'd be very interested in peoples thoughts on this organization, and if
>> you think it will help.
>
> I read thru ede.info:
>
> In general, this is a big improvement! It's much easier to understand
> what is going on with project detection.

Thanks!

> In general, there are more `require's needed with the bundled CEDET than
> with CEDET from a SourceForge checkout (accessed with
> cedet/cedet-devel-load.el). It would be better if
> cedet/cedet-devel-load.el mimiced the bundled environment more closely
> (same set of preloads/autoloads), so this issue was clearer to the CEDET
> developers.

I finally got an emacs 25 going, and noticed the same problem when you 
first posted about it.  My intent is to make Emacs core more like what 
is in Source Forge.

> The SourceForge code seems to be currently in transition between Emacs
> 24 and Emacs 25. It contains (require 'cl-generic), which is not in
> Emacs 24 (there is a Gnu ELPA package for it). With Emacs 25, I get
> errors like: eieio-oref: eieio-oref called on a class:
> ede-generic-target-c-cpp. In Emacs 24, cedet/cedet-build.el cedet-build
> gives an error: byte-code: Symbol's function definition is void:
> eieio-make-class-predicate.

Yes.  EIEIO changed a lot in Emacs 25, and David and I seemed to both be 
busy around the same time and couldn't keep up.  ;)

> So in the following comments, I'm using SourceForge CEDET, compiled and
> loaded in Emacs 25 (attempting to ignore the errors). But the comments
> about `require' come from trying to use the bundled CEDET.
>
> - Top node second paragraph
>
>    Using EDE is _not_ as simple as
>    '(ede-minor-mode 1)'; it also needs (require 'ede).
>
>    Perhaps should add ;;;###autoload to ede-minor-mode? and
>    global-ede-minor-mode.

On 08/09/2015 12:43 AM, Stephen Leake wrote:> Stephen Leake 
<[email protected]> writes:
 >
 >>      and if need emacs project type; (require 'ede/emacs)
 >>          same for other project types? not tested with bundled CEDET
 >>          possibly add ;;;###autoload to ede-emacs-load
 >
 > It turns out this is because ede-add-project-autoload is broken in
 > emacs/master bundled CEDET, so it always replaces the first entry in
 > ede-project-class-files. So this is fixed in SourceForge CEDET.
 >

Thanks for identifying that.  The intention is for all these project 
types to be enabled by default.

> - 1.1 What is a project
>
>      suggest: "a project consists of a directory hierarchy, a set of meta
>      data, command features, and a set of targets.
>
>      This section does not mention cross-reference or find-identifier
>      tools, but later it says some are supported (Gnu GLOBAL, for
>      example). So that should be mentioned here.

There is a missing section regarding the commands available in EDE which 
would be good to reference from here.

> - 2 Quick Start - wrapper
>
>      also need (require 'ede) in ~/.emacs
>
>      and if need emacs project type; (require 'ede/emacs)
>          same for other project types? not tested with bundled CEDET
>          possibly add ;;;###autoload to ede-emacs-load

I'd like to fix this.

>      Android project worked (detector has autoload)
>
>      For Arduino projects on Windows, need:
>
>      (setq ede-arduino-preferences-file
>        (expand-file-name (substitute-in-file-name "$APPDATA/Arduino15/preferences.txt")))
>
>      I'm not sure where the "15" comes from; I'm using Arduino 1.6.4.

Thanks, I'll add that.

>      In addition, there's a problem with the Arduino auto-detect on
>      Windows; the sketchbook directory has \ in preferences.txt, but it
>      is compared to buffer-file-name, which has /. So ede/auto.el
>      ede-do-dirmatch needs an 'expand-file-name' in (setq matchstring
>      ...). I didn't actually edit the code and test, because I'm not sure
>      that change is ok in general.

Expanding the file seams reasonable since most tests are just 
(file-exists-p) which is vaguely similar.

I did this and it passed all my tests on Linux.

--- a/lisp/cedet/ede/auto.el
+++ b/lisp/cedet/ede/auto.el
@@ -64,10 +64,11 @@ into memory.")

  (defmethod ede-calc-fromconfig ((dirmatch ede-project-autoload-dirmatch))
    "Calculate the value of :fromconfig from DIRMATCH."
-  (let ((fc (oref dirmatch fromconfig)))
-    (cond ((stringp fc) fc)
-	  ((functionp fc) (funcall fc))
-	  (t (error "Unknown dirmatch object match style.")))
+  (let* ((fc (oref dirmatch fromconfig))
+	 (found (cond ((stringp fc) fc)
+		      ((functionp fc) (funcall fc))
+		      (t (error "Unknown dirmatch object match style.")))))
+    (expand-file-name found)
      ))

>      The list of Wrapper Projects is longer here than in the Wrapper
>      Projects section; I guess there is more manual to be written.

Thanks for pointing that out - The Java ones (ant, maven, etc) are 
missing a section.  The automake project type wasn't user focused and 
got deleted, so it needs an updated section. I'll get that started.

The compdb stuff is in a separate section.

>      It would be good if there were a menu item that displayed a list of
>      the project types currently auto-detected. That is simple to extract
>      from ede-project-class-files.
>
>      Then this section can say:
>
>      "To see the list of supported generic projects, invoke the menu
>      Development | Project Options | Show auto-detects"
>
>      I don't have examples of all of the project types listed, so I
>      couldn't test all of them.

You can do:

C-h v ede-project-class-files RET

but i get your meaning.  Lisp struct dump isn't so helpful.  Here's a 
handy way to explore:

(defun ede-show-supported-projects ()
   "Display all the project types registered with EDE."
   (interactive)
   (data-debug-new-buffer (concat "*EDE Autodetect*"))
   (data-debug-insert-stuff-list ede-project-class-files "* "))


> - 8 Managed Projects
>
>      This section needs an intro; what is a "managed project", and why
>      would I choose this over the other options? How is this different
>      from section 7?

Thanks for pointing that out.  I can put in a bit of motivation.

>      I think this section is about adding an EDE project to an existing
>      source tree that does not match one of the wrapper patterns.
>
>      ede-new prompts for a "Name: "; the info file should say how it will
>      be used.
>
>      It then adds the project directory to the custom variable
>      ede-project-directories; the info section should say that.
>
>      I tried to do these steps.
>
>      ede-new worked
>
>      when I tried to do ede-new-target, there was no Project Options
>      submenu. M-x ede-new-target worked.
>
>      add file: there is a Development | Target Options | Add File menu
>      entry, but it complained "wrong file type"; apparently you can't mix
>      file extensions? On the other hand, I have no idea what file type it
>      was expecting; that should be in the error message.
>
>      (I'll just keep writting my Makefiles by hand :).
>
>      When I restarted Emacs (I had some edebug stuff that just broke),
>      the new project was not automatically recognized. I think I know
>      why, but the info did not say anything about that. So I tried
>      Development | Load Project, and Emacs crashed.
>
>      More later, after I debug that crash.

I didn't updated these sections, and it seems like some of the workflow 
is a bit broken.   I pushed a ton of workflow testing into CEDET's 
interactive test suite, so I know it works, but that tests commands, not 
the menus.  It seems like some interactive testing/debugging is needed.

My experience is that most folks would rather write their Makefiles by 
hand, and that EDE still needs a good level of Makefile understanding to 
use, so it doesn't help as much as it should.

> - 10 Misc
>
>      ede-find-file does not do completion on the file name. I looked at
>      the code; it looks complicated, because of the locate objects. Emacs
>      has very nice file name completion now, so it would be good to
>      improve this. The Emacs filename completion takes a flat list of
>      directories (like load-path or compilation-search-path), so we'd
>      have to construct that out of all the locate objects. I'll look into
>      it more.

The location system is pretty old and it delegates to external tools. 
Newer systems like what you suggest I'm sure would be better.

All the objects do is abstract away the different tools so EDE can ask 
where some file is.  Most usage of this is not related to users asking 
to visit a file, but for a tool to move to a file based on a short-name 
reference, so completion was never a priority for me.

> 11 - not read, since it says it needs work. But I'll get back to it later

Since this section was originally written, EDE as become more about 
creating wrapper projects than managed projects.  There is some useful 
stuff in there, but it has the wrong focus.

Thanks for all the feedback.
I pushed a small related batch of changes.

Eric



------------------------------------------------------------------------------