path: root/mkproj.1

.TH MKPROJ 1 "2026-09-12" "mkproj 0.2.0" "User Commands"
.SH NAME
mkproj \- dumb project generator
.SH SYNOPSIS
.B mkproj
.RI [ options ]
.I name
.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
.B src
directory with a stub
.IR main
(or the stub at the root, with
.BR \-\-flat ),
a build file for the chosen build system, a
.B .gitignore
and, unless disabled, an initialized git repository. The stub compiles
cleanly under a strict set of warnings with address and undefined
sanitizers enabled by default.
.SH OPTIONS
.TP
.BR \-l ", " \-\-lang " " \fIlang\fR
Source language:
.BR c ", " cpp ", " objc " or " nasm .
Default
.BR c .
.B nasm
projects are x86\-64 assembly and only support the
.B make
build system (executables only, no language standard).
.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
.B c17
for
.B c
and
.BR objc ,
and
.B c++23
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 or
.B lib
for a static library. A library gets a
.RI < name >.h
/
.RI < name >.c
pair with a stub function instead of a
.IR main .
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 \-\-no\-git
Do not initialize a git repository.
.TP
.B \-\-intermediate
Compile objects into a separate directory (see
.BR \-\-bin\-int ).
Only meaningful for
.B make
and
.BR premake .
.TP
.B \-\-flat
Flat layout: put the sources at the project root instead of in a
.B src
directory. Objects still build into the
.B \-\-bin
directory, so the tree stays a single level deep.
.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
Separate directory for intermediate object files. Implies
.BR \-\-intermediate ,
and applies only to
.B make
and
.BR premake .
Default
.BR bin\-int .
.TP
.B \-\-no\-clangd
Do not generate a
.B compile_flags.txt
for clangd, and do not add the clangd artifacts
.RB ( .clangd ", " compile_commands.json )
to
.BR .gitignore .
By default a
.B compile_flags.txt
with the project's flags is written so an editor's language server works before
the first build.
.TP
.BR \-v ", " \-\-version
Print version and exit.
.TP
.BR \-h ", " \-\-help
Print a usage summary and exit.
.SH "BUILD SYSTEMS"
.B make
and
.B premake
build objects and the executable into
.BR \-\-bin ,
or split objects into
.B \-\-bin\-int
when
.B \-\-intermediate
is given.
.BR cmake ", " meson " and " xmake
use a single out\-of\-source build directory named by
.BR \-\-bin ,
so
.B \-\-intermediate
and
.B \-\-bin\-int
do not apply to them and are rejected if combined with either.
.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 \-\-flat quick
A flat project: the source sits at the root, no
.B src
directory.
.TP
.B mkproj \-k lib \-\-license mit libfoo
A static-library project with an MIT
.BR LICENSE .
.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>