Re: Difficulty building tree-sitter grammars [was: Help sought from C++ expert: ....]

[Eli Zaretskii]

> Date: Thu, 19 Jan 2023 17:14:43 +0000
> Cc: emacs-devel@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> > > Just as a matter of interest, in c++-ts-mode a treesit-query-error gets
> > > thrown.
> 
> > I don't see any such error.  Maybe this is again your outdated grammar
> > library?
> 
> Heh!  Maybe you're right.  So time to get around to installing one from
> github.  So I look at the Emacs-29 NEWS for instructions on how to do
> this.  These instructions are glib and insufficiently helpful.

Nothing is ever good enough, eh?

> (i) The smallest problem is actually downloading the source of, e.g.,
> tree-sitter-cpp.  github doesn't make it obvious how to download stuff,
> and it took me over 10 minutes to find the GUI thing to activate the
> download.  Then this download was a file.zip.  The instructions don't
> mention that, on GNU, a package called zip is required to unzip this.
> 
> (ii) The instructions glibly say "To compile such a library, compile the
> files "scanner.c" and "parser.c" (sometimes named "scanner.cc" and
> "parser.cc") in the "src" subdirectory of the library's source tree
> using the C or C++ compiler,...".  A Python hacker may well not even
> know that the C/C++ compiler is called "gcc", far less that the
> necessary command line option -c is needed to compile the two source
> files.  Personally, this bit didn't present me any great difficulty.
> 
> (iii) The instructions continue with "..., then link these two files
> into a shared library named "libtree-sitter-LANG.so, ...".  How,
> exactly?  I've guessed that I can also do this with gcc, and need the
> option -o libtree-sitter-cpp.so, but I also need some flags meaning
> "link" and "build a .so" and some standard run-time library besides the
> two object files.  I still haven't worked out what these are.  The
> Python hacker pictured above will be totally lost here.

If you don't know how to do this given what's in NEWS, then I'm sorry,
but these instructions are not for you.  You will have to wait until
someone else (your distro?) produces the grammar library and lets you
download and install it like you download and install all the image
libraries and the rest of the optional stuff for Emacs.

I'm not going to make NEWS a step-by-step tutorial for how to compile
a bunch of files into a shared library.  That is too much to expect
from us.  It is NOT our job to teach people how to do that.

> (iv) Then we have precise instructions on where to put the newly built
> ..so file.  This is good!

This is the only part that is specific to Emacs, so I deliberately
included there all the details, since you are unlikely to find it
elsewhere.

> This process has so far taken me over an hour, which is too long for
> something which should be purely routine.  It is likely to take a
> typical Emacs user even longer.

Typical Emacs users who don't know how to build libraries from sources
will need someone else to do the job for them.  Exactly like they do
with GMP or librsvg or HarfBuzz or any other library that Emacs can
link against.  Eventually, there's no way around this.

> I suggest that these instructions in NEWS should be enhanced with (i)
> Tips on downloading stuff from github; (ii) A sample command line for
> compiling the C/C++ source files; (iii) A sample command line for
> linking these to the needed .so file.  Possibly two or three versions of
> these would be needed for the different environments Emacs runs in.

Sorry, but NO!!