Re: project.el semantics

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

John Wiegley <jwiegley@gmail.com> writes:

> For convenience, the DEFINITION can often be determined from context, such as
> by querying Git or VC.
>
> For convenience, the SELECTION can often be reduced to small set of options,
> such as "all file paths" or "files and directory roots".
>
> For convenience, the QUERY can be reduced to a set of possibilities, like
> "source code", or "ignored files", or "library files", etc.
>
> While the surface API might encode these conveniences as short-hands for what
> are likely to be common uses, the underlying API should allow the general form
> of a rich query. The project is, in a sense, a database of entities, and it's
> hard to pre-determine all possible useful queries of such data.
>
> How these conveniences are implemented is completely open; `cl-defgeneric'
> methods that encode the QUERY&SELECTION against an auto-determined DEFINITION
> is just fine, and is how project.el is written today.
>
> What is presently missing is the lower-level query API, and the freedom to
> specify the DEFINITION, QUERY and SELECTION in more flexible ways.
>
> *That said*, I'd be willing to postone such an API until a future version,
> since, from the user's perpective, it could be seen as an implementation
> detail behind the convenience APIs.
>
> So maybe this has come full circle, but if so, I hope it adds some clarity.

Yes, I like this description.

We are left with what set of convenience functions to implement in 
Emacs 25 project.el.

We don't have a good process for determining that.

I think it would be helpful to go back to one of your original
suggestions, and collect a list of requirements for what we want
project.el to be able to do.

To that end, here is what the project features of ada-mode provide; they
are all candidates for what project.el could provide:

- Set `compilation-search-path' so `next-error' works correctly with
  compilation results. This is a non-recursive list of project
  directories, since the compiler default settings do not include the
  directory in the error messages.

  Some language compilers include the full directory in the error
  messages, so `compilation-search-path' is not needed at all; some
  include a relative path, so only the roots are needed.

- Set `ff-search-directories' and other `ff-' variables so
  `ff-find-the-other-file' works correctly, both for body/header files
  and for "with" (similar to C "include").

  For Ada, C, C++, `ff-search-directories' is a non-recursive list of
  project directories. For Java, it may be only the project roots (the
  core Emacs java-mode does not make this work for Java 'import').
  
- Set the xref backend so M-. finds multiple language definitions, and
  M-? finds multiple language references. (ada-mode does not yet use the
  actual xref.el, but it does the equivalent; the cross reference
  tool supports Ada, C, C++).

- Implement find-file-in-project to find any file included by the build
  tool project definition files, with completion on the file name (not
  the directories).

  The implementation uses `locate-file' with a non-recursive list of
  project directories, as returned by the build tool.

  For other project backends, this could be replaced by a call to an
  external 'find' with directory roots and ignores, or to 'global',
  which has it's own search path.

- Provide a menu of known projects, from which the user selects the
  currently active one.

- Invoke the build tool to build the main executable in the project.

  This assumes there is only one main. I normally don't use this
  feature; I use Makefiles directly since they are much more powerful.
  But others, particularly newbies, find this feature useful.


-- 
-- Stephe