Re: project.el semantics

[Stephen Leake]

Dmitry Gutov <address@hidden> writes:

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

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

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

"Dependency" includes system libraries, other managed projects, and
anything else the user wants to search.

Why do you insist on the less general term?

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

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

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

You have two data points on this; insisting that yours is the only one
that matters is simply not helpful.

It would be helpful if others would contribute here.

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

Suggested rewording:

  "Return the list of directory roots belonging to the current project.
This excludes project dependencies.

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

The directory names should be absolute.")

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

Functions that use project-roots and/or project-library-roots:

elisp--xref-find-references         both
etags--xref-find-references         both
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.

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

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

Only for languages that imply a path of some sort. In which case that
path is more useful than using "path = vc root".

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

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

That's true anyway.

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

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

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

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

How is it worse than the current cop-out of setting
project-library-roots-function in elisp-mode?

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

No, it's needed for projects that don't have any better way to define a
project path.

-- 
-- Stephe