Re: project.el semantics

[Stephen Leake]

Dmitry Gutov <address@hidden> writes:

> 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".

In general? for the search path? why?

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

What are the use cases for having so many choices of search path:

top level project
libraries
other dependencies

?

> 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.

>> "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.

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

>
>> 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".

Which implies that managed project dependencies (which can be edited) go
in project-roots, so it is not just top-level.

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.

>>>> 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". 

So what would be wrong with including both ways of describing it, so
more people understand what is wanted?


> 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.

>> 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.

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.

Not that it will matter very much; most uses
will always search both project-roots and project-library-roots.


>> 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.

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.

>> 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.

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

xref-collect-references would be better named
xref-semantic-find-references; it is a semantic implementation of
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.

And points out that the predefined interface doesn't allow choice of
path. So providing a choice of path via project-roots and
project-library-roots is moot; there is no way for the user to take
advantage of that.

> 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?

If you think people will actually want to have a choice of paths, yes,
that is where it needs to be.

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.

 >>> 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.

That's changing the API, which is a different approach than taking
advantage of the current API.

> Should I write a proof-of-concept?

Sure, but not before this merge, and probably not before the feature freeze.

> 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.

project.el can support both styles, of course.

>>> 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. 

And yet you are fine having it depend on the "current language"; where
does that come from?

> Only on the current directory. 

I include multiple language source files in one directory.

> Or be picked explicitly by the user (not implemented), and be
> "current" for the whole Emacs session.

Always a good choice ;).

>>> 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. 

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

-- 
-- Stephe