path: root/mkproj.1

.TH MKPROJ 1 "2026-09-20" "mkproj 0.4.0" "User Commands"
.SH NAME
mkproj \- dumb project generator
.SH SYNOPSIS
.B mkproj
.RI [ options ]
.I name
.br
.B mkproj \-\-completions
.BR bash | zsh | fish
.br
.B mkproj
.BR \-v | \-h
.SH DESCRIPTION
.B mkproj
generates boilerplate for
.BR make ,
.BR cmake ,
.BR meson ,
.B premake5
or
.B xmake
so you do not have to keep writing build files for small projects.
.PP
It creates a directory
.I name
containing a stub
.I main
at the root and a build file for the chosen build system. With
.B \-\-git
it also writes a
.B .gitignore
and initializes a git repository. The stub compiles
cleanly under a strict set of warnings with address and undefined
sanitizers enabled by default.
.PP
If
.I name
is
.BR . ,
the project is generated into the current directory instead of a new one,
and the project name is taken from that directory's basename. In this mode
.B mkproj
refuses to run if a build file already exists, so it will not clobber an
existing project.
.PP
By default the layout is flat (sources at the root), the executable is
built at the project root, object files go under
.BR bin ,
and the newest language standard is used. Use
.BR \-\-src ", " \-\-no\-root
and
.B \-s
to change these.
.SH OPTIONS
.TP
.BR \-l ", " \-\-lang " " \fIlang\fR
Source language:
.BR c ", " cpp ", " objc ", " nasm ", " swift " or " crust .
Default
.BR c .
.B nasm
projects are x86\-64 assembly.
.B swift
is compiled with
.BR swiftc ,
and
.B crust
is Rust driven straight through
.B rustc
(no cargo), from the crate root
.RB ( main.rs ).
.B nasm ", " swift " and " crust
only support the
.B make
build system, build executables only, and take no language standard;
.B swift
and
.B crust
also have no
.BR \-\-style .
.TP
.BR \-s ", " \-\-std " " \fIstd\fR
Language standard passed to the compiler as
.BI \-std= std\fR,
for example
.B c17
or
.BR c++23 .
Must be valid for the chosen language. Defaults to the newest standard for
the language
.RB ( c2y
for
.B c
and
.BR objc ,
.B c++26
for
.BR cpp ).
.TP
.BR \-b ", " \-\-build " " \fIsystem\fR
Build system to generate:
.BR make ", " cmake ", " meson ", " premake " or " xmake .
Default
.BR make .
.TP
.BR \-k ", " \-\-kind " " \fIkind\fR
What to build:
.B exe
for an executable,
.B lib
for a static library
.RI ( lib < name >.a ),
or
.B shared
for a shared library
.RI ( lib < name >.so
on Linux,
.RI lib < name >.dylib
on macOS). Either library kind gets a
.RI < name >.h
/
.RI < name >.c
pair with a stub function instead of a
.IR main ,
and is built without sanitizers \(em those belong in the executable that
links the library. Default
.BR exe .
.TP
.BR \-\-cc " " \fIcc\fR
Compiler to use. Default
.B clang
for
.B c
and
.BR objc ,
.B clang++
for
.BR cpp .
Applies to the
.BR make ", " premake " and " xmake
backends (for
.B premake
and
.B xmake
it selects the matching toolset);
.B cmake
and
.B meson
pick the compiler from the environment instead.
.TP
.BR \-\-license " " \fIname\fR
Write a
.B LICENSE
file. One of
.BR mit ", " isc ", " bsd-2 ", " bsd-3 " or " unlicense .
The copyright holder is taken from
.B git config user.name
(falling back to
.BR $USER ).
No license is written by default.
.TP
.B \-\-git
Initialize a git repository and write a
.BR .gitignore .
By default neither is created.
.TP
.BR \-\-src " " \fIdir\fR
Put the sources in
.I dir
instead of at the project root. By default the layout is flat, with sources
at the root; objects always build into the
.B \-\-bin
directory.
.TP
.B \-\-docker
Add a
.B Dockerfile
and
.B .dockerignore
that build and run the project in a container. Supported for
.B c
and
.B cpp
(with
.BR make ", " cmake " or " meson )
and for
.BR nasm .
With
.B nasm
the container targets Linux
.RB ( elf64 ),
so you write against Linux syscalls instead of the macOS assembly
conventions the native build uses.
.TP
.B \-\-no\-root
Put the built executable inside
.B \-\-bin
instead of at the project root. By default the executable is built at the
project root
.RI ( ./ name ),
with objects under
.BR \-\-bin .
Applies to
.B make
and
.BR premake ;
.BR cmake ", " meson " and " xmake
always keep the executable in their build directory.
.TP
.B \-\-single
Generate a simplified
.B Makefile
for a project whose sources compile in one step: the sources are built straight
into the executable with no object directory, and
.B clean
removes only the binary. There is no
.B \-\-bin
or
.BR \-\-bin\-int .
Only for
.B make
with
.BR c ", " cpp " or " objc ,
and only for an executable.
.TP
.B \-\-no\-validation
Leave out the
.B check
target (which runs
.BR bear " and " cppcheck )
and the address and undefined sanitizer flags from the generated
.BR Makefile .
.TP
.B \-\-style
Add a
.B .clang-format
and
.B .editorconfig
matching the house style guide
.RB ( hachem.wtf/blabbing/style-guide ).
Only for
.BR c ", " cpp " and " objc .
.TP
.B \-\-ci
Add a
.B .github/workflows/ci.yml
GitHub Actions workflow that builds the project on every push and pull
request. Runs on
.B macOS
for
.BR objc ", " swift " and " nasm ,
and on
.B Linux
otherwise, installing whatever the runner does not already provide.
.TP
.BR \-\-bin " " \fIdir\fR
Build directory. The default depends on the build system:
.B bin
for
.B make
and
.BR premake ,
.B build
for
.BR cmake ,
and
.B builddir
for
.BR meson .
The final executable is written here.
.TP
.BR \-\-bin\-int " " \fIdir\fR
Compile object files into their own directory
.I dir
instead of alongside the executable in
.BR \-\-bin .
Applies only to
.B make
and
.BR premake .
By default objects and the executable share the
.B \-\-bin
directory.
.TP
.BR \-v ", " \-\-version
Print version and exit.
.TP
.BR \-h ", " \-\-help
Print a usage summary and exit.
.TP
.BR \-\-completions " " \fIshell\fR
Print a shell completion script for
.BR bash ", " zsh " or " fish
to standard output, then exit. Source it from the shell's startup file, or
install it where that shell looks for completions.
.SH "BUILD SYSTEMS"
.B make
and
.B premake
build objects into
.BR \-\-bin ,
or into
.B \-\-bin\-int
when it is given, and place the executable at the project root unless
.B \-\-no\-root
is set.
.BR cmake ", " meson " and " xmake
use a single out\-of\-source build directory named by
.BR \-\-bin ,
so
.B \-\-bin\-int
does not apply to them and is rejected if combined with either.
.PP
The generated
.B make
build files have a
.B run
target for executables, so
.B make run
builds and runs the program;
.B xmake
projects use
.B xmake run
instead.
.SH EXAMPLES
.TP
.B mkproj hello
A C project built with make.
.TP
.B mkproj \-l cpp \-s c++20 \-b cmake app
A C++20 project built with cmake.
.TP
.B mkproj \-b make \-\-bin\-int obj tool
A make project with objects compiled into
.BR obj/ .
.TP
.B mkproj \-\-src source quick
A project with its source under
.BR source/ ,
rather than the default flat layout.
.TP
.B mkproj .
Generate the project into the current directory, naming it after that
directory.
.TP
.B mkproj \-l crust hello
A Rust project built straight through
.B rustc
with make, no cargo.
.TP
.B mkproj \-k lib \-\-license mit libfoo
A static-library project with an MIT
.BR LICENSE .
.TP
.B mkproj \-k shared \-b cmake libbar
A shared-library project built with cmake.
.SH ENVIRONMENT
These set defaults that command-line options override:
.BR MKPROJ_LANG ", " MKPROJ_STD ", " MKPROJ_BUILD ", " MKPROJ_CC ", " MKPROJ_KIND
and
.BR MKPROJ_LICENSE .
.SH "EXIT STATUS"
.TP
.B 0
The project was generated.
.TP
.B 1
A usage error, or a file or directory could not be created.
.SH AUTHOR
hachem <im@hachem.wtf>