diff options
Diffstat (limited to 'mkproj.1')
| -rw-r--r-- | mkproj.1 | 248 |
1 files changed, 184 insertions, 64 deletions
@@ -1,4 +1,4 @@ -.TH MKPROJ 1 "2026-09-18" "mkproj 0.3.0" "User Commands" +.TH MKPROJ 1 "2026-09-20" "mkproj 0.4.0" "User Commands" .SH NAME mkproj \- dumb project generator .SH SYNOPSIS @@ -6,6 +6,9 @@ mkproj \- dumb project generator .RI [ options ] .I name .br +.B mkproj \-\-completions +.BR bash | zsh | fish +.br .B mkproj .BR \-v | \-h .SH DESCRIPTION @@ -21,28 +24,61 @@ 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 +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, unless disabled, an initialized git repository. The stub compiles +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 " or " nasm . +.BR c ", " cpp ", " objc ", " nasm ", " swift " or " crust . Default .BR c . .B nasm -projects are x86\-64 assembly and only support the +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 (executables only, no language standard). +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 @@ -51,16 +87,16 @@ for example .B c17 or .BR c++23 . -Must be valid for the chosen language. Defaults to -.B c17 +Must be valid for the chosen language. Defaults to the newest standard for +the language +.RB ( c2y for .B c and .BR objc , -and -.B c++23 +.B c++26 for -.BR cpp . +.BR cpp ). .TP .BR \-b ", " \-\-build " " \fIsystem\fR Build system to generate: @@ -71,15 +107,24 @@ Default .BR \-k ", " \-\-kind " " \fIkind\fR What to build: .B exe -for an executable or +for an executable, .B lib -for a static library. A library gets a +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 . -Default +.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 @@ -115,23 +160,18 @@ The copyright holder is taken from .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 . +.B \-\-git +Initialize a git repository and write a +.BR .gitignore . +By default neither is created. .TP -.B \-\-flat -Flat layout: put the sources at the project root instead of in a -.B src -directory. Objects still build into the +.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, so the tree stays a single level deep. +directory. .TP .B \-\-docker Add a @@ -153,6 +193,67 @@ the container targets Linux 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 @@ -170,51 +271,58 @@ for 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 +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 . -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. +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 and the executable into +build objects into .BR \-\-bin , -or split objects into +or into .B \-\-bin\-int -when -.B \-\-intermediate -is given. +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 \-\-intermediate -and .B \-\-bin\-int -do not apply to them and are rejected if combined with either. +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 @@ -227,14 +335,26 @@ A C++20 project built with cmake. 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 +.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 |