Re: project.el semantics

[Dmitry Gutov]

On 11/09/2015 08:15 PM, Stephen Leake wrote:

> > I'm saying we'd probably want to treat "managed project dependencies"
> > differently from "library dependencies".
>
> In general? for the search path? why?

Not necessarily for the search path. But it would be a different notion, 
so we might as well reserve the name.

> Personally, I've only ever used "project + dependencies" in an Emacs
> search path.

That's totally fine.

> What are the use cases for having so many choices of search path:
>
> top level project
> libraries
> other dependencies

We'll have to see, really.

> > And if we were to introduce a "dependencies" accessor, I think it
> > would return a list of projects, not directories.
>
> You can easily get the project from the directory, and you can easily
> search the directory. So the directory is more useful.

I don't know about that. If you only know the directory, you're at the 
mercy of project-find-functions. If (project-dependencies project) 
returns project instances, however, you're free to choose the right 
project implementation to use for them, set up "parent project" 
references, use some other information from the current project file, 
and so on.

Although again, what will the project dependencies be used for, is still 
an open question for me.

> Well, For my projects, I'll just put all dependencies in the "library"
> path, and move on.

Not a problem.

> > For now, the distinction is "you want to edit this" vs "you don't want
> > to edit this".
>
> Which implies that managed project dependencies (which can be edited) go
> in project-roots, so it is not just top-level.

Oh, so that's what "managed" means. All right; then that means yes, in 
my opinion.

> I don't see the point of making that distinction here; the files in
> non-editable places will be read-only. Non-edit does not imply
> non-search.

In dynamic languages that I've used, the library files are often 
perfectly editable. You just don't want to do that, most of the time.

Another thing you might want to do - replace some term across the 
project (using M-x project-find-regexp and then M-x xref-query-replace). 
If we were to show its occurrences in library files as well, that would 
be a waste of user's and computer's time.

> > I'm using "outside" as "directory terminology".
>
> So what would be wrong with including both ways of describing it, so
> more people understand what is wanted?

I generally try to get away with using as little words as possible when 
describing something, because words can be misunderstood, especially new 
ones, which haven't been used before in the given context (such as 
"dependency").

Since we're discussing project-library-roots here, I'm not sure which 
improvement you mean. How about simply replacing "the list of 
directories outside of the project" with "the list of directories 
outside of the project roots"?

Because if we describe it in terms of dependencies, a dependency might 
be checked out inside a project root subdirectory in certain 
configurations (maybe with an appropriate .gitignore entry, maybe not). 
In that case, though, we probably don't want to have 
project-library-roots include it.

> > 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 don't see how that affects anything.
>
> If I don't know what "project roots" are supposed to be (because the doc
> string is not clear to me), I can't do this.

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

And my point is that if author knows what the "project roots" are, they 
should understand what "project library roots" are, easily. Can we agree 
that the project-library-roots docstring is more or less fine?

> Fine; mention explicitly that some project dependencies should go here,
> if you want to edit them.
>
> The point is that some people will read "library" as "dependency", and
> then do The Wrong Thing.

I do think that occasional misreadings of the spec aren't going to be 
much of a problem, because there's not going to be *too* many project 
implementations.

We can add "So if the project has dependencies which should be edited 
together with it, they should go here as well." to the third paragraph 
of the project-roots docstring. But doesn't it look redundant?

> So provide alternate wording that uses the concepts "separate projects"
> and "dependencies", and says what you want it to say.
>
> People will want to know.

Guess that might go into the manual instead. I've seen someone state 
that it's okay for the manual to have redundancies.

> Right; so project-find-references should be a cl-defgeneric.

xref-find-references will be a cl-defgeneric. Would there be a good 
reason to have project-find-references as well?

Keep in mind that the current Grep-based "find references" are sloppy, 
best-effort implementations. It's not like we expect the users to use 
them when there's any other alternative.

> xref-collect-references would be better named
> xref-semantic-find-references; it is a semantic implementation of
> xref-find-references.

It's a... semantic-symref-tool implementation of it, actually. Which has 
no relation to Semantic grammars, its tags, or etc.

And I'm seriously considering to get away from it and always use Grep, 
because the other tools, while they can be faster, they're also entirely 
opaque to the user, can have outdated databases, non-indexed relevant 
directories, unsupported languages, and so on.

> It's simpler to avoid the whole issue and merge project-roots and
> project-library-roots, at least in this first iteration of the project
> API. Then we can find out if people actually want a choice of paths.

IMO, it's more important to have the distinction between "project roots" 
and "project library roots" in "find regexp" than in "find references".

> > Not really. If the is a hook that will return library roots for
> > different languages, a given project implementation can use them all.
>
> That's changing the API, which is a different approach than taking
> advantage of the current API.

I don't understand. Which API?

> > Should I write a proof-of-concept?
>
> Sure, but not before this merge,

I've merged project-next.

> and probably not before the feature freeze.

Why not? These aren't particularly big changes that I'm talking about.

They're not backward-compatible, however, and I wouldn't want to freeze 
the API in the state that we'll want to change later.

> > 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.
>
> I would merge multiple project files into one Emacs project, not have
> different Emacs projects for each language.

And to do that, vc-project needs to know how to get library-roots from 
each of those project files. From a hook. Right?

> > I don't think we should have "current project" depend on the current
> > buffer.
>
> And yet you are fine having it depend on the "current language"; where
> does that come from?

No, I'm not. The "current project" value cannot depend on the "current 
language" already: the `project-current' contract forbids it.

The only part that can depend on the current language is 
`project-library-roots', and here I am, again, discussing the ways to 
improve that.

> > Only on the current directory.
>
> I include multiple language source files in one directory.

Yessss. Did I mention that I have multiple project files in one 
directory? Naturally, they're from different languages.

> Ok; enhance the FIXME: to say "because some modes make this
> buffer-local" (project.el does _not_ declare it buffer local).

I've pushed a change along these lines.