Makefile

# flint build.
#
# `make` with no arguments gives you a release binary. Everything else is a
# different set of flags on the same sources.
#
# What is deliberately not here: a configure step, a generated makefile, a
# code generator, or a dependency on anything outside a C11 compiler and
# make. If adding a feature to the build ever requires installing a tool,
# the tool is not worth the feature.

CC ?= cc

# -Werror is not a default you can turn off. A patch that produces a warning
# does not get merged, so there is no target that relaxes it.
STD  := -std=c11
WARN := -Wall -Wextra -Wpedantic -Werror

INCLUDES := -Isrc/core -Isrc/frontend -Isrc/runtime -Isrc/util

# User flags go last so they can add to the baseline without being able to
# quietly drop the parts that matter.
CFLAGS ?=

# The version is the tag, read at build time. `git describe` gives
# "v0.2.0", or "v0.2.0-3-gabc1234" a few commits after it, or "abc1234"
# with no tags at all. Outside a git tree (a tarball build) there is
# nothing to read and the fallback in main.c reports "dev".
#
# The escaped quotes survive make and the shell so the compiler receives a
# string literal. Without them -D hands the preprocessor a bare token and
# the build fails in a way that looks nothing like a quoting problem.
VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo dev)
ALL_CFLAGS := $(STD) $(WARN) $(INCLUDES) -D_POSIX_C_SOURCE=200809L $(CFLAGS) -DFLINT_VERSION="\"$(VERSION)\""

SRCDIRS := src src/core src/frontend src/runtime src/util

