Installing emacs C source code and info

Installing emacs C source code

As mentioned in Getting started, emacs packages, the emacs comment describe-function gives links to the implementation of function, even if it is coded in C.

To take advantage of this you need to download the emacs source code for the version of emacs you are using, e.g. emacs-28-2.tar.xz. Unpack that file and place it somewhere, for example ~/emacs_src/emacs-28-2/; and when emacs prompts for "Emacs C source dir: ", tell it ~/emacs_src/emacs-28-2/src/. Alternatively one can directly set the variable:

(setq find-function-C-source-directory "~/emacs_src/emacs-28-2/src/")

For example try running describe-function on make-list. The link will take you to:

DEFUN ("make-list", Fmake_list, Smake_list, 2, 2, 0,
       doc: /* Return a newly created list of length LENGTH, with each element being INIT.  */)
  (Lisp_Object length, Lisp_Object init)
{
  Lisp_Object val = Qnil;
  CHECK_NATNUM (length);

  for (EMACS_INT size = XFASTINT (length); 0 < size; size--)
    {
      val = Fcons (init, val);
      rarely_quit (size);
    }

  return val;
}

In the file alloc.c.

Installing (additional) emacs info pages

The emacs src tarball includes documentation in info format. If you are running linux, your system probably already has some info files, which the operating system finds by looking at the paths in the environment variable "INFOPATH". To include the info files in the src tarball, just add that path. So for example, if you expanded the emacs source files in the directory /home/joe/emacs_src_emacs-28.2/ then add /home/joe/emacs_src_emacs-28.2/info to the environment variable "INFOPATH". So on linux the result might be something like:

/usr/share/info/emacs:/usr/local/share/info/:/usr/share/info/:/usr/local/texlive/2021/texmf-dist/doc/info:/home/joe/emacs_src_emacs-28.2/info

The environment "INFOPATH" is used not only by emacs, but also by standalone info documentation readers. If your system does not use "INFOPATH", or you only want emacs to see the additional info files you can directly set the elisp variable Info-directory-list instead. See explanation on emacswiki.org.

You also need to update the info page dir file which serves as a top level list of links to info nodes. To do that on linux (maybe elsewhere too?) you can use a command line tool named install-info.

Here I share how I did that with linux. First, to determine where the dir file is, I entered the emacs command info to go to the *info* buffer and then ran the pwd command to see what directory is associated with the *info* buffer found it to be /usr/share/info/ (on my system, could be different for you). Indeed I did find a file there named /usr/share/info/dir. The contents of *info* are a processed version of contents of this file. The /usr/share/info/dir was owned by root and users only had read permission, so I added write privileges.

% sudo chmod 666 /usr/share/info/dir

Then I used cd to move to the directly holding the info files I wanted to install; /home/joe/emacs_src_emacs-28.2/info in our running example. That directly holds info node files such as calc.info, elisp.info, etc.
To install them I used the bash shell loop:

% cd /home/joe/emacs_src_emacs-28.2/info
% for f in *.info; do install-info $f /usr/share/info/dir; done

(Of course some systems may use a different directory than /usr/share/info/dir With your path set you can use the emacs command info to view your info pages. At the menu try pressing m and entering "info" at the prompt. With luck you will find yourself reading documentation describing how to browse info pages. After that I would suggest looking at the "Emacs", "Elisp Lisp Intro" pages.

At first info may seem unnecessarily complicated to setup, and you may not want to spend time learning how to browse it. In my experience however it is well worth it. I still often consult the "Elisp", "CL-Lib", and "Calc" info pages.

Note you can easily have multiple buffers for reading various info pages open at the same time. After invoking info, just use rename-buffer to change the buffer to another name, such as *info-emacs-manual*, *info-elisp-manual*, *info-calc-manual*, etc. Then you can use switch-to-buffer to revisit the most recent page you looked at in whichever set of info pages your want.