Re: project.el semantics

[Dmitry Gutov]

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

> I don't understand; you seem to be saying a "library" is _not_ a
> "dependency". That's not consistent with common usage.

I'm saying we'd probably want to treat "managed project dependencies" 
differently from "library dependencies".

And if we were to introduce a "dependencies" accessor, I think it would 
return a list of projects, not directories.

> "Dependency" includes system libraries, other managed projects, and
> anything else the user wants to search.
>
> Why do you insist on the less general term?

Because it's a less loaded one. 
http://www.jetbrains.org/intellij/sdk/docs/reference_guide/project_model.html 
also uses the term "library" in a similar fashion, so I think it will be 
clear enough.

> The user has the freedom to do whatever they want. The point is to have
> clearly defined semantics, so the user at least knows what the intent of
> each of these functions is.

For now, the distinction is "you want to edit this" vs "you don't want 
to edit this".

> > > The default implementation of project-library-roots makes the lists
> > > disjoint, so the doc strings should say that.
> >
> > Doesn't it? It says "outside".
>
> True; but I did not understand what you meant by that; it's not common
> project terminology. I think "dependency" is much more widely
> understood.

I'm using "outside" as "directory terminology". We seem to approach this 
from different directions: I think that the user first decides what 
their "project roots" will be, and *then* designates a certain set of 
directories that also contain related files, as "library roots".

> > I think "list of directories outside of the project" is pretty clear.
>
> You have two data points on this; insisting that yours is the only one
> that matters is simply not helpful.

Yes, sorry. You repeated the complaint, so I just repeated the answer.

> It would be helpful if others would contribute here.

Absolutely. I keep waiting for more people to join the discussion at 
this level of detail.

John, would you like to weigh in? This is one of the issues we'd might 
want to decide on before the freeze.

> Suggested rewording:
>
>    "Return the list of directory roots belonging to the current project.
> This excludes project dependencies.

But do we want to exclude project dependencies, always? This might 
contradict the third paragraph: sometimes, you edit certain dependencies 
together with the project.

> Most often it's just one directory, which contains the project
> file and everything else in the project.  But in more advanced
> configurations, a project can span multiple directories.
>
> One rule of thumb for whether to include a directory here, and not
> in `project-library-roots', is whether its contents are meant to
> be edited together with the rest of the project.
>
> If a directory contains a separate project, it belongs in
> `project-library-roots'.

As stated, I'm not sure about this.

> Functions that use project-roots and/or project-library-roots:
>
> elisp--xref-find-references         both
> etags--xref-find-references         both

These are different implementations for the same command: 
xref-find-references.

> project-find-regexp                 only project-roots
> project-or-libraries-find-regexp    both
>
> (I thought there were more; I guess I was thinking of my own code)
>
> It is reasonable to provide a way to control what paths are searched,
> but this is cumbersome and inconsistent.

Inconsistent, yes. Somewhat. If we're walking about the last two, how 
would you change them? Rename to project-without-libtaries-find-regexp 
and project-find-regexp?

IME, the former will be the one that the user will prefer most of the time.

> Hmm. There's a "TODO" in etags--xref-find-references that says it
> should be merged with elisp--xref-find-references; it's the same code.
> So one solution would be to delete those two, and provide a new
> function:
>
> (defun project-find-references (symbol &optional paths)

I'll get around to it in a short while, but the idea is that the 
xref-find-references implementation based on project+grep is just the 
default one (and it will be one function). There will also be different, 
more specialized implementations possible, and the entry point for all 
of these is still going to be called xref-find-references.

> "...
> PATHS is one of:
> 'top-level    - only the top-level project
> 'dependencies - only the dependencies
> 'both         - both (the default)"
>
> and change project-find-regexp to match.
>
> Or provide project-find-references and
> project-or-libraries-find-references.

This kind of goes against the idea of providing an implementation for 
the predefined interface.

So, yes, etags--xref-find-references searches both the project roots and 
the libraries, and ideally the user would choose, but I'm not sure where 
to ask them. Should we expose these semantics in the 
xref-find-references interface somehow?

> > That implies having to create a separate project implementation for
> > every language, making vc-project utterly useless.
>
> Only for languages that imply a path of some sort. In which case that
> path is more useful than using "path = vc root".

Most languages do, I think.

> vc projects are useful in situations where there is neither a language
> defined path nor a build system project file that defines a path. That's
> pretty rare for me, but they are not "utterly useless".

All right, I can understand this viewpoint.

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

Not really. If the is a hook that will return library roots for 
different languages, a given project implementation can use them all. 
Should I write a proof-of-concept?

Where I come from, it's common enough to have several "project files", 
so to speak, at the top of a project, coming from different languages. 
For instance, having both Gemfile and package.json.

> > Note that determining whether the a given directory tree has Elisp
> > files inside is not 100% reliable, outside of traversing it whole.
>
> I didn't say anything about "directories with elisp files"; just about
> elisp-mode.

I don't think we should have "current project" depend on the current 
buffer. Only on the current directory. Or be picked explicitly by the 
user (not implemented), and be "current" for the whole Emacs session.

> > 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.
>
> That's what EDE does; we should improve that rather than duplicate it.

Not really. EDE chooses from a list of applicable project 
implementations. It has no hooks for "libraries", AFAIK.

> I am proposing something much simpler; a project-find-file that uses the
> mode of the current buffer to help pick the project.

I dislike that. The project should be the same, whether we're visiting 
an .el file, or the README file beside it.

> > At the moment, I feel that this approach would be a cop-out.
>
> How is it worse than the current cop-out of setting
> project-library-roots-function in elisp-mode?

Not worse, it's just bad on its own.

project-library-roots-function being buffer-local is a problem. Hence 
that FIXME. And hence the proposals to improve it that I've written in 
the previous two messages (one of which you haven't replied to yet).