mk.1

.\" Copyright (c) 2025 Benjamin Stürz <benni@stuerz.xyz>
.Dd January 4, 2025
.Dt MK 1
.Os
.Sh NAME
.Nm mk
.Nd build stuff
.Sh SYNOPSIS
.Nm
.Op Fl hkpsSv
.Op Fl C Ar dir
.Op Fl f Ar makefile
.Op Fl o Ar objdir
.Op Fl V Ar var
.Op Ar target ...
.Sh DESCRIPTION
.Nm
is designed to help you build stuff.
It is specifically designed for larger projects,
for which
.Xr make 1
is not suitable enough.

The following options are available:
.Bl -tag -width indent
.It Fl h
Print a help page for the current directory.
.It Fl hv
Similar to
.Fl h ,
but do so recursively for all subdirectories.
.It Fl p
Dump the current directory's makefile.
.It Fl pv
Same as
.Fl p ,
but do so recursively for all subdirectories.
.It Fl s
Do not echo commands, as they are executed.
Equivalent to specifying '@' before each command in the makefile.
.It Fl S
stop processing when an erorr is encountered.
This is the default behavior and is the opposite of
.Fl k .
.It Fl k
Continue processing after errors are encountered,
but only on those targets that do not depend on the target whose creating caused the error.
This options is the opposite of the 
.Fl S
option.
.It Fl v
Cause
.Nm
to print more verbose output.
This option can be specified multiple times, to increase the verbosity.
This option is negated by the
.Fl s
option.
.It Fl C Ar dir
Change the current working directory to
.Ar dir .
.It Fl f Ar mk
Read file
.Ar mk
instead of the default makefile.
Contrary to other implementations, only the last occurence of this option is honored.
.It Fl o Ar obj
Put generated artifacts into the
.Ar obj
directory.
.Nm
will also search for artifacts in this directory.
This is very useful for out-of-tree builds.
.It Fl V Ar var
Print the expanded value of
.Ar var
to the standard output and exit.
.El
.Sh DEPENDENCY LINES
Dependency lines consist of one or more targets,
and zero or more prerequisites:
.Bd -ragged -offset ident
.Ar target ... : Ns Op Ar prerequisite ...
.Ed
.Pp
This creates a relationship, where the targets
.Dq depend
on the prerequisites, and are built from them.
.Pp
Targets must consist of only characters in
.Dq [a-zA-Z._-] .
Dependencies can additionally contain
.Dq /
characters, but the resulting paths must be relative,
and cannot cross directories, that are outside the build.
.Sh SHELL COMMANDS
Each target may have associated with it a series of shell commands,
normally used to build the target.
While several dependency lines may name the same target,
only one of these dependency lines may be followed by shell commands,
and thus define a complete target rule.
.Pp
If a command line begins with one of the characters,
.Sq Ic @
or
.Sq Ic \- ,
the command is treated specially:
.Bl -tag -width '@'
.It Sq Ic @
causes the command not to be echoed before it is executed.
.It Sq Ic \-
causes any non-zero exit status of the command line to be ignored.
.El
.Pp
Commands are executed using
.Pa /bin/sh
in
.Qq set -e
mode, unless
.Sq Ic \-
is specified, or the shell is broken (in case of Minix-vmd).
.Sh INFERENCE RULES
TODO
.Sh VARIABLE ASSIGNMENTS
Variables in
.Nm
are much like variables in the shell:
.Bd -ragged -offset ident
.Ar name No = Ar value
.Ed
.Pp
They are also sometimes refered to as
.Sq macros .
Variable names can only consist of
.Dq [a-zA-Z0-9._-]
and may not start with a digit or hyphen.
By tradition names consist of all upper-case letters.
.Pp
The following operators can be used to define variables:
.Bl -tag -width Ds
.It Ic \&=
Assign the value to the variable.
Any previous value is overriden.
.It Ic \&:=
Like
.Dq \&= ,
but expand the value, before assigning it.
.It Ic \&::=
Currently equivalent to
.Dq := .
.It Ic \&+=
Append the value to the current value of the variable.
.It Ic \&?=
Assign the value, if it is not already defined.
.It Ic \&??=
Similar to
.Dq \&?= ,
but take environment variables into account.
.It Ic \&!=
Perform variable expansion and pass the result to the shell for execution.
The output of the shell command will be assigned to the variable.
.El
.Pp
Any whitespace before or after the assigned
.Ar value
will be removed;
if the value is being appended,
a single space is inserted between the previous contents of the variable and the appended value.
.Pp
Variables are expanded by surrounding the variable name with curly braces
.Pq Ql {}
and preceding it with a doller sign
.Pq Ql $ .
If the variable name consists of only a single letter,
the surrounding braces can be omitted.
.Pp
Variables can be made visible into subdirectories using the
.Dq .EXPORT:
directive.
.Ss SPECIAL VARIABLES
The following special variables can be used:
.Bl -tag -width Ds
.It Ic $$
The literal
.Ic $
character.
.It Ic $.
Relative path to the top-level directory.
This is the shortform of ${\fB.TOPDIR\fR}.
.It Ic $@
The name of the target currently being built.
This is the shortform of ${\fB.TARGET\fR}.
.It Ic $<
The name of the prerequisite from which this target is to be built,
if a valid inference rule (suffix rule) is in scope.
This is the shortform of ${\fB.IMPSRC\fR}.
.It Ic $^
All source dependencies.
This is the shortform of ${\fB.ALLSRC\fR}.
.It Ic $*
This is the shortform of ${\fB.IMPSRC:T\fR}.
.It ${\fB.SUBDIRS\fR}
A list of subdirectories specified by the
.Ic .SUBDIRS:
directive.
.It ${\fB.EXPORTS\fR}
A list of variables specified by the
.Ic .EXPORTS:
directive.
This is useful for invoking other build systems in foreign subdirectories.
.It ${\fB.OBJDIR\fR}
The object directory specified by the
.Fl o Ar objdir
option, or the current directory.
.It ${\fB.MAKEFILES\fR}
A list of Mkfiles from this directory upwards.
.It ${\fBSHELL\fR}
The shell used to interpret the command lines.
.It ${\fBMAKE\fR}
The name of the
.Nm
command.
Alias for ${\fB.MAKE\fR}.
.It ${\fBMAKEFLAGS\fR}
A list of options given to
.Nm .
Alias for ${\fB.MAKEFLAGS\fR}.
.El
.Ss MODIFIERS
Modifiers can be applied to a macro expansion using the following syntax:
.Bd -ragged -offset ident
${\fBNAME\fR:\fImodfiers\fR...}
.Ed
.Pp
The following modifiers can be applied to variable expansions:
.Bl -tag -width Ds
.It Ic :U
Make all characters in
.Ar string
uppercase.
.It Ic :L
Make all characters in
.Ar string
lowercase.
.It Ic :F
Search for files in either the source directory, or in
.Ic ${.OBJDIR} .
.It Ic :E
Replace each word by it's suffix.
.Dq suffix
refers to the file extension.
.It Ic :R
Replace each word by everything but it's suffix.
.It Ic :H
Replace each word by it's
.Xr dirname 1
equivalent.
.It Ic :T
Replace each word by it's
.Xr basename 1
equivalent.
.It Ic :M\fIpattern\fR
Only retain words that match
.Ar pattern .
.It Ic :N\fIpattern\fR
The opposite of the
.Ic :M
modifier.
.It Ic :J\fIseparator
Concatenate each word and separate the resulting string by
.Ar separator .
.It :\fBname\fR=\fBvalue\fR
Replace every occurence of
.Ar name
with
.Ar value .
This has to be the last modifier.
.El
.Pp
These are a few examples for using macro modifiers:
.Pp
.Bd -literal -offset indent
SOURCE = main.c lex.l parse.y gen.S

