Re: project.el semantics

[Stephen Leake]

John Wiegley <address@hidden> writes:

>>>>>> Dmitry Gutov <address@hidden> writes:
>
>> 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. :(

Previouslyl, we have said that a project.el object is not a replacement
for EDE projects. It makes sense for project.el to be used as a wrapper
for EDE projects.

The project.el header says it fairly well:

;; This file contains generic infrastructure for dealing with
;; projects, and a number of public functions: finding the current
;; root, related project directories, search path, etc.
;;
;; The goal is to make it easy for Lisp programs to operate on the
;; current project, without having to know which package handles
;; detection of that project type, parsing its config files, etc.

EDE can be used as a project.el backend, to do the "detection of project
type, parsing its config files, etc".

projectile could be another backend.

elisp packages that interface with build tools like ant or maven could
be other backends.

Then higher level code, like locate-file or xref-find-definition, can
use the project.el API to access project features. Mostly search-path,
at the moment; the intent is that there be other project features in the
future.

> 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
> meaning; and *outside* the project (say, in "/usr/include"), that are likewise
> distinguished directories and file subsets with common meaning.
>
> 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, 

Yes, I think roots (more precisely, a list of roots and ignores, or an
explicit list of directories like `load-path') is a proxy for the
project fileset.

> and a way to identify which project (perhaps multiple!)
> that a given buffer is associated with.

Yes; that's project-current.

> A fileset could be defined as:
>
>     Everything within a directory
>     Everything within a directory tree
>     Everything within a directory or tree matching a predicate

or:

      Everything within the directory trees on a path

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

That's not the most general case; that's just one particular project
backend; the vc backend.

Other project backends, for EDE or gradle, will have other ways of
defining the filesets.

I'm working on implementing a couple of these, but I don't seem to be
moving very fast on it.

> Filesets in turn have an extensible set of attributes:
>
>     Is the file part of the project, or external to it?

There are actually three categories:

- member of the top level project

- member of a dependency of the top level project

- everything else

So, if "the project" is defined as "all elisp files on load-path", then
foo.c is in "everything else", even if it is in a load-path directory.

>     Is it under version control?

Emacs already has a standard API for version control, but it might make
sense to wrap it in a project metadata structure.

>     Is it a build product?

That would be useful.

>     Should it be searched, tagged, presented in various contexts, etc.?
>       (This itself might be an extensible sublist)

Some of this can be a permanent attribute of the file, but it depends on
the context. As I pointed out in another message, some contexts (like
"refactor foo") are transient, and defined by the user, not the fileset.

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

Better, "definable by the backend". I reserve "user" in this case for
the person that is running the code that uses project.el. The project
backends define what attributes the project filesets can have.

But maybe you meant something like "the user writes the project files
that the build tool uses" and which the project backend uses to define
what the project is; that's true.

> and may look nothing like what we presently have in mind. 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.

Right; clearly a compilation buffer should be associated with a project.
Currently, since project-current uses directory-based project detection,
this works well. EDE relies mostly on directory-based detection as well.

I prefer letting the user specify a single active project; that way the
same search path is used no matter what buffer a search is started from.
That's partly because that's what the ada-mode code does (I maintain
ada-mode, and used it extensively at NASA); I'm trying to see what
advantages there are to a more fragmented project approach.

-- 
-- Stephe