I am far from knowledgeable about most areas of the pacman code-base, so whenever I want to implement a new feature I first have to sit down and walk step-by-step through a transaction and figure out the code path. Given I have now done this several times, I thought it a good idea to post it for further reference.

Here is my brief overview of what happens with a pacman -S <pkg> transaction:

pacman/pacman.c:
 -> int main(int argc, char *argv[])
      - parse command line
      - parse config file
 
pacman/sync.c:
 -> int pacman_sync(alpm_list_t *targets)
      - check we have a pacman database
      - check target list for SyncFirst packages
 
 -> static int sync_trans(alpm_list_t *targets)
      - initialise transation
      - process the target list
 
libalpm/trans.c:
 -> int SYMEXPORT alpm_trans_prepare(alpm_list_t **data)
      - perfoms checks (via _alpm_trans_prepare)
         - requested packages have valid architecture
         - all deps are available
         - deps do not directly conflict (not files)
 
 -> int SYMEXPORT alpm_trans_commit(alpm_list_t **data)
 
libalpm/sync.c:
 -> int _alpm_sync_commit(pmtrans_t *trans, pmdb_t *db_local, alpm_list_t **data)
      - download needed files
      - deal with deltas (if any)
      - check package integrity
      - check file conflicts
      - remove packages (conflicts/replacements)
      - install targets


Doing a pacman -Syu takes you down exactly the same code path with the only difference being that the package databases are updated and the list of packages to be updated is calculated in the pacman_sync function.

While that is a fairly basic overview, it has more than enough detail for me to locate where I should implement checking for free disk space before proceeding with a package install (which has been a long time feature request for pacman).

I hope this also shows people that the pacman code is not that complex. There are quite a few old bug reports/feature requests in the bug tracker that are obviously very low on the developers priority list and are good candidates for new contributors. Just step through the code until you find the relevant section and then get started!