# $(sort) is not cosmetic. $(wildcard) hands back whatever order the
# filesystem feels like, so two clones of this tree can link into
# different binaries. Sort it and the output is byte-for-byte reproducible.
#
# $(wildcard) rather than a shell glob on purpose: the shell would also match
# a directory, and a bare *.c left in a subdirectory is a build error nobody
# wants to debug.
SRCS := $(sort $(wildcard $(addsuffix /*.c,$(SRCDIRS))))

LIBS := -lm

# One object tree per configuration.
#
# -O0 objects and -O2 objects are not interchangeable, and make cannot know
# that: it sees one file called memory.o and assumes it is current. A single
# shared tree means `make release && make debug` quietly links -O0 code into
# a binary it calls a release. Separate directories make that unrepresentable.
#
# The trees mirror the source layout, so src/core/memory.c becomes
# build/release/src/core/memory.o and no two files can collide on a basename.
BUILD := build
REL_DIR := $(BUILD)/release
DBG_DIR := $(BUILD)/debug
STR_DIR := $(BUILD)/stress

REL_OBJS := $(SRCS:%.c=$(REL_DIR)/%.o)
DBG_OBJS := $(SRCS:%.c=$(DBG_DIR)/%.o)
STR_OBJS := $(SRCS:%.c=$(STR_DIR)/%.o)

# Header dependencies, generated by the compiler with -MMD. Listing them as
# includes rather than parsing them ourselves is the whole trick: the
# compiler already knows the answer, and it stays correct when includes move.
REL_DEPS := $(REL_OBJS:.o=.d)
DBG_DEPS := $(DBG_OBJS:.o=.d)
STR_DEPS := $(STR_OBJS:.o=.d)

# -MP is the part people leave out. Without it, deleting a header leaves a
# stale .d file naming a file that no longer exists, and make refuses to
# build anything until you delete the .d by hand.
DEPFLAGS := -MMD -MP

# -g3 because the stress and debug builds exist to be put under a debugger,
# and -O1 rather than -O0 so the optimizer still gets a look at the code
# while the sanitizers stay readable.
REL_CFLAGS := -O2 -DNDEBUG
DBG_CFLAGS := -O0 -g3 -DFL_DEBUG_PRINT_CODE -DFL_DEBUG_TRACE_EXECUTION
STR_CFLAGS := -O1 -g -fsanitize=address,undefined -fno-omit-frame-pointer -DFL_GC_STRESS
STR_LDFLAGS := -fsanitize=address,undefined

.PHONY: all release debug stress test diagnostic-test unit bench check lint fmt fmt-check clean help install uninstall flint-goto
.SUFFIXES:

# If a compile fails partway, do not leave a truncated object behind. Make
# will happily treat it as up to date next time, and the error you get then
# is about a file that compiled fine.
.DELETE_ON_ERROR:

# Built-in rules are a trap here. They know how to build .c from .yacc and
# will happily do so at two in the morning when someone runs a typo'd target.
MAKEFLAGS += --no-builtin-rules

# The default goal. `make` should do the obvious thing.
all: release

# What everyone actually wants.
release: flint

# The three configurations. Identical structure on purpose: the difference
# between them is the flags, and a difference in structure would mean
# testing a different program than the one you ship.
flint: $(REL_OBJS)
	$(CC) $(ALL_CFLAGS) $(REL_CFLAGS) $^ -o $@ $(LIBS)

flint-debug: $(DBG_OBJS)
	$(CC) $(ALL_CFLAGS) $(DBG_CFLAGS) $^ -o $@ $(LIBS)

flint-stress: $(STR_OBJS)
	$(CC) $(ALL_CFLAGS) $(STR_CFLAGS) $(STR_LDFLAGS) $^ -o $@ $(LIBS)

debug: flint-debug

$(REL_DIR)/%.o: %.c
	@mkdir -p $(dir $@)
	$(CC) $(ALL_CFLAGS) $(REL_CFLAGS) $(DEPFLAGS) -c $< -o $@

$(DBG_DIR)/%.o: %.c
	@mkdir -p $(dir $@)
	$(CC) $(ALL_CFLAGS) $(DBG_CFLAGS) $(DEPFLAGS) -c $< -o $@

$(STR_DIR)/%.o: %.c
	@mkdir -p $(dir $@)
	$(CC) $(ALL_CFLAGS) $(STR_CFLAGS) $(DEPFLAGS) -c $< -o $@

# Missing .d files are normal on a first build, so this is an include, not
# an error. Any .d file that does exist is loaded, and from then on editing
# a header rebuilds only the files that include it.
-include $(REL_DEPS) $(DBG_DEPS) $(STR_DEPS)

# Runs the suite against a freshly built binary. `test` builds release first
# because a stale binary makes a passing test meaningless.
test: flint
	@sh tests/run_tests.sh ./flint

diagnostic-test: flint
	@sh tests/diagnostics.sh ./flint

# The build that finds bugs. GC on every allocation means every missing root
# turns into a use-after-free immediately instead of on a Tuesday, and asan
# plus ubsan catch the rest. Slow on purpose.
stress: flint-stress
	@sh tests/run_tests.sh ./flint-stress

# Unit tests. test_chunk needs the runtime, test_value does not, and neither
# needs main.c, which is why the object list is filtered.
UNIT_DIR := $(REL_DIR)/tests/unit
LIB_OBJS := $(filter-out $(REL_DIR)/src/main.o,$(REL_OBJS))

# Linking and running are separate targets, and that is the whole point.
#
# When one rule did both, the binary was a file target. Once it existed and
# was newer than its objects, `make unit` reported "Nothing to be done" and
# ran nothing -- so a green result meant "the file is there", not "the tests
# passed". A test target that stops testing after the first run is worse than
# no test target, because it still looks like it works.
#
# The .bin targets are ordinary files and get rebuilt only when something
# changed. The test targets are phony and always run what they built.
.PHONY: test_value test_chunk test_verify

test_value.bin: $(UNIT_DIR)/unit_value.o
	$(CC) $(ALL_CFLAGS) $(REL_CFLAGS) $^ -o $@ $(LIBS)

test_chunk.bin: $(UNIT_DIR)/test_chunk.o $(LIB_OBJS)
	$(CC) $(ALL_CFLAGS) $(REL_CFLAGS) $^ -o $@ $(LIBS)

test_verify.bin: $(UNIT_DIR)/test_verify.o $(LIB_OBJS)
	$(CC) $(ALL_CFLAGS) $(REL_CFLAGS) $^ -o $@ $(LIBS)

test_value: test_value.bin
	@./test_value.bin

test_chunk: test_chunk.bin
	@./test_chunk.bin

test_verify: test_verify.bin
	@./test_verify.bin

# Built in the release tree on purpose: these run under the same -Werror
# baseline as the interpreter, so a header change that breaks them shows up
# here rather than in CI.
$(UNIT_DIR)/%.o: tests/unit/%.c
	@mkdir -p $(dir $@)
	$(CC) $(ALL_CFLAGS) $(REL_CFLAGS) $(DEPFLAGS) -c $< -o $@

# Each test reports through its exit status, so make stops at the first
# failure and names it rather than running the rest onto a broken build.
unit: test_value test_chunk test_verify

#
# The computed-goto interpreter.
#
# A switch is portable C11. Computed goto is a GCC/Clang extension that drops
# the bounds check and lets the processor predict the next opcode from the
# previous one, and it is worth 7-21% on loop-heavy programs -- measured, see
# bench/RESULTS.md.
#
# It is not the default because taking the address of a label is not standard
# C, and this project builds with -Wpedantic -Werror and has never needed to
# relax either for a feature. So the fast interpreter is a separate binary
# produced by transforming the source, rather than a #ifdef in it:
#
#   * one copy of the interpreter, not two that have to be kept in step
#   * the default build stays portable and warning-clean
#   * the transformation is a script you can read, rather than a macro that
#     hides sixty handlers behind one
#
# scripts/to_computed_goto.py rewrites the dispatch into labels. It is
# idempotent and it refuses to run on an already-transformed file.
GOTO_DIR := $(BUILD)/goto
GOTO_VM := $(GOTO_DIR)/vm.c
GOTO_OBJS := $(SRCS:%.c=$(REL_DIR)/%.o)
GOTO_OBJS := $(filter-out $(REL_DIR)/src/runtime/vm.o,$(GOTO_OBJS)) $(GOTO_DIR)/vm.o

flint-goto: $(GOTO_VM) $(GOTO_OBJS)
	$(CC) $(ALL_CFLAGS) -std=gnu11 -Wno-pedantic $(REL_CFLAGS) $(GOTO_OBJS) -o $@ $(LIBS)

$(GOTO_VM): src/runtime/vm.c scripts/to_computed_goto.py
	@mkdir -p $(dir $@)
	@python3 scripts/to_computed_goto.py --output $@ $<

$(GOTO_DIR)/vm.o: $(GOTO_VM)
	$(CC) $(ALL_CFLAGS) -std=gnu11 -Wno-pedantic $(REL_CFLAGS) $(DEPFLAGS) -c $< -o $@

#
# Install.
#
# Two directories, because the runtime needs to find lib/ and there are two
# honest places for it. The binary goes on PATH; the standard library goes to
# ~/.flint/stdlib, which is the third entry in the lookup order the runtime
# already documents:
#
#   1. $FLINT_STDLIB
#   2. <exe-dir>/lib
#   3. ~/.flint/stdlib
#
# (3) is chosen over (2) because a package-installed binary on PATH has no
# lib/ beside it -- /usr/local/bin is full of other things -- and because a
# user-level install should not need root. Point FLINT_STDLIB somewhere else
# and it wins over both.
#
# PREFIX/DESTDIR are honoured for packaging.
#
PREFIX ?= $(HOME)/.local
BINDIR ?= $(PREFIX)/bin
LIBDIR ?= $(HOME)/.flint/stdlib

install: flint
	@mkdir -p $(DESTDIR)$(BINDIR) $(DESTDIR)$(LIBDIR)
	install -m 755 flint $(DESTDIR)$(BINDIR)/flint
	install -m 644 lib/*.fl $(DESTDIR)$(LIBDIR)/
	@echo "installed $(DESTDIR)$(BINDIR)/flint"
	@echo "          $(DESTDIR)$(LIBDIR)/*.fl"
	@command -v flint >/dev/null 2>&1 || \
		echo "note: $(BINDIR) is not on PATH."

uninstall:
	rm -f $(DESTDIR)$(BINDIR)/flint
	@echo "left $(DESTDIR)$(LIBDIR) alone; it is yours to delete"

# Benchmarks.
#
# `make bench` measures the portable build, because that is the one everybody
# has. `make bench-goto` builds the computed-goto interpreter and measures that
# too, and writes the numbers into RESULTS.md's place -- see bench/compare.sh,
# which does an old-binary-against-new-binary comparison rather than an absolute
# timing, because that is the only comparison that survives a busy machine.
bench: flint
	@python3 bench/bench.py

bench-goto: flint flint-goto
	@sh bench/compare.sh ./flint ./flint-goto

# Full gate: clean build then every test suite. The only target that proves the
# tree is green from scratch. `make test` alone tests a possibly stale binary;
# this one does not. Use it before pushing or tagging.
check:
	$(MAKE) clean
	$(MAKE) release
	$(MAKE) test
	$(MAKE) unit

# Static analysis. Reads .clang-tidy for the check list and the reason each
# exclusion is there, so the policy lives in one reviewable place.
#
# -std=c11 and the -Isrc flags have to be repeated here: clang-tidy does not
# run the build, so it never sees ALL_CFLAGS. Tidy up its own output in the
# Makefile, not in the shell, or a stray note from the header search becomes a
# lint failure on a machine that happens to have a different clang.
CLANG_TIDY ?= clang-tidy
TIDY_FLAGS := --quiet --extra-arg=-std=c11 \
	--extra-arg=-D_POSIX_C_SOURCE=200809L \
	--extra-arg=-Isrc/core --extra-arg=-Isrc/frontend \
	--extra-arg=-Isrc/runtime --extra-arg=-Isrc/util

# The debug-only macros, so the second lint pass sees the #ifdef arms that
# the default configuration cannot see.
TIDY_DEBUG_FLAGS := --extra-arg=-DFL_DEBUG_PRINT_CODE \
	--extra-arg=-DFL_DEBUG_TRACE_EXECUTION

#
# The debug and stress configurations define FL_DEBUG_PRINT_CODE and
# FL_DEBUG_TRACE_EXECUTION, which is the only place debug.h is called from.
# A translation unit that only uses it under #ifdef reports the include as
# unused to a lint run in the default configuration, so removing it would
# break the debug build. Lint the debug configuration too, or the
# include-cleaner check is only half right.
lint: flint flint-debug
	@command -v $(CLANG_TIDY) >/dev/null 2>&1 || { \
		echo "$(CLANG_TIDY) not found. install clang-tools, or skip: this target is advisory."; \
		exit 1; \
	}
	$(CLANG_TIDY) $(TIDY_FLAGS) $(SRCS)
	$(CLANG_TIDY) $(TIDY_FLAGS) $(TIDY_DEBUG_FLAGS) $(SRCS)

# Formatting. The policy is in .clang-format; this is only the plumbing.
#
# One glob over src and tests, and one place to add a directory. The -i is
# what makes `make fmt` do the work; fmt-check is the same command without it,
# and is the one that belongs in CI. A formatter nobody can run in check mode
# is a formatter people stop trusting.
CLANG_FORMAT ?= clang-format

# $(sort) for the same reason SRCS is sorted: reproducible command lines, and
# so a diff is the same on every machine.
FMT_FILES := $(sort $(wildcard src/*.c src/*/*.c src/*/*.h tests/unit/*.c))

fmt:
	@command -v $(CLANG_FORMAT) >/dev/null 2>&1 || { \
		echo "$(CLANG_FORMAT) not found. install clang-tools."; \
		exit 1; \
	}
	$(CLANG_FORMAT) -i $(FMT_FILES)
	@echo "formatted $(words $(FMT_FILES)) files"

# Reports the files that differ and exits non-zero. Does not rewrite
# anything, so a failing CI job leaves the tree alone.
fmt-check:
	@command -v $(CLANG_FORMAT) >/dev/null 2>&1 || { \
		echo "$(CLANG_FORMAT) not found. install clang-tools."; \
		exit 1; \
	}
	@bad=0; \
	for f in $(FMT_FILES); do \
		if ! $(CLANG_FORMAT) "$$f" 2>/dev/null | diff -q "$$f" - >/dev/null; then \
			echo "needs formatting: $$f"; \
			$(CLANG_FORMAT) "$$f" 2>/dev/null | diff -u "$$f" - | head -30; \
			bad=1; \
		fi; \
	done; \
	if [ $$bad -ne 0 ]; then \
		echo "run 'make fmt'"; \
		exit 1; \
	fi; \
	echo "all $(words $(FMT_FILES)) files formatted"

clean:
	rm -rf $(BUILD) flint flint-debug flint-stress flint-goto \
		test_value.bin test_chunk.bin test_verify.bin

help:
	@echo "make            release build          -> ./flint"
	@echo "make debug      -O0, disassembly, trace -> ./flint-debug"
	@echo "make stress     gc stress + asan/ubsan, runs the suite"
	@echo "make test       release build, runs the language suite"
	@echo "make unit       value and chunk unit tests"
	@echo "make check      clean + build + test + unit (gate quality)"
	@echo "make flint-goto computed-goto interpreter, 7-21% faster"
	@echo "make install    flint + lib to ~/.local/bin and ~/.flint/stdlib"
	@echo "make bench      benchmarks (bench/bench.py)"
	@echo "make lint       clang-tidy, policy in .clang-tidy"
	@echo "make clean      remove build/ and the binaries"
	@echo ""
	@echo "add CFLAGS=... to override flags, CC=clang to change compiler."
	@echo "every target works with -j. check does not (intentionally sequential)."