Re: project.el semantics

[Dmitry Gutov <dgutov@yandex.ru>]

On 11/08/2015 09:11 AM, Stephen Leake wrote:

> These are inconsistent.
>
> It would be best for the project-library-roots-function doc string to
> _only_ refer to cl-defgeneric (ie, "default implementation of
> `project-libary-roots'"), so you don't have duplicate documentation that
> gets out of sync.

It would be impossible for project-library-roots-function to implement 
the "outside of the current project" part of semantics, unless we pass 
it the current project.

And then, what's the point? It's just as easy to call 
project-subtract-directories from the default project-library-roots impl.

Any other inconsistencies? (I've pushed a minor update now, but it's 
probably unrelated to your concerns).

> You seem to be trying to establish a difference between "a single
> project" and "the libraries used by a project". Better terminology would
> be "top level project" and "dependencies"; not all dependencies are
> libraries. It would be helpful to make this distinction more explicit.

I think we might want to introduce the notion of project dependencies 
later, and then we'd have to call some of library-roots, again, library 
roots, to distinguish from the dependencies.

Better to defer that change.

Note that you currently have the freedom to include the checked out 
dependent projects in the project-roots (if you edit these projects 
together).

> The default implementation of project-library-roots makes the lists
> disjoint, so the doc strings should say that.

Doesn't it? It says "outside".

> In particular,
> "load path" and "class path" contain _both_ the top level project and
> the dependencies, so project-library-roots should _not_ be the same as
> "load path" or "class path".

I think "list of directories outside of the project" is pretty clear.

> The advice in project-roots on "include here but not there" should
> mention top-level vs dependencies.

Could you rephrase that? I'm not sure I follow.

> On the other hand, `project-library-roots ((project (head vc))' does
> _not_ make them disjoint, so there is a bug here somewhere.

Fixed, thanks for pointing that out.

> The new function `project-find-regexp' is not consistent with other
> usage; other project- search functions search both top level and
> dependencies.

Sorry, what other project- search functions? Do you mean 
xref-find-references?

Note that we also have project-or-libraries-find-regexp. IME, when doing 
a regexp search across the project, you aren't interested in the library 
code, most of the time.

>> Also see the FIXME commentary above project-library-roots-function;
>> it's waiting for the public opinion. Though it's not really about
>> source vs documentation as much as about different kinds of sources.
>
> That FIXME: says, in part:
>
> ;; FIXME: Using the current approach, we don't have access to the
> ;; "library roots" of language A from buffers of language B, which
> ;; seems desirable in multi-language projects, at least for some
> ;; potential uses, like "jump to a file in project or library".
>
> emacs-lisp-mode makes project-library-roots-function buffer-local,
> which makes it language-specific. That's an argument for overriding the
> default implementation of project-library-roots to do something more
> useful. Which is what `project-library-roots ((project (head vc))' does,
> for example. Which means that the behavior of projects in an elisp file
> that happens to be in a vc directory is different from one that is not.

`project-library-roots ((project (head vc))' knows nothing of library 
roots, however, aside from the local variable that's supposed to be set 
by the user.

> No other language mode sets project-library-roots-function.

There is etags-library-roots, however. It's not language-specific, but, 
again, vc-project doesn't know about it.

There is also ruby-library-roots already brewing in my head.

> The root cause of this problem is trying to infer a project in an elisp
> file. This makes sense in general, because an elisp file implies the use
> of load-path, which is the main part of defining a project. A better way
> is to provide a project-find-function that returns an elisp-project
> object in elisp buffers;

That implies having to create a separate project implementation for 
every language, making vc-project utterly useless.

You'd also have to create yet-another kind of project implementations, 
for multi-language projects.

Note that determining whether the a given directory tree has Elisp files 
inside is not 100% reliable, outside of traversing it whole. But if we 
pick some detection mechanism, (and we'd have to, for Elisp-project 
detection), we can just as well use it to call elisp-library-roots 
globally and make it auto-detect whether the current project is 
applicable. Like described in the FIXME.

> then elisp-project can override
> project-library-roots to return load-path; it could also add the emacs C
> sources if they are available.

At the moment, I feel that this approach would be a cop-out. But it's 
definitely an option.

> That leaves the default behavior in non-elisp files that are also not in
> a vc directory; they currently use 'etags-library-roots. You could
> change the default definition of project-library-roots to use
> etags-library-roots directly, but it seems better to have a variable for
> this.

I don't think we ever call project-library-roots-function from anywhere 
but project-library-roots (*). And that requires the presence of the 
current project.

> I would delete the advice that overriding functions should use
> project-library-roots-function; the main reason to override is to do
> something different.

(*) Hence, if we go your way, there seems to be no need for 
project-library-roots-function.

> I have no problems merging this branch to master; it makes things better
> in most places, and no worse in any. Howver, it would be best to clean
> up the inconsistencies above first.

Thanks, I'll merge after your next reply.