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

# BUILD is declared before INCLUDES because the generated version header
# lives in it, and an include path that is empty at expansion time is
# an include path that silently finds nothing.
BUILD := build

INCLUDES := -Iinclude -Isrc/core -Isrc/frontend -Isrc/runtime -Isrc/util -I$(BUILD)

# 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)

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.
# The version is a build input, so moving a tag has to invalidate whatever
# carries it. Without this, tagging a release and rebuilding without a
# clean leaves the previous version string baked into the binary -- which
# is how a release publishes the wrong version.
#
# A generated header, rewritten only when its contents change, so the
# rebuild happens exactly when the version moves and never otherwise. A
# phony prerequisite on every object would have been simpler and would
# also recompile the world on every make, including the stress build.
VERSION_HEADER := $(BUILD)/version.h
$(shell mkdir -p $(BUILD) && \
	printf '#define FLINT_VERSION "%s"\n' '$(VERSION)' > $(VERSION_HEADER).tmp && \
	(cmp -s $(VERSION_HEADER).tmp $(VERSION_HEADER) || \
	 mv $(VERSION_HEADER).tmp $(VERSION_HEADER)) && \
	rm -f $(VERSION_HEADER).tmp)
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 fmt-test pkg-test runner-test native-test quick validate libflint.a
.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.
# -rdynamic exports the executable's symbols to the dynamic linker, which is
# what lets a dlopened module resolve fl_module_func and the rest. Without it
# the module loads and then fails on its first call to the host, which is a
# confusing way to learn that the ABI needs it.
#
# The alternative -- linking each module against a shared libflint -- would
# mean the runtime becomes a library, which changes how flint is built and
# shipped for one feature. Exporting the ABI is the smaller change.
#
# ELF-only: mingw has no -rdynamic, and needs none, because the Windows
# loader refuses up front -- there is nothing to resolve against. Matched
# on the compiler name, which is what the Windows probe sets.
RDYNAMIC := -rdynamic
ifneq (,$(findstring mingw,$(CC)))
RDYNAMIC :=
endif
flint: $(REL_OBJS)
	$(CC) $(ALL_CFLAGS) $(REL_CFLAGS) $^ -o $@ $(LIBS) $(RDYNAMIC)

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

# main.o carries FLINT_VERSION, so the generated header is its dependency:
# a new tag rebuilds that one object and relinks, nothing else.
$(REL_DIR)/src/main.o: $(VERSION_HEADER)

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

$(DBG_DIR)/src/main.o: $(VERSION_HEADER)

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

$(STR_DIR)/src/main.o: $(VERSION_HEADER)

$(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_sha256

# A static library of the runtime, for hosts that embed flint: C through
# include/flint.h, Rust through rust/flint. Everything but main.c, so an
# embedding program brings its own main. The objects are the release ones,
# because a host should link what ships. Lives here, below LIB_OBJS,
# because a prerequisite list expands where the rule is parsed.
libflint.a: $(LIB_OBJS)
	$(AR) rcs $@ $^

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_sha256.bin: $(UNIT_DIR)/test_sha256.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

test_sha256: test_sha256.bin
	@./test_sha256.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 test_sha256

#
# 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

# The fast local gate: everything that takes seconds. This is the loop for
# working on the interpreter -- build, all four test suites, formatting,
# static analysis.
#
#   make quick
#
# It reuses `flint` and the object trees rather than cleaning, so it runs
# against the binary you just built. It is not the release gate: it does not
# clean, and it does not run the sanitizer build, so it cannot prove the
# tree is green from scratch. `make validate` is that.
quick:
	$(MAKE) release
	$(MAKE) test
	$(MAKE) unit
	$(MAKE) fmt-test
	$(MAKE) pkg-test
	$(MAKE) runner-test
	$(MAKE) fmt-check
	$(MAKE) lint

# The release gate: clean build, then everything, then the sanitizer and
# computed-goto configurations the fast gate cannot stand in for.
#
#   make validate
#
# Ordered so the cheap failures come first: a compiler error in the release
# build costs seconds, while `stress` costs minutes. Every target here is
# required -- a failure stops the recipe rather than being reported at the
# end, because a validation run that continues past a red gate has already
# told you it is not a validation run.
#
# The stress build is a separate object tree (STR_DIR) and a separate binary,
# so it neither replaces ./flint nor rebuilds the release objects. That
# separation is what lets this run after `make release` without a clean.
validate: release test unit diagnostic-test fmt-test pkg-test runner-test \
	native-test fmt-check lint stress flint-goto
	@sh tests/run_tests.sh ./flint-goto
	@echo "validate: every gate passed"

# The formatter's contract: same input, same output, and one pass is
# enough (fmt(fmt(source)) == fmt(source)). Checked over every source in
# the tree plus a set of awkward shapes, so a canonical-style change
# cannot leave the repository disagreeing with itself.
fmt-test: flint
	@sh tests/fmt_test.sh ./flint

# The runner's own contract, built from throwaway fixtures: a suite with the
# right output and the wrong exit status has to fail, a declared nonzero
# status has to pass, and a malformed status file has to be reported rather
# than defaulted. A runner that cannot fail is worse than no runner.
runner-test: flint
	@sh tests/runner_test.sh ./flint

# The public C ABI: real shared objects, built against include/flint.h and
# loaded through dlopen. Needs a linker and a posix dynamic loader; the test
# skips with a message rather than failing on a system without them, so it
# does not turn a missing toolchain into a red build on an unrelated commit.
native-test: flint
	@sh tests/native_test.sh ./flint

# The package manager, end to end against real fixtures: a path
# dependency, a git dependency over file:// (no network, no registry),
# lock pinning, update, and the failure messages.
pkg-test: flint
	@sh tests/pkg_test.sh ./flint

# 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 \
	--extra-arg=-Iinclude --extra-arg=-I$(BUILD)

# 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"

# `check` is what people type and what older notes cite. It is the full
# gate, alias and all -- see validate.
check: validate

clean:
	rm -rf $(BUILD) flint flint-debug flint-stress flint-goto libflint.a \
		test_value.bin test_chunk.bin test_verify.bin test_sha256.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, chunk and verifier unit tests"
	@echo "make diagnostic-test  diagnostic rendering and exit codes"
	@echo ""
	@echo "gates:"
	@echo "make quick      seconds: build, all suites, fmt-check, lint"
	@echo "make validate   minutes: everything, incl. sanitizers and goto"
	@echo ""
	@echo "flint-goto      computed-goto interpreter, 7-21% faster"
	@echo "libflint.a      static runtime for embedding (C/Rust hosts)"
	@echo "install         flint + lib to ~/.local/bin and ~/.flint/stdlib"
	@echo "bench           benchmarks (bench/bench.py)"
	@echo "lint            clang-tidy, policy in .clang-tidy"
	@echo "fmt / fmt-check reformat / verify formatting"
	@echo "clean           remove build/ and the binaries"
	@echo ""
	@echo "add CFLAGS=... to override flags, CC=clang to change compiler."
	@echo "every target works with -j. validate does not (sequential by design)."