Re: Unified project interface

[Stephen Leake <stephen_leake@stephe-leake.org>]

Dmitry Gutov <dgutov@yandex.ru> writes:

> Let's maybe continue this discussion?
>
> On 06/05/2015 01:08 PM, Stephen Leake wrote:
>
>> No, xref-find-regexp should search project-source-directories.
>>
>> Most real projects include other projects, so limiting the search to
>> only the top project is wrong in general (although that might be a
>> useful option in some use cases).
>
> I suppose, and maybe I was wrong to suggest a distinction between
> "source" directories and the rest of them. However, here's one which
> could be better: directories to search vs. directories to modify.
>
> Like, I might want to search the full system includes path, in a C
> project, but when performing a replacement operation (such as
> xref-query-replace), I should probably limit myself to the directories
> with code I actually own. 

Yes, that's a good use case.

> At the moment, it's the distinction I
> imagine for project-search-path vs project-directories.

I would suggest the terminology "main project" vs "included projects"
for this; the "main project" is the code you own; the "included
projects" are all the others (included the system includes).

So this would be an argument to xref-find-regexp;

(defun xref-find-regexp (regexp &optional not-included-projects)
"Search all files in all project directories for REGEXP.
If NOT-INCLUDED-PROJECTS is non-nil (default nil), search only the main
project. Otherwise, search the main project and included projects."

To implement this, project-search-path might want to be an alist of:

(PROJECT-NAME <search-path>)

where the first element is the main project and the rest are the
included ones.

>> In addition, there might be a directory under project root that should
>> _not_ be searched; the object file directory for ada-mode, for example.
>
> We have that in project-ignores now.

Right. That's not consistent with current things like load-path. I
should think at some point in the implementation of any "search project"
function you will want an explicit list of directories (and maybe files)
to search, which will be the union of project-search-path minus
project-ignores. So it seems simpler to specify that list directly.

The user interface (the syntax of the project file) could be structured
as includes and ignores (excludes).

>> We can make [root] a requirement in order to use the general tool. But first
>> we have to justify it; ada-mode has never needed that notion; neither
>> has elisp. In my experience, only config management needs it.
>> ...
>> It also points out that "project root" is poorly defined; I think that
>> is because it's not at all clear when and why we need it.
>
> Here's the first use case I know of:
>
> There's a third-party project called rspec-mode. It allows one to
> switch between a source file and its test, and to run tests in a
> compilation buffer. For both purposes, it needs to determine the
> directory which to build the relative paths against, and in which to
> run the 'rspec' program. Currently, it does a locate-dominating-file
> like routine (looking for Gemfile or Rakefile), but it could switch to
> the project API in the future.

Ok, makes sense.

> You're probably aware of similar tools.

monotone, git, subversion ... :).

Recently I've been playing with Google's Android Studio (shudder; only
to make Emacs do what it does, I promise :). It defines a project root
by a dominating file.

On the other hand, AdaCore GPS (an Ada-specific IDE) defines a project
by a project file that specifies various lists of directories (source,
object, executable); there is no root directory. The project file itself
can be anywhere, it doesn't have to be in one of the listed directories.
That's what Emacs Ada mode does as well.

> So, now we have both project-root and project-directories. However,
> the relationship between them looks murky, from the consumer's
> standpoint. Like, must the former always be included in the latter?

I think they are disjoint concepts. Nothing wrong with keeping both;
some tools will need them, some won't.

> I'm considering removing project-root, and copying a part of Atom's
> API [0]: adding a function project-relativize-path, which will, given
> an arbitrary directory, if it's inside project-directories, split its
> file name in two and return a cons, with one of project-directories in
> the car, and the relative file name against it in the cdr.

If project-directories contains all directories (not just root ones),
this is just (file-name-directory path) . (file-name-non-directory
path).

> Then instead of project-root, a consumer will use (car
> (project-relativize-path default-directory)).

I don't follow; that means the value of 'root directory' changes
depending on where the current file is.

Unless project-directories contains only one directory, which would then
be the root.

Given the variable project-root, it makes sense to define
project-relativize-path to return the portion of the path that is
relative to project-root, and error if there is no such portion (ie an
absolute path outside the root tree). Monotone has such a function in
the C++ code.

-- 
-- Stephe