# Only retain words that match the glob \fB*.c\fR
CFILES = ${SOURCE:M*.c}

# Replace all the file extension \fB.c\fR with \fB.o\fR
COBJS = ${CFILES:.c=.o}

clean:
	# Use \fB:F\fR to search for the object files in \fB${.OBJDIR}\fR
	rm -f ${COBJS:F}

print:
	# Multiple modifiers can be specified:
	@echo ${SOURCE:T:U}
.Ed
.Sh INCLUDE STATEMENTS
Using the
.Ic include
statement it is possible to instruct
.Nm
to read another file.

Examples:
.Bd -literal -offset indent
# Include a file called "templates.mk"
\fBinclude\fR templates.mk

# Try including a file called "config.mk", if it exists
\fB-include\fR config.mk
.Ed
.Sh SUBDIRECTORIES
Subdirectories can be declared using the
.Ic .SUFFIXES:
directive.
.Pp
The handling of subdirectories is done lazily,
such that the
.Ic Mkfile
of the subdirectory is only parsed,
once a target in that subdirectory tree is needed.
.Pp
Examples:
.Bd -literal -offset indent
# Declare subdirectories \fIfoo\fR and \fIbar\fR
\fB.SUBDIRS:\fR foo bar

# Depend on targets from other directories
foobar: foo/libfoo.a bar/libbar.so ../config.h
	# \fN$^\fR refers to the list of prerequisites
	build -o foobar \fB$^\fR

# Print a ", " separated list of subdirectories
list:
	@echo "${\fB.SUBDIRS\fR:J, }"

# Depend on the \fIclean\fR target of every subdirectories:
clean: ${\fB.SUBDIRS\fR:=/clean}
	# Prefix with ${\fB.OBJDIR\fR}/ for compatibility with the \fB-o\fR option.
	rm -f ${\fB.OBJDIR\fR}/foobar
.Ed
.Ss FOREIGN SUBDIRECTORIES
TODO
.Pp
Foreign subdirectories allow integration with other build systems.
.Pp
This is an example of integrating an example Autotools dependency:
.Bd -literal -offset indent
# Declare hello as a "foreign directory"
\fB.FOREIGN\fR: hello

