Re: Unified project interface

[Dmitry Gutov]

On 06/08/2015 04:59 AM, Stephen Leake wrote:

> The user; they are the only ones that know what "the project" is.

Let's cut out the user out of the discussion and just say that the 
project system knows stuff. Because it can know everything we want to 
ask the user; we just need to figure out the right set of questions.

> > Will a project-backend "source directories" implementation
> > always cl-call-next-method?
>
> I don't understand this.

If project-source-directories is a generic method, maybe we can say that 
its implementation should almost always (unless it really knows what 
it's doing) call the next applicable implementation.

That implementation could be set up to dispatch based on the value of 
major-mode.

> > Will the default impl simply return the value of some variable,
> > assigned by a major mode?
>
> default implementation of what function?

project-source-directories.

> > "sources" already has a common meaning,
>
> What is that? I take it to mean "any human-readable file". Which thus
> includes README, Makefile, .git/config, etc.

Maybe there's value in allowing this semantic split to (sometimes?) go 
along different lines, but the two main directions I want to see 
commands work are these:

- Search all files that belong to any of the projects we're currently 
interested in.

- Search only some of those files; ones that are likely programmatically 
(semantically?) related to the one we're editing right now.

The latter could have a decent-enough implementation using Grep, but it 
would be better if we could only search directories that are related.

Maybe it's indeed an excessive requirement, though. After all, backends 
can provide their own implementations of "find references" already.

> > and at least in one proprietary editor it's just one a subset of all
> > project files (see the nomenclature here:
> > https://www.jetbrains.com/idea/help/content-root.html).
>
> That gives me 404

That link still works for me. Maybe your email client mangles it somehow?

> We need it to search what the user wants to search; the user needs to be
> able to specify that clearly and easily.

I intend to allow the user to specify the exact directory for 
xref-find-regexp to search, when called with a prefix. However, allowing 
to input an arbitrary set of directories is obviously non-trivial (if we 
want to have an interface that's not annoying).

> If the user specifies compilation-search-path (directly or indirectly),
> and the user wants to be able to search README, then the user must
> include the directory containing README in compilation-search-path.
>
> Is that a problem?

I mentioned compilation-search-path only as an example, though I didn't 
expect that you might suggest putting the project root into 
compilation-search-path.

Anyway, emacs-lisp-mode doesn't set compilation-search-path. And 
hopefully you're not suggesting to put project roots into load-path, 
just to be able to search READMEs.

> > So it would make sense to have a different name (and a different
> > function/slot/etc) for directories that might be reached that way.
>
> I don't follow; can you give more details, and a clear example?

If my java project is in ~/vc/fooberz, then project-directories would be 
'("~/vc/fooberz"), and project-source-directories would be 
'("~/vc/fooberz/src"). That seems obvious enough, so maybe I don't 
understand the question.

> Ah. Now you are talking about one file that mixes source in two
> languages. Yes, that is a problem. There have been discussions here of
> multi-mode files.

It's targentially related, but the difficulties in displaying and 
editing multi-mode files are entirely different from the subject of this 
discussion.

> I have projects that mix Ada and C++; the project level cross reference
> facility handles both, using the current xref API. That works because
> gcc generates the same cross reference info for those two langauages; I
> doubt there is something similar for Ruby and html.

Maybe, or maybe not; but that's not very relevant. If the tool *can* be 
written, the API is manageable. In the meantime, we can use Grep.

> > That's probably not necessary: after all, only the default
> > xref-find-references implementation will use
> > project-source-directories in a naive way. A smarter xref backend
> > should determine itself which directories to search.
>
> I don't see how that is at all possible, especially in the face of
> hierarchical projects.

I suppose all parts of the "hierarchical project" will employ the same 
project definition logic, possibly enabled by the same minor mode. And 
that minor mode might as well implement the specialized xref backend 
that will know where to search.

> Only the user knows what a "project" is; they write the hierachical
> project files that tell the system what the project structure is.

See the beginning of this email.

> You seem to be missing my point; I see no need for project-root, outside
> of configuration management. So I don't see why xref should care about
> "root" at all.

Or you're missing mine.

The distinction I'm (or was) suggesting is not between the root and 
everything else, but between "source directories" and "other directories 
the user might want to search in", and we'll often want to see the 
project's root directory inside the latter list (when not in both).

> > > > On the other hand, after the project root is determined, it might want
> > > > to add some new element(s) to the source directories list.
> > >
> > > "it" is what here ? Can you give an example?
> >
> > Some package that defines that root-finding logic. Not every major
> > mode knows where the relevant source directories are, or it might not
> > know some of them.
>
> As I've said, none of the languages I deal with care about a "root"
> directory. Only git, mtn, cvs care.

Allow me to repeat: "it" is the package that defines the root-finding 
logic. Defines the logic that determines the bounds of the current (and 
possibly linked) project(s).

The act of find the project root directory may sometimes be skipped in 
some odd cases, but otherwise, it'll usually be the first step to 
determining the current project.

> Hmm. Java imposes something like a root by forcing the directory
> structure to match the hiearchical package naming. But referencing other
> package hierarchies complicates that, just as in Ada and C++.

So there'll be several roots. Or project-directories. No big deal.

> > If we've opened one of the files in a third-party Elisp project that
> > hasn't been loaded yet (so not in load-path), a project implementation
> > can still add an element or several to project-source-directories, so
> > that xref-find-references returns somewhat useful results anyway.
>
> What does that have to do with "root"?

The root directory usually, a) contains data about the project 
structure, b) includes files we want to search.

> The third-party elisp file will presumably have some paths in "(require
> ...)" forms that will define a set of directories to be added to
> project-source-directories.

First of all, those forms specify path relative to *any* load-path 
element. We can't add every permutation. Second, I was describing the 
case where the requires load-path element weren't even set yet.

Third, either way it won't include the files that depend on the current 
one. Those are important, too.

> > Or, say, for Ruby: while the major mode might conceivably be taught
> > about paths where to find system-wide libraries, the locations of
> > source files in a given project depend on the project's type, and that
> > must be something a project implementation knows better. Even if it'll
> > simply add the root to project-source-directories.
>
> What "root"? Is that the directory containing the Ruby file that we
> opened?

It's some parent directory of the currently opened file. Probably not 
the direct parent. It's important because it contains files related to 
the current one.

> Why is that a "root" as opposed to just some source directory?

That's a weird question. It's a root of the project. It *is* also one of 
the source directories, in this example.