[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: project.el semantics

From: Dmitry Gutov
Subject: Re: project.el semantics
Date: Wed, 11 Nov 2015 23:46:49 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:42.0) Gecko/20100101 Thunderbird/42.0

On 11/11/2015 07:22 PM, John Wiegley wrote:

It's supposed to be a generic replacement for the top-level EDE ede-project
class, more or less.

Except I don't know what that is. :(

ede-project is defined in lisp/cedet/ede/base.el. I think its defclass declaration is all that you need to know for this discussion.

It's the top parent of any EDE project. If someone wants to write a command acting on the current project, and they want it to work on any kind of EDE project, they would have to use the info that ede-project provides.

Those are outside. Does "external to the project" sound better?

Ah, I think so, yes. "Ancillary roots" might be even better.

I meant "external to the project" instead of "outside the project", of course. In the project-library-roots docstring. But you seem to mean a rename, right?

Do you really think "project-ancillary-roots" is better than "project-library-roots"? The word "ancillary" doesn't mean anything (or it can mean basically anything). "Library" at least evokes some associations.

Since you both don't understand the few sentences that seem clear to me, I'm
apparently an utter failure of a technical writer. Which is not terribly
surprising, considering it's my second language.

I don't mean to criticize your writing. It's hard to speak at the level of
precise specification.

Yet by now I've spent a gargantuan amount of time writing these emails, as well as comments and docstrings in project.el. If reading them doesn't make things clearer to other people, maybe I should take up another, more productive hobby.

I honestly expected an "I see what you mean", or at least some targeted questions about the sentences I've already written. Not "I still don't understand what X and Y means".

Not "within the project", but related to the project. Does the term
"library" sound familiar?

OK, this is starting to make more sense now. So, you're saying that *within* a
project there are both distinguished directories, and file subsets with common

A project consists of directories. Most often, it consists of just one directory, but there are odd configurations where it's spread over several directories (Stephen gave some examples). It's not hard to support that case, so it's "project roots" now, instead of "project root".

We've not reached the stage where we want to group different kinds of files within the project somehow, yet. But we have project-ignores, so you might say it splits files into two groups (ignored and not).

and *outside* the project (say, in "/usr/include"), that are likewise
distinguished directories and file subsets with common meaning.

Yes. And `project-library-roots-function' docstring mentions "headers search path, load path, class path".

What we may want to do is avoid the concept "root" entirely, and talk instead
about general "filesets": That is, every "project" would have 0 or more
associated filesets, and a way to identify which project (perhaps multiple!)
that a given buffer is associated with.

That suggestion seems orthogonal. Does "project library filesets" sound more clear to you than "project library roots" or "project library root directories"? Does the difference between "project library filesets" and "project filesets" become more apparent?

The names ending with "-roots" mean the elements of the returned lists are treated in a recursive fashion (everything within each of project roots, including subdirectories, belongs to the project).

A fileset could be defined as:

     Everything within a directory
     Everything within a directory tree
     Everything within a directory or tree matching a predicate

In the most general case, a fileset is determined by whatever function the
user provides in .dir-locals.el.

What function? Each user will have to write a function now?

I'm happy to discuss patches along these lines, but please note that you're proposing to drastically increase the API's complexity, and you're not solving any of what I see as the two immediate problems (and the "feature freeze" is the day after tomorrow):

- The disagreement around what "library roots" means (or library filesets, etc). And whether we should have that in the API.

- Dealing with "library roots" for projects with multiple source languages inside, in an automatic fashion, without a combinatoric explosion of project backends. This is the first FIXME in project.el talks about. Would you like to comment on it?

Filesets in turn have an extensible set of attributes:

     Is the file part of the project, or external to it?
     Is it under version control?
     Is it a build product?
     Should it be searched, tagged, presented in various contexts, etc.?
       (This itself might be an extensible sublist)

I'd expect to see a justification for each of these features.

"Under version control" - this question is answered by VC. Why would we have that in the project API?

"build product" - why not simply ignore those using project-ignores?

"Should it be searched, tagged, presented in various contexts" - that description sounds like a pony.

This way we can talk in general terms, and not about concrete roots or
directories. In the most abstract case, the notion of "project" should be
entirely definable by the user, and may look nothing like what we presently
have in mind.

The more flexible the API allows every project to me, the more trouble, in general, the consumers of the API are going to have with it.

Example one:

You want to have "filesets" instead of simply directories. We'll have a new data structure to decide on, and the API consumers will have figure out what filesets are, and how to work with them. Directories are trivial in comparison.


You want filesets to be allowed to include only immediate directory contents, or the contents of the whole directory tree.

That means that any consumer will have to handle both of these cases. E.g. xref-collect-matches will have to use two different code paths to handle both recursive and non-recursive traversals.

As we've discussed with Stephen previously, a "directory to traverse non-recursively" is equivalent to "directory to traverse recursively, but ignoring all its subdirectories", and the second part can be implemented via project-ignores (that lists all subdirectories of the directory in question). That results in just one code path in all consumers.

Stephen still wanted to support both recursive and non-recursive traversals explicitly, so if you both insist on that, I guess I will give in.


Allowing "Everything within a directory or tree matching a predicate" means, I believe, that searching through the fileset won't be possible to implement with just one find+grep call. If that involves calling the predicate at each directory level, that is.

It's even possible that a buffer without an associated file, say
a *Compilation* buffer, could momentarily be considered part of a project, and
as a candidate for cross-buffer searching within that project.

And that feature would mean that one can't implement searching through the project with find+grep at all. Do you consider it valuable enough, to give up on that simplicity?

reply via email to

[Prev in Thread] Current Thread [Next in Thread]