cgit — Building

Prerequisites

Build System Overview

cgit uses a two-stage build that embeds itself within Git's build infrastructure:

cgit/Makefile
  └── make -C git -f ../cgit.mk ../cgit
        └── git/Makefile (included by cgit.mk)
              └── Compile cgit objects + link against libgit.a

Stage 1: Top-Level Makefile

The top-level Makefile lives in cgit/ and defines all user-configurable variables:

CGIT_VERSION = 0.0.5-1-Project-Tick
CGIT_SCRIPT_NAME = cgit.cgi
CGIT_SCRIPT_PATH = /var/www/htdocs/cgit
CGIT_DATA_PATH = $(CGIT_SCRIPT_PATH)
CGIT_CONFIG = /etc/cgitrc
CACHE_ROOT = /var/cache/cgit
prefix = /usr/local
libdir = $(prefix)/lib
filterdir = $(libdir)/cgit/filters
docdir = $(prefix)/share/doc/cgit
mandir = $(prefix)/share/man
SHA1_HEADER = <openssl/sha.h>
GIT_VER = 2.46.0
GIT_URL = https://www.kernel.org/pub/software/scm/git/git-$(GIT_VER).tar.xz

The main cgit target delegates to:

cgit:
    $(QUIET_SUBDIR0)git $(QUIET_SUBDIR1) -f ../cgit.mk ../cgit NO_CURL=1

This enters the git/ subdirectory and runs cgit.mk from there, prefixing all cgit source paths with ../.

Stage 2: cgit.mk

cgit.mk is run inside the git/ directory so it can include Makefile to inherit Git's build variables (CC, CFLAGS, linker flags, OS detection via config.mak.uname, etc.).

Key sections:

Version tracking

$(CGIT_PREFIX)VERSION: force-version
    @cd $(CGIT_PREFIX) && '$(SHELL_PATH_SQ)' ./gen-version.sh "$(CGIT_VERSION)"

The gen-version.sh script writes a VERSION file that is included by the build. Only cgit.o references CGIT_VERSION, so only that object is rebuilt when the version changes.

CGIT_CFLAGS

CGIT_CFLAGS += -DCGIT_CONFIG='"$(CGIT_CONFIG)"'
CGIT_CFLAGS += -DCGIT_SCRIPT_NAME='"$(CGIT_SCRIPT_NAME)"'
CGIT_CFLAGS += -DCGIT_CACHE_ROOT='"$(CACHE_ROOT)"'

These compile-time constants are used in cgit.c as default values in prepare_context().

Lua detection

LUA_PKGCONFIG := $(shell for pc in luajit lua lua5.2 lua5.1; do \
    $(PKG_CONFIG) --exists $$pc 2>/dev/null && echo $$pc && break; \
done)

If Lua is found, its --cflags and --libs are appended to CGIT_CFLAGS and CGIT_LIBS. If not found, NO_LUA=YesPlease is set and -DNO_LUA is added.

Linux sendfile

ifeq ($(uname_S),Linux)
    HAVE_LINUX_SENDFILE = YesPlease
endif

ifdef HAVE_LINUX_SENDFILE
    CGIT_CFLAGS += -DHAVE_LINUX_SENDFILE
endif

This enables the sendfile() syscall in cache.c for zero-copy writes from cache files to stdout.

Object files

All cgit source files are listed explicitly:

CGIT_OBJ_NAMES += cgit.o cache.o cmd.o configfile.o filter.o html.o
CGIT_OBJ_NAMES += parsing.o scan-tree.o shared.o
CGIT_OBJ_NAMES += ui-atom.o ui-blame.o ui-blob.o ui-clone.o ui-commit.o
CGIT_OBJ_NAMES += ui-diff.o ui-log.o ui-patch.o ui-plain.o ui-refs.o
CGIT_OBJ_NAMES += ui-repolist.o ui-shared.o ui-snapshot.o ui-ssdiff.o
CGIT_OBJ_NAMES += ui-stats.o ui-summary.o ui-tag.o ui-tree.o

The prefixed paths (CGIT_OBJS := $(addprefix $(CGIT_PREFIX),$(CGIT_OBJ_NAMES))) point back to the cgit/ directory from inside git/.

Quick Build

cd cgit

# Download the vendored Git source (required on first build)
make get-git

# Build cgit binary
make -j$(nproc)

The output is a single binary named cgit in the cgit/ directory.

Build Variables Reference

Overrides can be placed in a cgit.conf file (included by both Makefile and cgit.mk via -include cgit.conf).

Installation

make install              # Install binary and static assets
make install-doc          # Install man pages, HTML docs, PDF docs
make install-man          # Man pages only
make install-html         # HTML docs only
make install-pdf          # PDF docs only

Installed files

Make Targets

Documentation Generation

Man pages are generated from cgitrc.5.txt using asciidoc/a2x:

MAN5_TXT = $(wildcard *.5.txt)
DOC_MAN5 = $(patsubst %.txt,%,$(MAN5_TXT))
DOC_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))
DOC_PDF  = $(patsubst %.txt,%.pdf,$(MAN_TXT))

%.5 : %.5.txt
    a2x -f manpage $<

$(DOC_HTML): %.html : %.txt
    $(TXT_TO_HTML) -o $@+ $< && mv $@+ $@

$(DOC_PDF): %.pdf : %.txt
    a2x -f pdf cgitrc.5.txt

Cross-Compilation

For cross-compiling (e.g. targeting MinGW on Linux):

make CC=x86_64-w64-mingw32-gcc

The toolchain-mingw32.cmake file in the repository is for CMake-based projects; cgit itself uses Make exclusively.

Customizing the Build

Create a cgit.conf file alongside the Makefile:

# cgit.conf — local build overrides
CGIT_VERSION = 1.0.0-custom
CGIT_CONFIG = /usr/local/etc/cgitrc
CACHE_ROOT = /tmp/cgit-cache
NO_LUA = 1

This file is -included by both Makefile and cgit.mk, so it applies to all build stages.

Troubleshooting