The first few steps were ok.

:make tags didn't work, first because I wasn't in the src directory.

then once in src/ it wouldn't work because ctags wasn't installed.

so I installed it by doing sudo pacman -Sy ctags.

It worked ok then.

I read through the readme, and :help development. I read about half of the :help buffers.

Tried out a few ctrl-]'s and gf's too.

I opened quickfix.c by placing the cursor on it and typing gf. Had a look through it, couldn't make much sense of it though! Couldn't find the make function either...

So I read up on the :make command, and if I understand correctly it's for compiling from within vim. It compiles what you specify by consulting a make file and if there is an error it shows it and places the cursor on the line of code that caused the error.

I'm only half guessing here though tbh.

So then to find the C routine that implements it, in the README.txt it says

The ":" commands are listed in ex_cmds.h.

So I jumped to ex_cmds.h using gf. I did /make to find make. Then I used ctrl-] to jump to ex_make.

I haven't been able to make much sense of ex_make(eap) yet. The function is used for ":make", ":lmake", ":grep", ":lgrep", ":grepadd", and ":lgrepadd" according to the comment.

And at the start there is a switch statement to figure out which is being used.

I think when :make is run it saves the current buffers to file. If there is an error then it should put the cursor on the line of the error I think. Not sure what other effects it has.

I did a few different lid -Sn eap commands to try and figure out what eap was about. Couldn't really figure it out. I'd guess that it's the location of the command / filename in memory as it's the only argument passed to a lot of the functions.

Starting from the src/README.txt under the Ex command section we can start looking for do_cmdline() or since we know :make is only one command jump stright to do_one_cmd() as mentioned in that section. do_one_cmd will eventually after some parsing and possible recursive calls call ex_make (:make has been replaced by :makeprg by this time).

The buffer will be flushed by the autowrite_all function.

eap is a struct defined in ex_cmds.h:1130 (or around that line depending on version of vim) that hold the arguments for the Ex command.

Now I don't know if it is just me that have not read C in a while but it is quite hard to follow. Thankfully by a mixture of tag jumping, documentation reading and cheating (read other peoples solutions) I came to this conclusion. :(

• use vim to create TAGS: done
• read through the readme: done
• :help development: read it. #1 point - Read documentation first! Made mental note of vim special functions. Will probably have to check that list again. Assumptions section good to note.

• :help buffers: read it. vim -o is great, vim -O is even better for my widescreen monitor.

• :make - gf

• :make uses the quickfix window, reading error messages from the errorfile or buffer. Inspired by the Manx Aztec C compiler for Amiga, error messages are saved to a file/buffer and jumped to one by one.
• ex_make()
• depending on "autowrite" option, changes in current buffer may be written out. If an error file with same name exists it will be deleted. The output of 'makeprg' is saved in the errorfile, which is then read thanks to the setting 'errorformat'
• eap handles mapping of ex functions. the enum CMD_index defined in ex_cmds.h details the available names codes.

probably a few errors in that list, comments much welcome!

• I found this site very helpful: http://vim.wikia.com/wiki/Browsing_programs_with_tags
• how does ":make" work? - ":make ***" eventually executes ex_make() found in 'quickfix.c'. This function executes make *** on the shell.
• what's the name of the C routine which implements it? - the path to ex_make() is the following: main_loop() -> normal_cmd() -> do_cmdline() -> do_one_cmd() -> ex_make()... so it is implemented by do_one_cmd() in 'ex_docmd.c'
• what are the side effects of ":make" on your current files/buffers? - Line 3937 in of ex_make() in quickfix.c calls autowrite_all(). Using Ctrl+] I was able to jump to the function and it is noted to "flush all buffers, except the ones that are readonly". So, the side effects would be that all buffers are flushed (except those that are readonly :).
• Extra Credit: whats that 'eap' argument all about? What is it and what does it contain? - eap is an exarg struct which is used to pass around Ex commands. By using :tag exarg, you can quickly look it up.

If you get the following error when trying to make tags:
rm -f tags
*.c *.cpp if_perl.xs *.h
/bin/sh: arabic.c: not found
make: *** [tags] Error 127
then it is because you haven't run ./configure

• To open the file move the cursor to the filename and press gf (goto file).

• ex_docmd.c:do_one_cmd parses command line and figures out which command to run.

• ex_docmd.c:replace_makeprg inserts makeprg in command line

• quickfix.c:ex_make runs make command with do_shell

• ex_make flushes all buffers with autowrite_all. I'm not quite sure what that function does though.

• eap is a pointer to a exarg struct which is defined in ex_cmds.h. It contains stuff like the command and its arguments, etc.

Running a self compiled vim seems a bit more complex than just invoking it. Maybe compilation control with a $HOME prefix to ensure that all the support files are in the right places.

make distclean
./configure -prefix=$HOME
make -j4
make install