\fBHELLODIR\fR = hello

## External make used for building libhello
\fBEMAKE\fR ?= make

## C Compiler
\fBCC\fR ?= cc

## C Compiler Flags
\fBCFLAGS\fR ?=

## Installation Prefix
\fBPREFIX\fR ?= /usr/local

## Installation destination directory
\fBDESTDIR\fR ?=

\fB.EXPORTS\fR: CC CFLAGS DESTDIR

## Build hello/hello and xhello
all: hello/hello xhello

## Delete build artifacts
clean: hello/clean
	rm -f xhello

## Delete all non-source files
distclean: clean
	rm -rf ${HELLODIR:F}
	rm -f ${.OBJDIR}/{hello.tgz,.hello-configure,.hello-extract}

## Install hello and xhello into ${DESTDIR}${PREFIX}
install: hello/install xhello
	mkdir -p ${DESTDIR}${PREFIX}/bin
	cp -f ${.OBJDIR}/xhello ${DESTDIR}${PREFIX}/bin/

## Download hello source
hello.tgz:
	ftp -o $@ https://got.stuerz.xyz/download/hello-2.0.tgz

\fR.hello-extract: hello.tgz
	tar -xzf $< -C ${.OBJDIR}
	touch $@

\fR.hello-configure: .hello-extract
	(cd ${HELLODIR:F} && ./configure --prefix=${PREFIX})
	touch $@

# Check if \fB$<\fR is fresh in hello
hello?:
	test -e ${HELLODIR:F}/Makefile
	${EMAKE} -q -C ${HELLODIR:F} ${.EXPORTS} "$$(echo "$<" | sed 's#./##')"

# Build $< in hello
hello!: .hello-configure
	${EMAKE} -C ${HELLODIR:F} ${.EXPORTS} "$$(echo "$<" | sed 's#./##')"

## Build the xhello binary
xhello: xhello.c hello/libhello.a
	${CC} -o $@ xhello.c -I${HELLODIR:F} -L${HELLODIR:F} -lhello ${CFLAGS}
.Ed
.Sh CONDITIONALS
TODO
.Sh OTHER DIRECTIVES
TODO
.Sh COMMENTS
Comments begin with a single hash
.Pq Ql \&#
character,
anywhere but in a shell command line, and continue to the end of the line.
A
.Pq \&#
character within a shell command line will be interpreted as a comment by the shell.
.Ss DOCUMENTATION COMMENTS
Documentation comments are a special variant of comments,
which can only appear before rule and macro definitions.
To define a doc-comment, two hash
.Pq Ql \&#
characters must be used.
.Pp
Example:
.Bd -literal -offset indent
# This is a doc-comment for macro NAME
## Define the name of the project
NAME = hello

# Macros in doc-comments will be expanded:
## Build ${NAME}
${NAME}: ${NAME}.c
	${CC} -o $@ $<
.Ed
.Sh SPECIAL TARGETS
TODO
.Sh ENVIRONMENT
TODO
.Sh FILES
.Bl -tag -width Mkfile -compat
.It Pa Mkfile
default makefile
.El
.Sh EXAMPLES
The following is a list of real-world projects built with
.Nm :
.Bl -bullet -compact
.It
.Lk https://got.stuerz.xyz/?action=summary&path=desktop.git desktop
.It
.Lk https://got.stuerz.xyz/?action=summary&path=286bsd.git 286bsd
.El
.Sh EXIT STATUS
.Ex -std
.Sh SEE ALSO
.Xr make 1 ,
.Xr sh 1
.Sh STANDARDS
This implementation of make(1) does not strictly follow any POSIX standard,
but still most simple Makefiles will work fine.
.Sh HISTORY
Over the the long history of make,
there have been many (competing) implementations of make(1):
.Bl -bullet -compact
.It
Original make from PWB/UNIX 1.0
.It
GNU Make
.It
Various versions of BSD Make
.It
Plan 9's mk(1)
.El
.Sh AUTHORS
.An Benjamin Stürz Aq Mt benni@stuerz.xyz
.Sh CAVEATS
.Bl -bullet -compact
.It
All paths used as targets/dependencies must be relative.
.It
The handling of the `?=` and `??=` is different from POSIX.
.It
The way environment and commandline variables are treated is different from POSIX.
.El
.Sh BUGS
.Bl -bullet -compact
.It
There exists another project called mk(1).
.It
Defining recursive dependencies can lead to
.Nm
crashing.
.It
Specifying multiple targets at once is broken.
.It
This manual is unfinished.
.El
.Sh TODO
.Bl -bullet -compact
.It
Run commands of the same rule in the same shell, instead of creating a new shell for every command line.
.It
Create a detailed list of all features.
.It
Create a second implementation in Rust, which will support parallel execution of targets.
.It
Create a comparison to other makes.
.It
See TODO.md file.
.It
Optional prerequisites (continue even if the prerequisite failed).
.It
Numbered prerequisite macros.
.It
Strip
.Dq ./
prefix for
.Ic $<
and other variables.
.El